# NH투자증권 Open API — 공통 (Common: 인증·계좌) Overview

## 개요

이 문서는 특정 자산군(국내주식·해외주식·파생·채권·금현물)에 속하지 않는 **플랫폼 공통 API** 를 설명합니다. 두 API 로 구성됩니다.

1. **접근 토큰 발급** (`POST /oauth2/token`) — 앱키/앱시크릿으로 access token 을 발급받습니다. ⚠️ **운영(`api.n2plug.com`) 전용 — 모의투자 미제공.** 발급받은 토큰은 운영·모의투자 호출에 모두 사용할 수 있습니다.
2. **계좌 목록 조회** (`POST /n2/acctinfo`) — 자격증명에 연결된 보유 계좌번호 목록을 조회합니다.

> 기본 환경은 **운영(Live · `api.n2plug.com:8443`)** 이며 주문이 실제로 체결됩니다. 테스트·검증은 **모의투자(`moapi.n2plug.com:8443`)** 를 사용하세요.

이 두 API 는 모든 조회·주문의 **선행 단계**입니다. 자산군 API(잔고·주문 등)는 계좌번호(`act_no`)를 입력으로 요구하는데, 그 계좌번호를 얻는 경로가 바로 `/n2/acctinfo` 입니다.

## 인증 방식

- **토큰 발급**: `/oauth2/token` 에 쿼리 파라미터(`appkey`, `appsecretkey`, `grant_type=client_credentials`, `scope=oob`)로 요청. Content-Type 은 `application/x-www-form-urlencoded`.
- **이후 모든 REST 호출**: 헤더에 `Authorization: Bearer {access_token}` + `x-client-id`(앱키) + `x-client-secret`(앱시크릿).

> 🔑 **토큰 재사용 필수** — access token 은 **24시간(`expires_in=86400`) 유효**합니다. 매 호출마다 재발급하지 말고 **프로세스 간 공유 캐시(파일 등)** 에 저장해 재사용하세요. 재발급은 보안 알림을 유발합니다. **재발급은 `401`(토큰 무효)일 때만** 하고, `429`(유량 초과) 재시도에는 기존 토큰을 그대로 사용하세요.
>
> 권장 흐름: `캐시 확인 → 유효하면 재사용 → 만료/401 일 때만 재발급 → 캐시 갱신`


## 봉투 규약

- `/n2/acctinfo` 는 다른 REST API 와 동일하게 요청 `Input_0` / 응답 `Output_0`(+`Output_1` …) 봉투를 사용합니다.
- 응답 공통 봉투: `rsp_cd`(응답코드, `00000`=정상), `rsp_msg`(응답메시지), `cust_no`(고객번호).
- `/oauth2/token` 은 예외적으로 봉투를 쓰지 않고 `access_token` 을 직접 반환합니다.

## 전형적 흐름

```
1) POST /oauth2/token           → access_token 획득
2) POST /n2/acctinfo            → Output_0[].acct_no 목록 획득
3) POST /krstock/inquiry/v1/balance (act_no = 위 acct_no)  → 잔고
   POST /krstock/order/v1/cashBuy   (act_no = 위 acct_no)  → 매수 주문
```

## 종목마스터 파일 (Instruments)

> ⚠️ **전 종목 목록·종목명·업종을 조회하는 REST API 는 없습니다.** 종목 정적정보는 아래 마스터 파일을 사용하세요.

전 종목의 코드·종목명·업종·지수편입 여부 등 **정적 종목정보**는 **종목마스터 파일(.mst)** 로 제공합니다. 총 **28종**(국내주식·해외주식·국내선물옵션·해외파생·장내채권).

- **다운로드**: `https://www.n2plug.com/instruments/<파일명>.mst` — **인증 불필요**(토큰·헤더 없이 공개 다운로드)
- **구조체 정의**(오프셋·길이·코드값·레코드크기): `https://www.n2plug.com/instruments/<파일명>.h` — 마스터 파일과 **1:1 대응**(예: `m_new_stock.mst` → `m_new_stock.h`). **인증 불필요**

### 파일 공통 형식

- 인코딩 **CP949** (UTF-8 아님)
- **고정 길이** 레코드. 파일 헤더 없음(0번 오프셋부터 첫 레코드)
- 좌측정렬 + 공백(`0x20`) 우측 패딩 → 길이 기반 슬라이싱 후 우측 공백 제거
- 레코드 끝 1바이트 **LF(`0x0A`)**. CRLF 아님
- 반드시 **바이너리 모드(`"rb"`)로 열 것**
- **`파일크기 % 레코드크기 == 0` 을 먼저 검증**할 것

### 주요 마스터

| 구분 | 마스터 파일 | 구조체 정의 |
|---|---|---|
| 국내주식 | `m_new_stock.mst` | `m_new_stock.h` |
| 해외주식 | `m_gtsstock.mst` | `m_gtsstock.h` |
| 지수옵션 | `m_optksp.mst` | `m_optksp.h` |
| 주식선물 | `m_stkfut.mst` | `m_stkfut.h` |
| 장내채권 | `bond_hts.mst` | `bond_hts.h` |

### 파싱 주의

- 지수옵션 `sPrice` 는 **실제 행사가 × 100** → `/100` (주식옵션 `m_optstp` 의 `sValue` 는 스케일 없음)
- 위클리옵션 `sMonth` 는 **YYMMWW(주차)** — 날짜로 파싱 금지
- 콜/풋 구분은 **CP949 한글 2바이트**(`"콜"`/`"풋"`)
- 지수 편입 플래그는 **`== "Y"` 로만** 판정
- 국내주식 한글종목명 선두 1바이트는 지수 마커(`*` KOSPI200 / `#` 코스닥150) — 정렬·검색 시 제거

> 금현물은 마스터 파일이 없고 전문(`IVOGLDREQ01`)으로 조회합니다.

## 참고

- `acct_no`(계좌목록 응답) 와 `act_no`(잔고·주문 입력) 는 필드명이 다르지만 **값은 동일**합니다.
- **계좌구분코드 `acct_type` — 사용 도메인이 결정됩니다.**

| `acct_type` | 용도 | 사용 도메인 |
|---|---|---|
| `01` | 🔴 운영 (Live) — 일반 | `https://api.n2plug.com:8443` |
| `02` | 🔴 운영 (Live) — 주문대리인 | `https://api.n2plug.com:8443` |
| `03` | 🟢 모의투자 (Mock) | `https://moapi.n2plug.com:8443` |

  계좌 목록에는 여러 구분의 계좌가 함께 내려옵니다. 호출하려는 환경과 **같은 구분의 계좌**를 사용하세요.