쿠폰 발송

쿠폰 발송 API를 사용하여 수신자에게 쿠폰을 발송합니다.

테스트 환경 안내

테스트 키(test_sk_)로 발송 API를 호출하면 정상적으로 202 Accepted 응답을 받고 발급 조회까지 가능하지만, 실제 MMS 문자는 발송되지 않습니다. 발송 흐름과 응답 구조를 검증하는 용도로 활용하세요. 실제 문자 발송은 라이브 키(live_sk_)로만 동작합니다.

발송 요청

POST/v1/coupons/issued/send

쿠폰을 수신자에게 발송합니다. 카탈로그에서 capabilities 배열에 "SEND"가 포함된 쿠폰만 발송할 수 있습니다. 발송은 비동기로 처리되며, 요청 즉시 202 Accepted 응답을 반환합니다. 실제 발송 결과는 발급 조회 API로 확인합니다.

Request Body

요청 파라미터

couponIdstring필수

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

orderIdstring

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

receiverobject필수

수신자 정보

phonestring필수

수신자 전화번호. 하이픈, 국가코드 등은 서버에서 자동 정규화됩니다.

namestring

수신자 이름. 최대 20자.

messageobject필수

발송 메시지

titlestring

메시지 제목. 벤더가 미지원 시 무시됩니다.

contentstring필수

메시지 본문. 벤더별 바이트/글자수 제약이 적용됩니다.

senderNumberstring

발신번호. 미입력 시 조직 기본값 또는 벤더 기본값이 사용됩니다.

Response Body (202 Accepted)

issuanceIdstring필수

발송 요청 식별자. iss_ 접두사로 시작합니다.

couponIdstring필수

발송 대상 쿠폰 식별자

orderIdstring | null필수

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

orderNumberstring필수

고객 응대용 주문 번호

비동기 처리

202 Accepted 응답은 발송 요청이 접수되었음을 의미합니다. 실제 발송 완료 여부는 발급 조회 API에서 message.status 필드를 확인하세요.

요청 예시

cURL
Node.js
Python
Java

curl -X POST https://api.aiconbiz.kr/v1/coupons/issued/send \
  -u "test_sk_your_key_here:" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "couponId": "cpn_01JNX8D7W7F6J0QYJ7YQ6G7M2R",
    "orderId": "ORD-20260323-0001",
    "receiver": {
      "phone": "01012345678",
      "name": "홍길동"
    },
    "message": {
      "title": "쿠폰이 도착했습니다",
      "content": "회원가입을 축하합니다!"
    }
  }'

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/send', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${encoded}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    couponId: 'cpn_01JNX8D7W7F6J0QYJ7YQ6G7M2R',
    orderId: 'ORD-20260323-0001',
    receiver: {
      phone: '01012345678',
      name: '홍길동',
    },
    message: {
      title: '쿠폰이 도착했습니다',
      content: '회원가입을 축하합니다!',
    },
  }),
});
const data = await res.json();
console.log(data.issuanceId); // iss_...

import base64
import uuid
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/send",
    headers={
        "Authorization": f"Basic {encoded}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "couponId": "cpn_01JNX8D7W7F6J0QYJ7YQ6G7M2R",
        "orderId": "ORD-20260323-0001",
        "receiver": {
            "phone": "01012345678",
            "name": "홍길동",
        },
        "message": {
            "title": "쿠폰이 도착했습니다",
            "content": "회원가입을 축하합니다!",
        },
    },
)
data = res.json()
print(data["issuanceId"])  # iss_...

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

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

String body = """
    {
      "couponId": "cpn_01JNX8D7W7F6J0QYJ7YQ6G7M2R",
      "orderId": "ORD-20260323-0001",
      "receiver": {
        "phone": "01012345678",
        "name": "홍길동"
      },
      "message": {
        "title": "쿠폰이 도착했습니다",
        "content": "회원가입을 축하합니다!"
      }
    }
    """;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.aiconbiz.kr/v1/coupons/issued/send"))
    .header("Authorization", "Basic " + encoded)
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", UUID.randomUUID().toString())
    .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-20260323-0001",
  "orderNumber": "123456789012"
}

에러 응답

코드	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_SEND_INVALID_COUPON`	400	발송을 지원하지 않는 쿠폰입니다.
`COUPON_SEND_COUPON_NOT_AVAILABLE`	400	현재 발송할 수 없는 쿠폰입니다.
`COUPON_SEND_INVALID_PHONE`	400	수신자 전화번호 형식이 올바르지 않습니다.
`COUPON_SEND_INVALID_SENDER_NUMBER`	400	발신번호 형식이 올바르지 않습니다.
`COUPON_SEND_INVALID_MESSAGE`	400	메시지 형식이 올바르지 않습니다.
`COUPON_SEND_ORDER_ID_CONFLICT`	409	이미 사용된 orderId입니다.

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

다음 단계

발송 후 결과 확인, 취소, 재발송은 발급 관리 페이지를 참고하세요.

발송 요청​

Request Body​

요청 파라미터

Response Body (202 Accepted)​

요청 예시​

응답 예시​

에러 응답​

다음 단계​