API 레퍼런스

API 레퍼런스는 Swipelux API의 공식 계약이에요. 각 동작마다 요청, 응답, 보안, 상태, 오류 스키마가 표시되어 있어요. 전체 공개 문제 카탈로그와 해결 지침은 오류 및 재시도를 참고하세요. 모든 요청에 https://platform.swipelux.com을 사용하세요. 보호된 백엔드에서 환경별 키를 X-API-Key에 실어 보내주세요.

쓰기 작업을 안전하게 재시도하세요

동작에 Idempotency-Key가 필수로 표시되어 있으면 의도한 각 동작마다 하나의 키를 생성하고 로컬 요청 기록과 함께 저장하세요.

Idempotent request

curl --request POST \
  'https://platform.swipelux.com/v3/customers' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Idempotency-Key: customer-order-1001' \
  --header 'Content-Type: application/json' \
  --data '{"type":"individual","externalId":"customer-order-1001"}'

응답이 불확실하면 동일한 메서드, 경로, 본문을 같은 키로 재시도하세요. 다른 동작이나 변경된 본문에 그 키를 재사용해서는 안 돼요. 일부 동작은 응답이 같은 키를 가진 이전 요청에서 왔을 때 Idempotency-Replayed: true를 반환해요. 그 응답은 원래 동작의 결과로 처리하고 두 번째 동작으로 다루지 마세요.

오류 처리

API 오류는 application/problem+json을 사용해요. 다음 안정 필드를 중심으로 클라이언트 동작을 구성하세요:

필드	용도
`status`	문제와 연관된 HTTP 상태예요.
`code`	안정적인 기계 판독 오류 코드예요.
`detail`	현재 요청에 대한 실행 가능한 설명이에요.
`retryable`	존재하는 경우, 동일한 요청 재시도가 성공할 수 있는지 여부예요.
`errors[].pointer`	유효하지 않은 요청 필드에 대한 JSON Pointer예요.
`correlationId`	로그와 지원 기록에 보관할 요청 식별자예요.

응답의 correlationId는 X-Request-Id를 반영해요. 동작과 이 값을 함께 로깅하되, 비밀 정보나 전체 금융 정보는 노출하지 마세요.

Problem response

{
  "type": "https://docs.swipelux.com/errors/validation-error",
  "title": "Validation error",
  "status": 400,
  "code": "validation_error",
  "detail": "The request contains invalid fields.",
  "correlationId": "01JERRORVALIDATION",
  "errors": [
    {
      "pointer": "/externalId",
      "code": "invalid_format",
      "message": "Use a valid external identifier."
    }
  ]
}

동작에 문서화된 문제 스키마를 사용해 입력을 수정할지, 리소스 상태를 새로고침할지, 작업을 완료할지, 재시도할지 결정하세요. 모든 공개 code, 안정적인 문제 타입 URI, 재시도 동작, 다음 조치는 오류 및 재시도를 참고하세요.

비동기 동작 추적

성공적인 생성 응답은 많은 워크플로를 시작해요. 완료를 보장하지는 않아요. 응답에서 파생된 리소스 ID를 저장하고, 현재 리소스를 조회하며, 검증된 웹훅을 사용해 변경 사항에 대응하세요. POST /v3/customers로 시작하거나, 완전한 샌드박스 여정을 위해 퀵스타트를 따라주세요.

개요

버전 관리

쓰기 작업을 안전하게 재시도하세요

오류 처리

비동기 동작 추적

​쓰기 작업을 안전하게 재시도하세요

​오류 처리

​비동기 동작 추적

쓰기 작업을 안전하게 재시도하세요

오류 처리

비동기 동작 추적