본문으로 건너뛰기

핀 발급

핀 발급은 PIN 코드를 발급받아 고객사가 직접 수신자에게 전달하는 방식입니다. 카탈로그에서 capabilities에 "PIN"이 포함된 쿠폰을 사용합니다.

동기 처리​

핀 발급은 동기로 처리됩니다. API를 호출하면 즉시 201 Created 응답과 함께 PIN 번호와 유효기간을 받습니다.

{
  "issuanceId": "iss_018d8f3a2b4c5d6e7f8a9b0c1d2e3f4a",
  "couponId": "cpn_01JNX8D7W7F6J0QYJ7YQ6G7M2R",
  "orderId": "ORD-20260318-0001",
  "orderNumber": "123456789012",
  "pinNumber": "1234-5678-9012",
  "validity": {
    "from": "2026-03-18",
    "to": "2026-04-17"
  }
}

MMS 발송과 달리 별도 폴링 없이, 응답에서 바로 PIN을 확인할 수 있습니다.

PIN 전달 방식​

PIN은 API 응답으로만 제공되며, 수신자에게 어떻게 전달할지는 고객사가 결정합니다.

  • 자체 앱/웹 화면에 바코드로 노출
  • 이메일로 전달
  • 카카오톡 등 메신저로 전달
  • 기타 고객사가 원하는 채널
안내사항(notice)을 함께 표시하세요

MMS 발송과 달리, PIN 방식에서는 카탈로그의 notice(안내사항)가 자동으로 전달되지 않습니다. PIN을 노출하는 화면에 notice 내용을 함께 표시하여 수신자가 이용 조건을 확인할 수 있도록 해주세요. notice는 카탈로그 API에서 확인할 수 있습니다.

MMS 발송과의 차이

MMS 발송(SEND)은 수신자의 전화번호만 전달하면 MMS가 자동으로 발송됩니다. 반면 핀 발급(PIN)은 고객사가 PIN을 받아 직접 전달 방식을 제어할 수 있습니다.

쿠폰 이미지 조회​

발급 후 GET /v1/coupons/issued/image 엔드포인트로 쿠폰 이미지(PNG)를 조회할 수 있습니다. 이미지에는 바코드, 상품명, 유효기간 등이 포함되어 있어 수신자에게 그대로 전달할 수 있습니다.

curl -u "test_sk_your_key_here:" \
  "https://api.aiconbiz.kr/v1/coupons/issued/image?id=iss_018d8f3a2b4c5d6e7f8a9b0c1d2e3f4a" \
  --output coupon-image.png
이미지 생성 지연

이미지는 발급 후 비동기로 생성됩니다. 발급 직후에는 아직 생성되지 않아 404가 반환될 수 있습니다. 잠시 후 다시 요청하세요.

수신자의 쿠폰 사용​

수신자는 PIN 번호 또는 바코드 이미지를 오프라인 매장에서 제시하여 쿠폰을 사용합니다. 쿠폰 사용 여부는 발급 조회 API의 coupon.status와 coupon.usedAt으로 확인할 수 있습니다.