AI 코딩 도구로 연동하기

[빌링플러스(BillingPlus) 공개 API 연동 규격 — 이 내용에 없는 항목은 추측하지 말고 나에게 물어볼 것]

1. 기준 주소: https://api.billingplus.co.kr/api/v1
   - 요청·응답 UTF-8 JSON. 금액은 원 단위 정수. 시간은 ISO-8601 + 오프셋(+09:00).
   - 카드번호를 보내는 API 는 없다. 카드 등록은 등록창(팝업)·가입 링크·빌링플러스 화면으로만 한다.

2. 인증 헤더(모든 요청)
   X-BillingPlus-Key: API 키(bpk_live_…)
   X-BillingPlus-Timestamp: 유닉스 시간(초). 서버 시각과 ±5분 안
   X-BillingPlus-Nonce: 요청마다 새 난수(32자 16진수 권장, 16~128자). 재사용 금지
   X-BillingPlus-Signature: hex(HMAC-SHA256(시크릿 키, 서명 문자열)), 소문자 64자
   서명 문자열 = METHOD + "\n" + 경로와쿼리 + "\n" + timestamp + "\n" + nonce + "\n" + sha256hex(본문 바이트)
   - METHOD 는 대문자. 경로는 도메인을 뺀 /api/v1/… 부터, 쿼리스트링이 있으면 보내는 그대로 포함.
   - 본문이 없으면 sha256hex("") = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
   - 서명한 본문 바이트를 그대로 보낸다(다시 직렬화하지 않는다).
   - 시크릿 키는 환경변수에서 읽는다. 코드·로그·브라우저에 넣지 않는다.
   - 인증 실패는 이유와 상관없이 401 UNAUTHORIZED. 연동 확인은 GET /api/v1/ping.

3. 멱등키
   - 모든 POST 에 Idempotency-Key 헤더 필수(200자 이하). 없으면 400 IDEMPOTENCY_KEY_REQUIRED.
   - 업무 한 건마다 키를 한 번 만들어 저장하고, 재시도할 때는 같은 키를 쓴다(서명·nonce·timestamp 는 새로).
   - 같은 키 + 같은 요청 → 처음 응답을 그대로 돌려준다(헤더 Idempotent-Replay: true, 24시간 보관).
   - 같은 키가 처리 중 → 409 REQUEST_IN_PROGRESS + Retry-After.
   - 같은 키로 다른 본문·경로·메서드 → 422 IDEMPOTENCY_KEY_REUSED.
   - 5xx 응답은 저장되지 않으므로 같은 키로 다시 보내도 된다.
   - 예외: 등록창 생성(POST /api/v1/register-windows) 재요청은 창의 지금 상태를 돌려준다. 안 열린 창이면 새 window_url
     (window_url_reissued: true, 앞 주소 무효), 열린·만료·사용된 창이면 window_url 이 null.

4. 에러와 결제 결과
   - 에러 본문: {"error": {"code": "...", "message": "...", "detail": {...}, "request_id": "req_..."}}
     응답 헤더 X-Request-Id 에도 request_id 가 있다. 분기는 code 로 한다(message 문구는 바뀔 수 있다).
   - code: UNAUTHORIZED(401) FORBIDDEN_IP(403) INVALID_REQUEST(400) IDEMPOTENCY_KEY_REQUIRED(400)
     IDEMPOTENCY_KEY_REUSED(422) REQUEST_IN_PROGRESS(409) NOT_FOUND(404) RATE_LIMITED(429)
     UNPROCESSABLE(422, detail.reason 이 있을 수 있음) INTERNAL_ERROR(500/503)
   - 결제 거절은 에러가 아니다. 200 응답의 payment.status 로 판단한다:
     APPROVED 승인 / FAILED 거절(failure_reason 은 빌링플러스 표준 사유) /
     UNKNOWN 미확정 — 실패로 처리하지 말고 재승인하지 말 것. 결제 조회나 웹훅으로 확정을 기다린다.
   - 429 이면 Retry-After 초만큼 기다린다. 목록은 커서 방식(cursor, limit 기본 20·최대 100,
     응답 page.next_cursor · page.has_more).

5. 웹훅(빌링플러스 → 우리 서버, POST, JSON)
   - 봉투: {"event_id": "...", "event": "payment.approved", "occurred_at": "...", "data": {...}}
   - 헤더: X-BillingPlus-Event, X-BillingPlus-Event-Id, X-BillingPlus-Timestamp, X-BillingPlus-Signature
   - 검증: hex(HMAC-SHA256(웹훅 시크릿, timestamp + "." + 받은 본문 바이트)) 를 서명 헤더와
     상수 시간 비교한다. 본문은 파싱 전 원문 바이트를 쓴다. timestamp 가 ±5분 밖이면 거부해도 된다.
   - 2xx 로 10초 안에 응답한다. 오래 걸리는 처리는 큐로 넘기고 먼저 2xx.
   - 순서 보장 없음 · 중복 도착 가능. event_id 로 한 번만 처리한다(재발송돼도 event_id 는 같다).
   - 실패하면 최대 8회 다시 보낸다. 카드번호·연락처 값은 웹훅에 없다. 상세 값은 API 로 다시 조회한다.

결제 성공 웹훅(payment.approved)을 받아 우리 서비스의 이용권을 갱신하는 코드를 작성해 주세요.
서명 검증과 중복 이벤트 처리(event_id)를 포함하고, 처리는 큐로 넘긴 뒤 먼저 200 을 돌려주세요.
웹훅 본문의 customer_code 로 우리 회원을 찾습니다. 문서에 없는 항목은 추측하지 마세요.

위 규격대로 빌링플러스 API 를 호출하는 클라이언트 함수를 Node.js 로 만들어 주세요.
서명 계산, 요청마다 새 nonce, POST 의 Idempotency-Key 를 호출하는 쪽에서 받도록 하고,
429 와 409 는 Retry-After 만큼 기다렸다 같은 멱등키로 다시 보내게 해 주세요.
GET /api/v1/ping 을 부르는 사용 예도 붙여 주세요. 시크릿은 환경변수에서 읽습니다.

회원이 동의한 수시결제 동의(charge-consents)로 POST /api/v1/charge-consents/{id}/charges 를 불러
결제하는 서버 함수를 Python 으로 만들어 주세요. 주문마다 멱등키를 한 번 만들어 DB 에 저장하고,
응답의 payment.status 가 APPROVED·FAILED·UNKNOWN 일 때 각각 어떻게 처리할지 나눠 주세요.
UNKNOWN 은 실패로 처리하지 말고 확정을 기다리게 하고, 422 의 detail.reason 은 그대로 기록해 주세요.

가맹점 서버가 POST /api/v1/register-windows 로 등록창을 만들고, 브라우저가 window_url 을 팝업으로
여는 코드를 만들어 주세요. 팝업 차단을 피하도록 클릭 즉시 빈 창을 먼저 열고, 완료 메시지는
event.origin 을 확인한 뒤 받으세요. 등록 완료는 서버에서 GET /api/v1/register-windows/{id} 로
다시 확인합니다. 시크릿 키가 브라우저 코드에 들어가지 않게 해 주세요.