연결 준비와 첫 호출

처음 연결하는 개발자를 위한 가이드입니다. 고객사 연동 계정과 테스트 범위를 협의한 뒤, 데이터를 변경하지 않는 재고 조회로 API 연결을 확인합니다.

아직 계정이 없다면 아래 요청 항목을 Maybox 담당자에게 전달하세요. 접속 주소와 API 인증 정보를 받았다면 예제 실행 준비로 이동하세요. 먼저 큰 흐름을 읽고 싶다면 전체 업무 흐름을, 개념의 뜻과 규칙을 찾으려면 핵심 개념을 참고하세요.

계정과 테스트 범위 요청

이 문서를 전달받은 Maybox 담당자에게 다음 항목을 회신해 주세요. 담당자를 모르면 고객사 내 연동 협의 담당자를 통해 Maybox 연락 창구를 확인합니다.

고객사명 / 연동할 시스템:
기술 담당자 / 회신받을 연락처:
연결할 업무: 상품·입고 / 재고·출고 / 웹훅 / 기타
예상 데이터량과 호출 빈도:
희망 테스트 일정:
웹훅 사용 여부 / 수신 URL 준비 여부:
창고 작업을 함께 확인할 담당자:

Maybox 담당자와 테스트 환경의 제공 방식·접속 주소·사용 기간, 테스트 데이터와 창고 작업 진행 방법을 협의합니다. 입고·출고를 끝까지 검증하려면 실제 창고 작업을 누가 언제 진행할지도 맞춰야 합니다.

API 키와 연동 계정

연동 계정(Service Principal)은 고객사 시스템이 API를 호출할 때 사용하는 계정입니다. 이 계정의 API 인증 정보(credential)를 발급받아 요청 헤더에 보냅니다. 다른 서비스의 API 키·접근 토큰에 해당하는 값이며, Maybox 담당자에게 발급을 요청합니다.

API 인증 정보는 고객사 하나에 고정됩니다. 요청에 tenantId를 추가해 고객사를 선택하지 않습니다.
여러 고객사를 연동하는 서비스는 고객사별 API 인증 정보를 사용합니다.
테스트와 운영의 API 인증 정보를 분리합니다. 웹훅 서명 키도 API 인증 정보와 별개로 관리합니다.

환경	접속 주소와 용도
연동 테스트	담당자와 제공 방식·접속 주소를 협의한 뒤 구현과 업무 시나리오를 검증합니다.
운영	`https://api.maybox.app` — 운영 연결 준비를 마친 뒤 실제 창고 업무를 연결합니다.

예제 실행 준비

공개 API는 다음 헤더로 인증합니다.

Authorization: Bearer <발급받은 API 인증 정보>

아래 예제는 cURL을 사용합니다. API 인증 정보는 비밀 관리 도구로 환경 변수 MAYBOX_API_CREDENTIAL에 설정하고, shell trace와 HTTP verbose 출력을 끕니다. 브라우저·모바일 앱이나 소스 코드에 인증 정보를 넣지 않습니다. 예제는 Authorization 헤더를 프로세스 인자에 넣지 않도록 cURL 설정을 표준 입력으로 전달합니다.

API 기본 주소(origin)는 요청 경로 앞에 붙이는 접속 주소입니다. 아래 환경 변수에는 담당자에게 안내받은 테스트 API의 기본 주소를 넣습니다.

export MAYBOX_API_ORIGIN='<별도 안내받은 테스트 API 기본 주소>'

접속 주소를 안내받은 뒤 MAYBOX_API_ORIGIN의 자리표시자를 실제 테스트 API 기본 주소로 바꿉니다. 데이터를 변경하는 API의 JSON 예제는 표시된 파일명으로 저장한 뒤 실행합니다. ID와 시각은 예시이며, 후속 요청에는 실제 응답과 업무에서 정한 값을 사용합니다.

실행 전에는 다음 세 가지를 확인하세요.

담당자에게 안내받은 테스트 API 기본 주소를 설정했다.
같은 환경의 API 인증 정보를 MAYBOX_API_CREDENTIAL에 설정했다.
아래 요청은 재고를 조회하며 상품 등록·예약·출고를 수행하지 않는다는 점을 확인했다.

재고 조회로 연결 확인

curl --fail-with-body --silent --show-error --get \
  --data-urlencode 'sku=DEMO-SERUM-001' --config - <<EOF
url = "${MAYBOX_API_ORIGIN}/api/v1/stock"
header = "Authorization: Bearer ${MAYBOX_API_CREDENTIAL}"
EOF

HTTP 200과 아래 형태의 응답을 받으면 해당 환경에서 인증된 재고 조회가 성공한 것입니다. 해당 SKU의 재고·예약 등에 관한 기록이 없으면 모든 수량이 0인 항목을 반환합니다. 이 결과만으로 상품 등록이나 실물 입고가 완료됐다고 판단하지 않습니다.

{
  "items": [
    {
      "sku": "DEMO-SERUM-001",
      "onHandQuantity": 0,
      "reservedQuantity": 0,
      "availableQuantity": 0,
      "securedOutboundQuantity": 0,
      "unusedReservedQuantity": 0,
      "reservationExcessQuantity": 0,
      "outboundShortageQuantity": 0
    }
  ],
  "nextCursor": null
}

연결이 되지 않는다면

접속 실패: 안내받은 API 기본 주소와 네트워크 연결을 확인합니다.
401: API 인증 정보가 환경 변수에 설정됐는지, 접속 환경과 인증 정보가 맞는지 확인합니다.
403: 고객사 계정의 접근 권한과 설정을 Maybox 담당자에게 확인합니다.
그 밖의 응답: 오류와 재시도에서 HTTP 상태 코드와 오류 코드에 따른 다음 행동을 확인합니다.

문의할 때는 환경, HTTP 메서드·요청 경로, 발생 시각, HTTP 상태 코드·오류 코드와 응답의 x-request-id를 전달하세요. API 인증 정보는 보내지 않습니다.

첫 호출 다음에는

인증과 공통 규칙에서 멱등 키·ID·시간 규칙을 확인합니다.
입고 연동로 상품 등록부터 입고 완료 수량 조회까지 연결합니다. 이미 재고가 준비됐다면 출고 연동로 이동할 수 있습니다.
기본 업무 흐름을 확인한 뒤 웹훅으로 변경 수신을 연결합니다.