입고 연동

상품 1종 100개의 입고를 요청하고, 창고가 기록한 수량을 확인한 뒤 입고 완료 수량을 조회하는 예제입니다. 부분 완료 수량과 입고 요청 전체의 종료는 따로 확인합니다. 각 개념의 차이는 도착과 입고에서 먼저 살펴볼 수 있습니다.

시작 전: 연결 준비에서 첫 조회를 확인하고, Maybox 담당자와 테스트 상품·수량 및 창고 작업 일정을 맞추세요. 각 JSON을 표시된 파일명으로 저장하고 후속 요청에는 실제 응답 ID를 사용합니다.

전체 흐름

고객사 · 요청: SKU를 등록하고 입고 예정 수량을 제출합니다. 응답의 inboundId를 고객사 시스템의 입고 ID와 연결해 저장합니다.
창고 · 작업: 도착한 상품을 확인하고 입고 수량을 기록한 뒤 고객사에 내용 확인을 요청합니다.
고객사 · 확인: 입고 상세를 조회하고, 창고가 확인을 요청한 버전의 수량·실측 결과를 검토한 뒤 입고 등록 내용 확인 API를 호출합니다.
창고 · 입고 처리 / 고객사 · 조회: 완료된 수량부터 재고에 반영됩니다. 고객사는 입고 완료 수량과 입고 종료 여부를 함께 조회하고, 현재고와 새로 예약할 수 있는 수량은 재고 API로 확인합니다.

상품 등록

sku.json:

{
  "sku": "DEMO-SERUM-001",
  "skuName": "데모 세럼 30ml",
  "brandName": "데모 브랜드"
}

curl --fail-with-body --silent --show-error \
  --request POST --data-binary @sku.json --config - <<EOF
url = "${MAYBOX_API_ORIGIN}/api/v1/skus"
header = "Authorization: Bearer ${MAYBOX_API_CREDENTIAL}"
header = "Content-Type: application/json"
header = "Idempotency-Key: demo-sku-20261113-001-create"
EOF

성공 응답 예시:

{ "skuId": "1001" }

다음 단계: 응답의 skuId를 저장합니다. 입고 요청에서는 같은 상품의 고객사 식별자인 sku를 사용합니다.

이미 등록된 SKU이면 409 SKU.ALREADY_EXISTS입니다. GET /api/v1/skus?sku=DEMO-SERUM-001로 조회한 뒤 해당 skuId를 사용합니다. 입출고 요청의 skuName·brandName은 창고 작업자가 확인하는 생성 시점 정보이므로, 요청에도 표시할 값을 함께 보냅니다.

입고 예정 수량 제출

inbound.json:

{
  "externalReference": "DEMO-INBOUND-20261113-001",
  "expectedDate": "2026-11-19T15:00:00.000Z",
  "note": "테스트 입고 연동 확인",
  "lines": [
    {
      "sku": "DEMO-SERUM-001",
      "skuName": "데모 세럼 30ml",
      "brandName": "데모 브랜드",
      "expectedQuantity": 100,
      "productBarcodes": ["8801234567890"],
      "requestsUnitMeasurement": false,
      "requestsCartonMeasurement": false,
      "pendingAutoReservationQuantity": 0
    }
  ]
}

curl --fail-with-body --silent --show-error \
  --request POST --data-binary @inbound.json --config - <<EOF
url = "${MAYBOX_API_ORIGIN}/api/v1/inbounds"
header = "Authorization: Bearer ${MAYBOX_API_CREDENTIAL}"
header = "Content-Type: application/json"
header = "Idempotency-Key: demo-inbound-20261113-001-create"
EOF

성공 응답 예시:

{ "inboundId": "2001" }

여기서 창고 작업을 기다립니다. inboundId를 저장하고 창고가 도착한 상품의 수량을 기록하는지 확인합니다. 변경 알림을 받거나 입고 상세를 다시 조회해 진행 상황을 확인할 수 있습니다.

같은 입고 요청에 동일 SKU를 중복할 수 없습니다. productBarcodes는 SKU 행별 최대 1개입니다. 예제에서는 자동 예약을 사용하지 않고, 입고 완료 수량을 확인한 뒤 필요한 수량을 별도로 예약합니다. 자동 예약을 사용하려면 pendingAutoReservationQuantity에 앞으로 입고와 함께 예약할 수량을 지정합니다. 예정 수량이나 이 지시만으로 현재고·예약 수량이 늘지는 않습니다.

입고 결과 조회와 등록 확인

export MAYBOX_INBOUND_ID='2001'

curl --fail-with-body --silent --show-error --config - <<EOF
url = "${MAYBOX_API_ORIGIN}/api/v2/inbounds/${MAYBOX_INBOUND_ID}"
header = "Authorization: Bearer ${MAYBOX_API_CREDENTIAL}"
EOF

MAYBOX_INBOUND_ID에는 실제 생성 응답을 설정합니다. 조회 결과에서 다음 항목을 사용합니다.

항목	의미
`status`	입고를 진행 중인 `OPEN`, 또는 종료한 `CLOSED`
`lines[].expectedQuantity`	고객사가 예정한 수량
`lines[].registeredQuantity`	창고에서 등록한 수량. 아직 입고 완료되지 않은 수량도 포함
`lines[].completedQuantity`	해당 입고의 입고 완료 수량. 현재 SKU 재고와는 다름
`registrationRevision`	입고 등록 내용의 버전 번호
`registrationConfirmationRequest`	창고의 등록 확인 요청. 요청이 없으면 `null`
`registrationConfirmation`	고객사가 확인한 버전 번호와 시각. 미확인이면 `null`

확인 API를 호출할 수 있는지 판단

버전 번호는 고객사가 검토한 내용과 확인하려는 내용이 같은지 구분하는 값입니다. 등록 내용 확인과 버전 번호에서 그 관계를 설명합니다.

아래는 창고가 입고 수량 100개를 기록하고 고객사에 내용 확인을 요청한 상태입니다. 등록 내용의 버전 번호(registrationRevision)는 3입니다. 응답에서 확인에 필요한 항목만 보여줍니다.

{
  "inboundId": "2001",
  "status": "OPEN",
  "registrationRevision": 3,
  "registrationConfirmationRequest": {
    "registrationRevision": 3,
    "requestedAt": "2026-11-13T01:00:00.000Z"
  },
  "registrationConfirmation": null,
  "lines": [
    {
      "sku": "DEMO-SERUM-001",
      "expectedQuantity": 100,
      "registeredQuantity": 100,
      "completedQuantity": 0
    }
  ]
}

현재 버전에 확인 요청이 있고 아직 확인하지 않았다면: 수량·상품·실측 결과를 검토하고 같은 버전 번호로 확인 API를 호출합니다. 예제는 등록 수량 100개, 입고 완료 수량 0개입니다.
확인 요청이 없거나 요청의 버전 번호가 현재 버전과 다르다면: 자동으로 확인 API를 호출하지 않습니다. 최신 상태를 다시 조회하고 창고 담당자와 진행 상황을 확인합니다.
이미 현재 버전의 내용을 확인했다면: 확인 요청을 새 업무로 반복하지 않고 입고 완료 수량을 조회합니다.

다음은 창고가 요청한 등록 내용을 확인하는 예제입니다. 연결 전에 대상 환경의 입고 확인 방식을 Maybox 담당자와 확인합니다.

registration-confirmation.json:

{
  "registrationRevision": 3,
  "note": "등록 수량과 상품을 확인했습니다"
}

curl --fail-with-body --silent --show-error \
  --request POST --data-binary @registration-confirmation.json --config - <<EOF
url = "${MAYBOX_API_ORIGIN}/api/v2/inbounds/${MAYBOX_INBOUND_ID}/registration-confirmation"
header = "Authorization: Bearer ${MAYBOX_API_CREDENTIAL}"
header = "Content-Type: application/json"
header = "Idempotency-Key: demo-inbound-20261113-001-confirm-revision-3"
EOF

registrationRevision에는 직전 조회값을 넣습니다. 등록 내용이 바뀌면 409 INBOUND.REGISTRATION_CHANGED가 발생하므로 최신 결과를 다시 조회하고 확인 여부를 재판단합니다. 웹훅 수신 자체가 등록 확인을 뜻하지 않습니다.

입고 완료 수량과 종료 확인

다음 작업은 창고의 입고 처리입니다. 고객사 확인 성공을 입고 완료로 취급하지 않습니다. 입고 상세의 lines[].completedQuantity로 완료 수량을 확인합니다. 창고에서는 상품을 보관 위치에 넣고 적재 수량을 저장할 때 해당 수량이 재고에 반영됩니다.

다음은 등록한 100개 중 60개의 입고가 먼저 완료된 시점의 응답 일부입니다. 전체 응답에는 다른 필드도 포함됩니다.

{
  "inboundId": "2001",
  "status": "OPEN",
  "closedAt": null,
  "lines": [
    {
      "sku": "DEMO-SERUM-001",
      "expectedQuantity": 100,
      "registeredQuantity": 100,
      "completedQuantity": 60
    }
  ]
}

60개 입고 완료, 요청 진행 중: 완료된 60개는 이미 현재고에 반영됐습니다. 남은 등록 수량 40개는 아직 입고 처리 중입니다.
100개 입고 완료, 요청 진행 중: 나머지 40개도 완료되면 completedQuantity는 100이 됩니다. 이때도 요청은 OPEN일 수 있습니다.
입고 종료: 이번 요청의 처리를 마치면 CLOSED가 됩니다. 종료 자체가 재고를 다시 늘리지는 않습니다. 100개 중 60개만 도착한 별도 상황에서는 도착 수량의 차이를 확인하고 모두 처리한 뒤 60개로 종료할 수도 있습니다.

GET /api/v1/stock?sku=DEMO-SERUM-001로 SKU의 현재고와 가용 수량을 별도로 확인합니다. 입고 완료 수량은 해당 입고의 실적이고, 현재고에는 다른 입출고와 재고 정정도 반영됩니다. 입고와 함께 자동 예약을 사용했다면 입고 완료 수량 전부를 새로 예약할 수 있는 것은 아닙니다.

이 가이드의 완료 기준: 고객사 시스템의 상품·입고 번호와 Maybox ID의 연결 관계를 저장하고, 등록 내용 확인·입고 완료 수량·입고 종료를 구분해 조회할 수 있습니다.

이후 출고 연동에서 최신 가용 수량을 확인하고 필요한 수량을 예약합니다. 변경을 자동 수신하려면 웹훅을 연결하세요. 전체 필드는 API 레퍼런스에서 확인할 수 있습니다.