API 참조
승인받은 범위에 공개된 작업과 권한만 구현하세요.
전체 연동 패키지를 요청하기 전에, 요청·응답·권한·중복 방지·실패 처리가 모두 갖춰진 계약 한 건을 먼저 살펴보세요.
연동 구현 체크리스트
조회
GET 작업은 필요한 권한, 조회 필드, 페이지 나누기 방식, 응답 형태를 명시합니다.
명령 실행
쓰기 요청은 고유한 Idempotency-Key로 중복 처리를 막으며, 최신 버전이나 추가 확인이 필요할 수 있습니다.
응답 해석
인증, 권한, 충돌, 입력 검증, 요청 제한, 서비스 오류를 서로 다르게 처리하세요.
추적
요청 ID를 보관해 두면 고객사 팀과 세일링고가 같은 요청을 두고 이야기할 수 있습니다.
요청과 처리 결과
POST /cases
Authorization: Bearer <server-token>
Idempotency-Key: <unique-command-key>
Content-Type: application/json
{ "subject": "Callback request" }HTTP 201
X-Request-Id: req_...
{ "id": "case_...", "status": "open" }오류별 대응 방법
| 상태 | 의미 | 연동 측 조치 |
|---|---|---|
| 401 | 인증 정보가 없거나 만료되었거나 올바르지 않음 | 요청을 중지하고 승인된 서버 절차로 인증 정보를 갱신합니다. |
| 403 | 요청한 작업에 필요한 권한 또는 범위가 없음 | 다시 시도하지 말고 접근 권한 검토를 요청합니다. |
| 409 | 상태, 버전, 중복 처리 방지 키, 승인 상태가 충돌함 | 충돌 내용을 확인하고 상태를 맞춘 뒤 다음 요청을 보냅니다. |
| 422 | 요청 형식이 공개된 스키마와 일치하지 않음 | 오류에 표시된 필드를 수정한 뒤 다시 요청합니다. |
| 429 | 짧은 시간에 요청을 너무 많이 보냄 | 응답에 안내된 대기 시간에 맞춰 요청 간격을 늘립니다. |
| 5xx | 일시적인 서비스 오류가 발생했을 수 있음 | 요청 ID를 보관하고 해당 작업이 재시도를 허용할 때만 다시 시도합니다. |