본문으로 건너뛰기

주문 ID

orderId는 고객사 시스템의 주문 번호를 aicon에 전달하는 필드입니다. 쿠폰 발송이나 PIN 발급 요청 시 함께 전달하면, 이후 고객사의 주문 번호로 발급 결과를 조회하거나 취소할 수 있습니다.

왜 필요한가​

aicon은 발급 요청마다 issuanceId를 부여합니다. 하지만 고객사 입장에서는 자체 시스템의 주문 번호가 더 자연스러운 식별자입니다. orderId를 전달하면 aicon의 발급 건과 고객사 주문을 직접 매핑할 수 있습니다.

고객사 시스템                   aicon
┌─────────────┐              ┌─────────────────────┐
│ ORD-0001    │ ─ orderId ─→ │ iss_018d8f3a...     │
│ ORD-0002    │ ─ orderId ─→ │ iss_029e9g4b...     │
└─────────────┘              └─────────────────────┘

사용 방법​

발송(SEND)과 PIN 발급 요청 시 orderId를 함께 전달합니다.

{
  "couponId": "cpn_01JNX8D7W7F6J0QYJ7YQ6G7M2R",
  "orderId": "ORD-20260323-0001",
  "receiver": {
    "phone": "01012345678"
  }
}

전달한 orderId는 응답에 그대로 포함됩니다.

{
  "issuanceId": "iss_018d8f3a2b4c5d6e7f8a9b0c1d2e3f4a",
  "couponId": "cpn_01JNX8D7W7F6J0QYJ7YQ6G7M2R",
  "orderId": "ORD-20260323-0001",
  "orderNumber": "123456789012"
}

orderId로 조회·취소·재발송​

orderId를 전달한 발급 건은 issuanceId 대신 orderId로 조회, 취소, 재발송할 수 있습니다.

# 결과 조회
curl -u "test_sk_your_key_here:" \
  "https://api.aiconbiz.kr/v1/coupons/issued?orderId=ORD-20260323-0001"

# 취소
curl -X POST https://api.aiconbiz.kr/v1/coupons/issued/cancel \
  -u "test_sk_your_key_here:" \
  -H "Content-Type: application/json" \
  -d '{ "orderId": "ORD-20260323-0001", "reason": "고객 요청에 의한 취소" }'

# 재발송 (SEND 타입만)
curl -X POST https://api.aiconbiz.kr/v1/coupons/issued/resend \
  -u "test_sk_your_key_here:" \
  -H "Content-Type: application/json" \
  -d '{ "orderId": "ORD-20260323-0001" }'

중복 방지​

같은 orderId로 두 번 요청하면 409 Conflict 에러가 반환됩니다. 이를 통해 고객사 시스템에서 동일 주문에 대해 쿠폰이 중복 발급되는 것을 방지할 수 있습니다.

{
  "status": 409,
  "code": "COUPON_SEND_ORDER_ID_CONFLICT",
  "message": "이미 사용된 orderId입니다."
}
orderId와 멱등키의 차이

orderId는 비즈니스 레벨의 중복 방지 수단입니다. 같은 주문에 대해 쿠폰을 두 번 발급하지 않도록 합니다. 반면 Idempotency-Key는 네트워크 오류 등으로 같은 HTTP 요청을 재시도할 때, 실제 처리는 한 번만 하고 저장된 응답을 반환하는 용도입니다.

orderIdIdempotency-Key
목적비즈니스 중복 방지HTTP 요청 재시도 안전성
중복 시 동작409 Conflict 에러기존 응답 그대로 반환
범위고객사(organization) 단위요청 단위

형식 규칙​

항목규칙
최대 길이64자
허용 문자영문 대소문자, 숫자, ., _, :, -
대소문자구분함 (ORD-001과 ord-001은 다른 값)
변경생성 후 변경 불가

orderId와 orderNumber​

orderId와 orderNumber는 이름이 비슷하지만 역할이 다릅니다.

orderIdorderNumber
누가 지정하나고객사가 요청 시 전달aicon이 자동 생성
용도고객사 시스템 연동, API 조회최종 수신자 고객 응대 (CS)
예시ORD-20260323-0001123456789012