규약

금액과 용량은 문자열

{
  "balance": "124.30",
  "currency": "USD"
}
{
  "purchased_gb": "25.000",
  "used_gb": "2.566",
  "left_gb": "22.434"
}

float가 아니라 decimal로 파싱하세요. 통화는 USD입니다. 1기가바이트 = 10^9바이트.

시간

오프셋을 명시한 ISO-8601, 항상 UTC: 2026-08-28T14:03:11+00:00.

확장 가능한 열거형

주문 상태, 거래 유형, 이벤트 유형, 패키지 상태, kind, family는 v1 안에서 예고 없이 값이 추가됩니다 - 모르는 값을 만나도 문제없이 처리해야 합니다. 필터에서 모르는 값은 “필터 없음”으로 처리됩니다.

페이지네이션

파라미터	의미
offset	건너뛸 행 수. 기본값 0
limit	1..200, 기본값 50(GET /api/v1/packages는 200)

두 값 모두 거부되지 않고 범위에 맞게 잘리며, 잘린 값이 본문에 그대로 돌아옵니다. 응답에는 total이 있습니다.

GET /api/v1/orders?limit=100&offset=100
    -> { "orders": [...], "total": 317, "offset": 100, "limit": 100 }

새 행이 계속 추가되는 목록에서 offset은 위치를 가리킵니다: 전체를 내려받을 때는 id로 중복을 제거하세요. 정렬 순서는 고정입니다 - 최신순.

이벤트 로그는 다르게 읽습니다: ?after=<id>, 응답에 next_after가 있습니다.

멱등성

금액이 차감되는 작업은 헤더가 필요합니다: POST /api/v1/packages(구매), POST /api/v1/packages/{id}/topup(트래픽 추가), POST /api/v1/packages/{id}/prolong (주소 연장).

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

최대 255자의 문자열이며, 앞뒤 공백은 제거됩니다.

같은 키와 같은 본문으로 재시도하면 같은 응답이 돌아옵니다. 키는 요청 전에 생성하고, 타임아웃 후 재시도를 포함해 재시도할 때 다시 사용하세요.

키는 24시간 동안 기억됩니다: 하루가 지난 뒤 같은 키는 새 작업을 시작합니다.

오류:

• 422 - idempotency_key_required(헤더 없음), idempotency_key_invalid(비어 있거나 255자 초과), idempotency_key_reused(같은 키에 다른 본문)
• 409 - idempotency_in_progress(이전 요청이 아직 실행 중 - 잠시 후 같은 키로 다시 시도하세요)
• 500 - operation_indeterminate(결과가 확정되지 않은 작업의 키로 재시도함 - 오류 참고)

지역 카탈로그 캐시

지역 카탈로그의 각 단계는 ETag를 반환합니다 - 카탈로그 버전의 불투명한 해시입니다. 이 값을 If-None-Match로 보내면 본문 없이 304를 받습니다. 같은 버전을 읽을 수 있는 형태로 담은 것이 본문의 version 필드입니다.

버전 관리

v1에서 예고 없이 출시되는 변경: 응답의 새 필드, 새 선택 파라미터, 확장 가능한 열거형의 새 값, 새 엔드포인트, 기존 상태 코드의 새 오류 코드.

새 버전에서만 하는 변경: 필드 삭제 또는 이름 변경, 타입 축소, 요청의 새 필수 필드, 문서화된 경우의 상태 코드나 오류 코드 변경, 기본값 변경.

지원 중단: Deprecation과 Sunset 헤더, 종료까지 최소 6개월.