중복 방지와 재시도

네트워크 타임아웃은 언제든 일어납니다. 주문은 실제 돈을 쓰므로, 재시도가 같은 선물을 두 번 보내는 일이 절대 없도록 연동을 설계하세요. (같은 요청을 몇 번 보내도 결과가 한 번과 동일한 이 성질을 개발 용어로는 멱등성(idempotency)이라고 합니다.)

external_reference_id — 나만의 중복 방지 키

주문 생성 시 고유한 external_reference_id(자체 주문 ID, 대시 없는 UUID 등 — 영숫자, 1–100자)를 전달하세요:

{
  "item": { "id": 10432 },
  "delivery": { ... },
  "external_reference_id": "campaign2026reward0042"
}

보장 내용: 한 계정 안에서 하나의 external_reference_id로는 주문이 단 하나만 존재할 수 있습니다. 이미 존재하는 값으로 생성 요청을 보내면 새 주문이 만들어지지 않고 — 기존 주문이 정상 200 응답으로 반환됩니다.

덕분에 주문 생성을 안전하게 재시도할 수 있습니다:

1. 요청이 타임아웃 → 주문이 생성됐는지 알 수 없음
2. 같은 external_reference_id로 재시도
3. 첫 요청이 성공했었다면 그 주문이 반환되고, 아니라면 새로 생성됨. 어느 쪽이든: 주문은 정확히 하나

external_reference_id가 없으면 모든 생성 요청이 새 주문을 만듭니다 — 중복 방지가 동작하지 않습니다.

📘

나중에 이 값으로 주문을 조회할 수도 있습니다 — 대사(reconciliation)에 유용합니다:

GET /v1/orders?external_reference_id=myfirstorder001&page=0&element_size=10

이 엔드포인트는 page와 element_size가 필수입니다 — 빠뜨리면 400이 반환됩니다.

언제 재시도하나요?

전달된 선물 다시 보내기

재시도와 재발송은 다릅니다: 수신자가 메일을 잃어버린 경우라면 POST /v1/orders/{order_item_id}/resend로 기존 주문 아이템을 다시 전달하세요. 재발송은 EMAIL·TEXT 주문 아이템만 지원하며, 그 외 방식은 resend_not_allowed가 반환됩니다.