사용량 API 연동

부트페이의 사용량 질문에 금액으로 답하는 엔드포인트를 만들어요.

사용량 API는 부트페이가 가맹점 서버를 호출하는 방향이에요. 웹훅처럼 가맹점이 엔드포인트를 열어두면, 회차 결제 전에 부트페이가 청구 대상 회차 목록을 보내고 가맹점은 각 회차의 금액을 응답해요.

구독 템플릿의 usage_api_url에 이 엔드포인트 주소를 등록해요.

호출 시점

결제 예정일이 다가오면(약 7일 전부터) 부트페이가 조회를 시작해요.
아직 확정되지 않았거나 이전 조회가 실패한 회차가 대상이에요.
같은 프로젝트·같은 URL의 회차는 한 요청에 묶여서 올 수 있어요 — 응답도 배열로 돌려줘요.

요청 (Bootpay → 가맹점)

usage_api_url로 JSON POST가 와요.

{
  "bills": [
    {
      "order_subscription_id": "6650f1a2b3c4d5e6f7a8b9c0",
      "order_subscription_bill_id": "6650f1a2b3c4d5e6f7a8b9c1"
    },
    {
      "order_subscription_id": "6650f1a2b3c4d5e6f7a8b9c2",
      "order_subscription_bill_id": "6650f1a2b3c4d5e6f7a8b9c3"
    }
  ]
}json

파라미터	타입	필수	설명
`bills`	Array	필수	청구액을 확정할 회차 목록
`bills[].order_subscription_id`	String	필수	구독 계약 ID
`bills[].order_subscription_bill_id`	String	필수	회차 ID — 응답에서 이 값으로 짝을 맞춰요

응답 (가맹점 → Bootpay)

HTTP 200 + JSON 배열로 응답해요. 배열이 아니거나 200이 아니면 실패로 처리돼요.

[
  {
    "order_subscription_bill_id": "6650f1a2b3c4d5e6f7a8b9c1",
    "price": 132000,
    "tax_free_price": 0,
    "quantity": 1200,
    "one_unit_price": 110,
    "usage_items": [
      {
        "item_code": "api_call",
        "item_name": "API 호출",
        "unit_price": 110,
        "quantity": 1200,
        "price": 132000
      }
    ]
  }
]json

필드	타입	필수	설명
`order_subscription_bill_id`	String	필수	요청으로 받은 회차 ID 그대로
`price`	Integer	필수	이 회차에 청구할 최종 금액
`tax_free_price`	Integer	선택	최종 금액 중 비과세 금액
`quantity`	Integer	선택	총 사용량 (기본 1)
`one_unit_price`	Integer	선택	단가
`one_unit_tax_free_price`	Integer	선택	단가 중 비과세
`origin_price`	Integer	선택	할인 전 원금액
`origin_tax_free_price`	Integer	선택	할인 전 비과세 금액
`usage_items`	Array	선택	사용량 상세 내역 — 고객 안내·정산 근거로 저장돼요
`item_code`	String	선택	과금 항목 코드
`item_name`	String	선택	과금 항목 이름
`unit_price`	Integer	선택	항목 단가
`quantity`	Integer	선택	항목 사용량
`price`	Integer	선택	항목 금액
`tax_free_price`	Integer	선택	항목 비과세 금액
`usage_summary`	Object	선택	요약 — 생략하면 usage_items 기준으로 자동 생성돼요

응답 배열에 없는 회차는 금액이 갱신되지 않은 채 조회 완료로 처리돼요. 요청에 온 회차는 빠짐없이 배열에 담아 응답하는 걸 권장해요.

실패와 재시도

상황	처리
HTTP 200이 아닌 응답	해당 회차 조회 실패 처리 후 다음 스케줄에 재시도
응답이 JSON 배열이 아님	위와 동일
타임아웃·네트워크 오류	위와 동일

결제 예정일까지 조회가 계속 실패하면 회차 금액을 확정할 수 없어요. 사용량 API는 멱등하게(같은 회차에 같은 금액을 응답) 구현하고, 5xx 없이 빠르게 응답하도록 유지해요.

요청 body의 bills 배열 순회 — 단건이 아니라 복수 회차가 올 수 있어요.
회차 ID 기준으로 사용량을 집계하는 조회 키를 미리 설계해요 (계약 ID ↔ 내 서비스 계정 매핑).
응답 금액은 정수(원 단위)예요.
집계 마감 전에 호출이 올 수 있으니, "조회 시점까지의 확정 사용량"을 응답하는 기준을 정해요.

호출 시점

요청 (Bootpay → 가맹점)

응답 (가맹점 → Bootpay)

실패와 재시도

관련 문서