WHATTA 택배 API 연동 문서

주소와 인증

마이페이지에서 발급되는 값 중 API 호출에 필요한 인증값은 WHATTA 연동 코드 하나입니다.

1. 연동 코드 발급마이페이지(/mypage/) → 쇼핑몰 연동에서 발급합니다. 기존 주문 관리 화면으로 이동할 필요가 없습니다.
2. 서버에 보관하고 요청에 사용코드를 안전하게 보관하고, HTTPS 요청 헤더에 아래 값을 넣습니다.

1. 쇼핑몰의 발송 준비 완료 시점에 호출결제·재고·발송 가능 여부를 쇼핑몰에서 확인한 뒤, 쇼핑몰 서버의 주문 처리 흐름에서 WHATTA를 호출합니다. merchantFulfillmentReady는 실제 확인 결과에 따라 JSON boolean으로 설정하고 항상 true로 고정하지 마세요.
2. 주문 필드 연결쇼핑몰 주문번호를 shopOrderId, 수취인 정보를 receiver, 상품명·수량을 products에 매핑합니다. 받는 분 상세주소 receiver.address2도 전달하고, 보내는 분 정보는 회원이 마이페이지에 저장한 발송처 설정을 사용합니다.
3. 응답에 따라 처리status와 shipmentQueueStatus를 확인합니다. 접수대기 초안 생성은 실제 택배 접수나 송장 발급 완료가 아닙니다. 중복·충돌·응답 유실은 아래 결과 안내를 따르세요.

발송 준비된 주문 전송

쇼핑몰 서버에서 WHATTA로 주문 전송을 실행하면 유효한 요청은 주문으로 수집됩니다. 이 연결에는 ZIP이나 택배사별 주문 endpoint가 필요하지 않습니다. 신규 CUSTOM 주문은 merchantFulfillmentReady: true가 수집·내부 접수대기 초안 생성의 기준입니다.

• 주문번호, 받는 분의 연락처·주소(상세주소 포함), 상품명과 수량을 보냅니다. 보내는 분 정보는 회원이 WHATTA /mypage/에 저장한 발송처 설정을 사용합니다.
• merchantFulfillmentReady는 JSON boolean true여야 합니다. WHATTA는 이 판매자 선언을 받으며 결제를 독립 검증하지 않습니다.
• CUSTOM 접수대기 초안에는 orderStatus와 paymentStatus가 필요하지 않으며, 두 값은 초안 생성 조건으로 사용하지 않습니다. 택배사 고객코드·사업자번호·인증정보도 이 주문 수집 요청의 필드가 아닙니다.

{
  "shopOrderId": "DOC-ORDER-0001",
  "merchantFulfillmentReady": true,
  "receiver": {
    "name": "가상 수취인",
    "phone": "010-0000-0000",
    "zipcode": "06236",
    "address1": "서울 예시로 1",
    "address2": "가상 주소"
  },
  "products": [{"name": "가상 상품", "quantity": 1}]
}

curl --disable --request POST \
  'https://whatta.example.invalid/api/shop/orders/' \
  --header 'Authorization: Bearer REPLACE_WITH_YOUR_CODE' \
  --header 'Content-Type: application/json' \
  --data-binary @order.json

(
  set +x
  read -r -s -p 'WHATTA 연동 코드: ' WHATTA_TOKEN
  printf '\n'
  curl --disable --config - <<EOF
url = "https://www.whatta.co.kr/api/shop/orders/"
request = "POST"
header = "Authorization: Bearer ${WHATTA_TOKEN}"
header = "Content-Type: application/json"
data-binary = "@order.json"
EOF
  result=$?
  unset WHATTA_TOKEN
  exit "$result"
)

전체 필드와 자료형은 OpenAPI 명세에서 확인하세요.

수집 결과 확인

주문 화면(/orders/)에서 수집 여부를, 접수 관리(/manage/)에서 배송 처리 상태를 확인하세요.

개발자는 HTTP 상태와 status, shipmentQueueStatus를 함께 확인합니다.

표를 좌우로 밀어 전체 내용을 확인하세요.

{
  "success": true,
  "status": "NEEDS_REVIEW",
  "data": {
    "shopOrderId": "DOC-ORDER-0001",
    "shipmentQueueStatus": "CREATED",
    "carrierCode": null,
    "carrierSetupRequired": true,
    "carrierSubmission": "NOT_EXECUTED"
  }
}

택배 접수와 송장 출력

배송정보를 확인하고 접수한 뒤, 운송장번호와 출력 준비 상태를 확인하세요.

1. 택배사·발송처 설정마이페이지(/mypage/)에 계약·인증·발송처를 저장하고, 주문 화면(/orders/)에서 기본 택배사를 선택합니다.
2. 접수대기 확인접수 관리(/manage/)에서 주문·보내는 분·받는 분 정보를 확인합니다.
3. 택배 접수CJ는 송장생성, 우체국은 우체국 송장생성을 누릅니다. 쇼핑몰 서버에서 배송 API로 접수할 수도 있습니다.
4. 송장 출력접수 완료, 운송장번호, 출력 데이터가 모두 준비되면 송장 출력을 누릅니다.

CJ대한통운

본인 CJ 계약정보와 발송처를 저장한 뒤 접수하세요.

1. 계약정보 저장마이페이지 → 배송사 설정 → CJ대한통운에서 고객코드·사업자정보·운임·박스·기본 발송처를 입력합니다.
2. 기본 택배사 선택주문 화면에서 CJ대한통운을 기본 택배사로 저장합니다.
3. 접수 후 출력접수 관리 → 접수대기에서 송장생성을 누릅니다. 송장번호와 출력 준비 상태를 확인한 뒤 출력합니다.

주문 전송 주소는 우체국과 같습니다. 자동 접수는 7. 배송 API를 참고하세요. 회원 설정 단계는 CJ대한통운 송장출력 가이드에서 확인할 수 있습니다.

우체국

본인 계약정보와 인증정보, 발송처를 준비하세요.

1. 계약·인증정보 저장마이페이지 → 배송사 설정 → 우체국 계약소포에서 계약 식별정보·인증정보·발송처를 저장하고 인증 상태를 확인합니다.
2. 기본 택배사 선택주문 화면에서 우체국 계약소포를 기본 택배사로 저장합니다.
3. 접수 후 출력접수 관리 → 접수대기에서 배송정보를 확인하고 우체국 송장생성을 누릅니다. 접수 결과·등기번호·출력 준비 상태를 확인합니다.

CJ와 같은 주문 API를 사용합니다. 자동 접수는 7. 배송 API를 참고하세요. 회원 설정 단계는 우체국 계약소포 설정 가이드에서 확인할 수 있습니다.

같은 수집 주문의 배송 API

주문 수집 때 사용한 연동 코드와 shopOrderId로 접수·조회·출력을 연결하세요. 저장된 주소와 상품을 다시 보낼 필요는 없습니다.

표를 좌우로 밀어 전체 내용을 확인하세요.

curl --disable --request POST \
  'https://whatta.example.invalid/api/shop/shipments/' \
  --header 'Authorization: Bearer REPLACE_WITH_YOUR_CODE' \
  --header 'Content-Type: application/json' \
  --data '{"shopOrderId":"DOC-ORDER-0001"}'

주문 연결 오류는 409, 코드·권한·택배 설정 오류는 401/403, 이용량 제한은 429, 서버·운영 준비 문제는 503입니다. 오류별 해결 방법 보기

오류와 재시도

오류 코드에 맞는 항목을 확인하세요. 응답이 없더라도 접수가 실패했다고 단정하면 안 됩니다.

표를 좌우로 밀어 전체 내용을 확인하세요.

전체 요청·응답 형식은 OpenAPI 명세에서 확인하세요.