인증과 공통 규칙

인증

모든 API 요청에 Authorization: Bearer <credential> 헤더로 API 인증 정보를 보냅니다. 인증 정보는 고객사 하나에 고정되며, 요청에서 tenantId를 선택하지 않습니다. 고객사 서버에서 호출하고 인증 정보는 비밀 관리 도구로 보관합니다. 발급과 설정은 연결 준비를 참고하세요.

경로와 버전

현재 연동에는 v1과 v2를 함께 사용합니다. v2가 v1의 모든 기능을 대체하지는 않습니다.

목적	경로
상품, 입고 요청 생성·수정, 재고·예약, 출고, 이벤트 복구	/api/v1
입고 결과 조회·등록 확인, 도착, 조건별 현재고, 실측	/api/v2

예를 들어 입고는 POST /api/v1/inbounds로 만들고 GET /api/v2/inbounds/{inboundId}로 결과를 읽습니다.

식별자와 업무 참조

• Maybox ID는 "1001"처럼 양의 10진수 문자열입니다. JavaScript number로 변환하지 않고 문자열로 보관합니다.
• sku는 고객사가 정한 상품 코드이며 대소문자를 구분합니다. 상품 카탈로그의 Maybox ID인 skuId와 다릅니다.
• externalReference에 고객사의 입고 요청 번호나 주문·출고 번호를 넣을 수 있습니다. 생성 후에는 바꿀 수 없으며 고유값 제약은 없습니다.
• 같은 externalReference가 여러 요청에 있을 수 있으므로, 생성 응답의 inboundId·outboundId와 고객사 업무 ID의 대응 관계를 저장합니다.

중복 요청 방지

상태를 변경하는 API는 중복 처리를 방지하는 멱등 키(Idempotency-Key) 헤더가 필요합니다. 입고 생성이나 수량 예약처럼 한 번 처리할 업무 요청마다 새 키를 만들고, 같은 요청을 재시도할 때는 같은 키와 같은 입력을 유지합니다. 키는 공백·제어 문자가 없는 출력 가능 ASCII이며 최대 255자입니다.

Idempotency-Key: demo-outbound-20261113-001-create

같은 호출자가 같은 키와 같은 업무 입력으로 재시도하면 처음 성공했을 때의 HTTP 상태 코드와 응답 본문을 다시 반환합니다. 같은 키를 다른 업무나 입력에 사용하면 422 IDEMPOTENCY.KEY_CONFLICT입니다. 키에 대응하는 성공 기록은 24시간 보존되며, 보존 기간이 지나면 같은 키도 새 요청으로 처리될 수 있습니다.

타임아웃이나 응답 유실 후 새 키로 다시 생성하면 중복 업무가 생길 수 있습니다. 같은 키로 확인·재시도하고, 보존 기간을 넘겼다면 저장한 ID와 목록 조회로 기존 생성 여부를 대조합니다. externalReference는 중복 요청 방지 키를 대신하지 않습니다.

이 문서의 예시 키는 한 번의 시나리오용입니다. 시나리오를 새로 시작할 때는 키도 새로 만듭니다. 예약과 출고 생성처럼 서로 다른 API 호출에는 각각 다른 키를 사용합니다.

응답과 페이지네이션

성공 응답은 결과를 별도 data 객체로 감싸지 않습니다. 생성 API는 일반적으로 201과 생성 ID를 반환합니다. 생성 성공은 업무 요청이 접수되었다는 뜻이며, 창고 작업의 완료 여부는 조회 API로 확인합니다.

일반 목록은 items와 nextCursor를 반환합니다. 커서(cursor)는 다음 목록 조회를 이어갈 때 그대로 전달하는 값입니다. 다음 페이지는 응답의 nextCursor를 cursor로 보내며, null이면 마지막입니다. 기본 크기는 50, 최대 100입니다. 커서를 해석하거나 직접 만들지 않습니다.

GET /api/v1/stock의 선택 SKU 조회는 sku를 반복해 최대 100개를 지정하며 cursor·limit·재고 필터를 함께 보내지 않습니다. 이벤트 복구 API는 별도의 after·hasMore 규칙을 사용합니다.

시각과 단위

createdAt·occurredAt 같은 시각과 입고·인계 예정일은 UTC ISO 8601 문자열을 사용합니다. 예정일은 창고 현지 날짜의 자정을 UTC로 변환합니다. 예를 들어 서울 기준 2026년 11월 20일은 2026-11-19T15:00:00.000Z입니다. 웹훅 서명용 timestamp 헤더는 Unix 초 문자열입니다.

치수는 mm, 무게는 g, 수량은 정수입니다. 조건별 현재고 API의 유통기한 필터·내역은 해당 API에서 정한 서울 기준 YYYY-MM-DD 형식을 사용합니다.