로그인이 필요합니다.
사방넷 풀필먼트 이전 프로모션
사방넷 2.0 정산 기능 OPEN
홈 개발가이드(ver2.0) 시작하기

개발가이드(ver2.0)

기본 개요

사방넷 풀필먼트 API는 기본적으로 REST 방식으로 json 형태로 요청의 응답을 처리합니다.

기본 REST method 역할

GET 조회 요청 처리
POST 등록 처리
발급된 api access key 와 api secret key 를 이용하여 signature 를 생성하여 api request 인증 절차를 진행하게 됩니다.
Signature 생성규칙은 인증 챕터에서 다시 자세히 설명 드리겠습니다.

Request Host

LIVE napi.sbfulfillment.co.kr

Throttling 이슈

API 서버의 처리 기능 향상을 위해 요청 횟수에 대한 제한이 있을 수 있으며, 제한이 생기는 서비스에 대해서는 별도 공지와 API 문서의 업데이트로 알려드리오니 사전에 API 연동 프로그램 제작시 요청 횟수를 가능한 최소한으로 작업을 하시길 권장드립니다.
호출 제한(Rate Limit) 안내 — 전체 API에 대해 초당 10회 이내 호출을 권장드립니다.
초과 시 응답 HTTP 429 — {"code": "4013", "message": "요청 처리 한도를 초과했습니다. 잠시 후 다시 시도해 주세요."}
아래 항목은 응답 헤더(Response Header)로 전달됩니다. (Retry-After는 429 응답에만 포함)
X-RateLimit-Limit 정책상 허용 최대 요청 수
X-RateLimit-Remaining 남은 허용 요청 수
X-RateLimit-Reset 한도가 초기화되는 시각 (Unix epoch, 초)
Retry-After 재시도까지 대기할 시간(초)
429는 요청이 처리되지 않았다는 의미이므로, 실패한 건은 다음 배치 호출에 포함해 재처리해 주세요.

응답 예시

HTTP/1.1 200 OK
X-RateLimit-Limit: <허용치>
X-RateLimit-Remaining: <남은 횟수>
X-RateLimit-Reset: <초기화 시각(epoch)>
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: <허용치>
X-RateLimit-Remaining: 0
X-RateLimit-Reset: <초기화 시각(epoch)>
Retry-After: <대기 시간(초)>

{
  "code": "4013",
  "message": "요청 처리 한도를 초과했습니다. 잠시 후 다시 시도해 주세요."
}

API 사용권한

API 사용권한은 고객사와 물류사로 분리되어 있으며 각 API 서비스 명세에서 확인할 수 있습니다.

Request URI 기본 규칙

구분 Method URI
기본 /v2/{기본구분코드}/{세부구분코드}
등록(단일) POST /v2/{기본구분코드}/{세부구분코드}
수정 PUT /v2/{기본구분코드}/{세부구분코드}/{PK}
조회(단일) GET /v2/{기본구분코드}/{세부구분코드}/{PK}
등록(벌크) POST /v2/{기본구분코드}/{세부구분코드복수형}
조회(벌크) GET /v2/{기본구분코드}/{세부구분코드복수형}

조회(벌크) 등록 dataObject

컬럼명 자료형 설명
request_data_list dataList 처리 데이터 리스트

처리 method별 요청 본문 특이사항

처리구분 Method 특이사항
등록(단일) POST 등록 대상 data object
수정 PUT 수정 대상 data object
조회(단일) GET 없음
등록(벌크) POST dataList는 등록 대상 data object 의 list 형태
조회(벌크) GET 검색조건 data

기본 응답 포맷

컬럼명 자료형 설명
code string 응답코드
message string 메세지
response dataObject 응답 본문

조회(벌크) 응답 dataObject

컬럼명 자료형 설명
total_count integer 전체 갯수
total_page integer 전체 페이지
current_page integer 현재 페이지
data_list dataList 데이터 리스트

등록(벌크) 응답 dataObject

컬럼명 자료형 설명
processed_count integer 처리 갯수
processed_data_list dataList 처리 데이터 리스트
Top