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필수

고객 응대용 주문 번호

pricenumber필수

정가 (원). 쿠폰의 액면가입니다.

purchasePricenumber필수

실구매가 (원). 계약 할인율을 적용한 금액이며, 적용 가능한 할인이 없으면 정가와 같습니다. 발급 시점 기준으로 고정됩니다.

pinNumberstring | null필수

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

couponViewUrlstring | null필수

쿠폰 확인 페이지 링크. 고객에게 그대로 전달하면 인증 없이 쿠폰번호·바코드·이미지를 확인할 수 있습니다.

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",
  "price": 4500,
  "purchasePrice": 4275,
  "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"
  }
}

에러 응답

코드	HTTP	설명
`COMMON_INVALID_IDEMPOTENCY_KEY`	400	멱등키 형식이 올바르지 않습니다.
`COMMON_IDEMPOTENCY_KEY_IN_PROGRESS`	409	동일한 멱등키 요청이 처리 중입니다.
`COMMON_IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_REQUEST`	409	동일한 멱등키로 다른 요청 본문을 사용할 수 없습니다.
`COMMON_ISSUANCE_SUSPENDED`	503	쿠폰 발급이 일시적으로 중단되었습니다. 잠시 후 다시 시도해 주세요.
`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)​

요청 예시​

응답 예시​

에러 응답​

다음 단계​