핀 발급
핀 발급은 PIN 코드를 발급받아 고객사가 직접 수신자에게 전달하는 방식입니다. 카탈로그에서 capabilities에 "PIN"이 포함된 쿠폰을 사용합니다.
동기 처리
핀 발급은 동기로 처리됩니다. API를 호출하면 즉시 201 Created 응답과 함께 PIN 번호와 유효기간을 받습니다.
{
"issuanceId": "iss_018d8f3a2b4c5d6e7f8a9b0c1d2e3f4a",
"couponId": "cpn_01JNX8D7W7F6J0QYJ7YQ6G7M2R",
"orderId": "ORD-20260318-0001",
"orderNumber": "123456789012",
"pinNumber": "1234-5678-9012",
"couponViewUrl": "https://coupon.aiconbiz.kr/c/018d8f3a-2b4c-5d6e-7f8a-9b0c1d2e3f4a?code=9f2c1d7e8a3b4c5d6e7f8a9b0c1d2e3f",
"validity": {
"from": "2026-03-18",
"to": "2026-04-17"
}
}
MMS 발송과 달리 별도 폴링 없이, 응답에서 바로 PIN을 확인할 수 있습니다.
PIN 전달 방식
PIN은 API 응답으로만 제공되며, 수신자에게 어떻게 전달할지는 고객사가 결정합니다.
- 응답의
couponViewUrl(쿠폰 확인 페이지) 링크를 그대로 전달 - 자체 앱/웹 화면에 바코드로 노출
- 이메일로 전달
- 카카오톡 등 메신저로 전달
- 기타 고객사가 원하는 채널
쿠폰 확인 페이지
couponViewUrl은 상품명·바코드·유효기간·사용 안내를 모두 담은 수신자용 페이지입니다. 인증 헤더가 필요 없으므로 문자·메신저·이메일 어디에든 링크만 넣으면 됩니다. MMS 발송(SEND)에서 수신자가 받는 것과 동일한 페이지입니다.
링크는 발급 식별자와 함께 담긴 code 값으로 열람을 검증합니다. 링크를 아는 사람은 누구나 쿠폰번호를 볼 수 있으므로, 수신자 본인에게만 전달하세요.
직접 만든 화면에 PIN을 노출하는 경우, 카탈로그의 notice(안내사항)는 자동으로 전달되지 않습니다. 해당 화면에 notice 내용을 함께 표시하여 수신자가 이용 조건을 확인할 수 있도록 해주세요. notice는 카탈로그 API에서 확인할 수 있습니다.
couponViewUrl 링크로 전달하는 경우에는 페이지에 안내사항이 이미 표시되므로 별도 조치가 필요 없습니다.
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으로 확인할 수 있습니다.