PIN 발급

PIN 발급 API를 사용하여 쿠폰 PIN을 발급합니다.

PIN 발급 요청

POST/v1/coupons/issued/pin

쿠폰 PIN을 발급합니다. 카탈로그에서 capabilities 배열에 "PIN"이 포함된 쿠폰만 발급할 수 있습니다.

Request Body

요청 파라미터

couponIdstring필수

발급할 쿠폰의 식별자. 카탈로그 API에서 조회한 값을 사용합니다.

orderIdstring

고객사 시스템의 주문 ID. 중복 방지 및 조회에 사용됩니다. 영문 대소문자, 숫자, ".", "_", ":", "-"만 허용되며 최대 64자입니다.

Response Body (201 Created)

issuanceIdstring필수

PIN 발급 식별자. iss_ 접두사로 시작합니다. 상태 조회, 취소 시 사용합니다.

couponIdstring필수

발급 대상 쿠폰 식별자

orderIdstring | null필수

요청 시 전달한 고객사 주문 ID

orderNumberstring필수

고객 응대용 주문 번호

pinNumberstring | null필수

고객에게 전달할 PIN/바코드 번호

validityobject | null필수

쿠폰 유효기간

fromstring | null필수

유효 시작일 (KST, YYYY-MM-DD)

tostring | null필수

유효 종료일 (KST, YYYY-MM-DD)

요청 예시

cURL
Node.js
Python
Java

curl -X POST https://api.aiconbiz.kr/v1/coupons/issued/pin \
  -u "test_sk_your_key_here:" \
  -H "Content-Type: application/json" \
  -d '{
    "couponId": "cpn_01JNX8D7W7F6J0QYJ7YQ6G7M2R",
    "orderId": "ORD-20260318-0001"
  }'

const secretKey = 'test_sk_your_key_here';
const encoded = Buffer.from(`${secretKey}:`).toString('base64');

const res = await fetch('https://api.aiconbiz.kr/v1/coupons/issued/pin', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${encoded}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    couponId: 'cpn_01JNX8D7W7F6J0QYJ7YQ6G7M2R',
    orderId: 'ORD-20260318-0001',
  }),
});
const data = await res.json();
console.log(data.issuanceId); // iss_...
console.log(data.pinNumber);  // 1234-5678-9012

import base64
import requests

secret_key = "test_sk_your_key_here"
encoded = base64.b64encode(f"{secret_key}:".encode()).decode()

res = requests.post(
    "https://api.aiconbiz.kr/v1/coupons/issued/pin",
    headers={
        "Authorization": f"Basic {encoded}",
        "Content-Type": "application/json",
    },
    json={
        "couponId": "cpn_01JNX8D7W7F6J0QYJ7YQ6G7M2R",
        "orderId": "ORD-20260318-0001",
    },
)
data = res.json()
print(data["issuanceId"])  # iss_...
print(data["pinNumber"])   # 1234-5678-9012

import java.net.URI;
import java.net.http.*;
import java.util.Base64;

String secretKey = "test_sk_your_key_here";
String encoded = Base64.getEncoder()
    .encodeToString((secretKey + ":").getBytes());

String body = """
    {
      "couponId": "cpn_01JNX8D7W7F6J0QYJ7YQ6G7M2R",
      "orderId": "ORD-20260318-0001"
    }
    """;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.aiconbiz.kr/v1/coupons/issued/pin"))
    .header("Authorization", "Basic " + encoded)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

응답 예시

{
  "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"
  }
}

에러 응답

코드	HTTP	설명
`COMMON_INVALID_IDEMPOTENCY_KEY`	400	멱등키 형식이 올바르지 않습니다.
`COMMON_IDEMPOTENCY_KEY_IN_PROGRESS`	409	동일한 멱등키 요청이 처리 중입니다.
`COMMON_IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_REQUEST`	409	동일한 멱등키로 다른 요청 본문을 사용할 수 없습니다.
`CREDIT_INSUFFICIENT_BALANCE`	402	크레딧 잔액이 부족합니다.
`USAGE_DAILY_LIMIT_EXCEEDED`	429	일일 사용 한도를 초과했습니다.
`USAGE_MONTHLY_LIMIT_EXCEEDED`	429	월간 사용 한도를 초과했습니다.
`COUPON_INVALID_COUPON_ID`	400	쿠폰 ID 형식이 올바르지 않습니다.
`COUPON_NOT_FOUND`	404	쿠폰을 찾을 수 없습니다.
`COUPON_PIN_NOT_ISSUABLE`	400	해당 쿠폰은 PIN 발급을 지원하지 않습니다.
`COUPON_PIN_ORDER_ID_CONFLICT`	409	이미 사용된 orderId입니다.
`COUPON_PIN_VENDOR_ISSUE_FAILED`	502	PIN 발급에 실패했습니다.

이 외에 인증, 요청 형식, 멱등키 관련 공통 에러가 발생할 수 있습니다.

다음 단계

PIN 발급 후 상태 조회, 취소, 이미지 조회는 발급 관리 페이지를 참고하세요.

PIN 발급 요청​

Request Body​

요청 파라미터

Response Body (201 Created)​

요청 예시​

응답 예시​

에러 응답​

다음 단계​