주문 동기화

주문 데이터를 인센토에 비동기로 전달하여 리퍼럴 보상 처리를 자동화합니다.

엔드포인트

POST /api/open/orders/sync/

항목	값
인증	`X-Incento-Key: inc_sk_...` (시크릿 키 필수)
Content-Type	`application/json`

이 엔드포인트는 즉시 202 Accepted를 반환합니다. 실제 DB 반영과 보상 처리는 백그라운드에서 비동기로 이루어집니다.

요청

예시

POST /api/open/orders/sync/
X-Incento-Key: inc_sk_YOUR_SECRET_KEY
Content-Type: application/json

{
  "orders": [
    {
      "order_id": "ORD-20240101-001",
      "member_id": "user_abc123",
      "order_amount": 50000,
      "paid_amount": 45000,
      "shipping_amount": 3000,
      "order_date": "2024-01-01T10:00:00+09:00",
      "first_order": true,
      "paid_at": "2024-01-01T10:05:00+09:00",
      "cancelled_at": null,
      "returned_at": null,
      "items": [
        {
          "product_id": "PROD-001",
          "product_name": "상품명 예시",
          "quantity": 2,
          "price": 25000,
          "paid_amount": 22500,
          "sku": "SKU-001-BLK-M"
        }
      ]
    }
  ]
}

최상위 필드

필드	타입	필수	설명
`orders`	`Order[]`	Y	동기화할 주문 목록. 1개 이상 필수

Order 객체

필드	타입	필수	설명
`order_id`	`string`	Y	고객사 주문 고유 ID (max 255자)
`member_id`	`string`	Y	고객사 회원 고유 ID (max 255자) — SDK `boot`의 `userId`와 일치해야 합니다
`order_amount`	`integer`	Y	주문 금액 (원, 0 이상)
`paid_amount`	`integer`	Y	실결제 금액 (원, 0 이상)
`shipping_amount`	`integer`	Y	배송비 (원, 0 이상)
`order_date`	`string`	Y	주문 일시 (ISO 8601)
`first_order`	`boolean`	N	첫 구매 여부. 기본값: `false`
`paid_at`	`string \| null`	N	결제 완료 일시 (ISO 8601). 기본값: `null`
`cancelled_at`	`string \| null`	N	주문 취소 일시 (ISO 8601). 기본값: `null`
`returned_at`	`string \| null`	N	반품 완료 일시 (ISO 8601). 기본값: `null`
`items`	`OrderItem[]`	N	주문 상품 목록. 기본값: `[]`

OrderItem 객체

필드	타입	필수	설명
`product_id`	`string`	Y	상품 고유 ID (max 255자)
`product_name`	`string`	Y	상품명 (max 255자)
`quantity`	`integer`	Y	수량 (1 이상)
`price`	`integer`	Y	상품 정가 (원, 0 이상)
`paid_amount`	`integer`	Y	상품 실결제 금액 (원, 0 이상)
`sku`	`string`	N	SKU (max 255자). 기본값: `""`
`cancelled_at`	`string \| null`	N	상품 취소 일시 (ISO 8601). 기본값: `null`

member_id는 SDK boot 호출 시 전달하는 userId와 반드시 일치해야 합니다. 불일치 시 해당 회원의 리퍼럴 보상이 연결되지 않습니다.

응답

202 Accepted

주문이 처리 큐에 정상적으로 접수되었습니다.

{
  "data": {
    "accepted_count": 1
  }
}

필드	타입	설명
`accepted_count`	`integer`	접수된 주문 건수

에러

HTTP	`code`	설명
401	`invalid_api_key`	Key가 없거나 유효하지 않음
401	`secret_key_required`	Public Key(`inc_pk_...`)로 호출됨 — 시크릿 키를 사용하세요
400	`invalid_request`	요청 바디 검증 실패 — `params`에서 필드별 오류 확인
503	`service_unavailable`	큐 일시 장애 — 잠시 후 재시도하세요

에러 응답 형식은 인증 가이드를 참고하세요.

구현 가이드

언제 호출하나요?

주문 상태가 변경될 때마다 최신 상태를 전달하세요. 동일한 order_id로 여러 번 호출하면 마지막 데이터로 업서트(upsert)됩니다.

주문 완료 시 — order_date, paid_at 설정
결제 완료 시 — paid_at 설정
주문 취소 시 — cancelled_at 설정
반품 완료 시 — returned_at 설정

배치 전송

한 번의 요청에 여러 주문을 묶어 전송할 수 있습니다. 단, 과도하게 큰 배치는 피하세요.

{
  "orders": [
    { "order_id": "ORD-001", ... },
    { "order_id": "ORD-002", ... },
    { "order_id": "ORD-003", ... }
  ]
}

503 재시도

503 service_unavailable 응답 시 지수 백오프(exponential backoff)로 재시도하세요. 큐의 일시적 장애로 인한 것이며, 재시도 시 정상 처리됩니다.

On this page