카탈로그

브랜드, 카테고리, 쿠폰 상품을 조회하는 카탈로그 API입니다.

브랜드 목록 조회

GET/v1/brands

현재 API 채널에서 발급 가능한 쿠폰이 존재하는 브랜드 목록을 조회합니다. 응답의 brandId는 쿠폰 목록 조회 시 필터로 사용할 수 있습니다.

Response Body

itemsBrandItem[]필수

브랜드 목록

brandIdstring필수

브랜드 식별자. 쿠폰 목록 조회의 brandId 파라미터에 사용합니다.

namestring필수

브랜드명

logoUrlstring | null필수

브랜드 로고 이미지 URL

요청 예시

cURL
Node.js
Python

curl -u "test_sk_your_key_here:" \
  https://api.aiconbiz.kr/v1/brands

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

const res = await fetch('https://api.aiconbiz.kr/v1/brands', {
  headers: { 'Authorization': `Basic ${encoded}` },
});
const data = await res.json();

import base64
import requests

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

res = requests.get(
    "https://api.aiconbiz.kr/v1/brands",
    headers={"Authorization": f"Basic {encoded}"},
)
data = res.json()

응답 예시

{
  "items": [
    {
      "brandId": "brd_019b9b5655b3770e8428fa2114f39219",
      "name": "스타벅스",
      "logoUrl": "https://cdn.example.com/brands/starbucks-logo.png"
    },
    {
      "brandId": "brd_019c0a1b2c3d4e5f6a7b8c9d0e1f2a3b",
      "name": "배스킨라빈스",
      "logoUrl": "https://cdn.example.com/brands/baskinrobbins-logo.png"
    }
  ]
}

카테고리 목록 조회

GET/v1/categories

활성화된 카테고리 목록을 조회합니다. 응답의 categoryId는 쿠폰 목록 조회 시 필터로 사용할 수 있습니다.

Response Body

itemsCategoryItem[]필수

카테고리 목록

categoryIdstring필수

카테고리 식별자. 쿠폰 목록 조회의 categoryId 파라미터에 사용합니다.

namestring필수

카테고리명

요청 예시

cURL
Node.js
Python

curl -u "test_sk_your_key_here:" \
  https://api.aiconbiz.kr/v1/categories

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

const res = await fetch('https://api.aiconbiz.kr/v1/categories', {
  headers: { 'Authorization': `Basic ${encoded}` },
});
const data = await res.json();

import base64
import requests

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

res = requests.get(
    "https://api.aiconbiz.kr/v1/categories",
    headers={"Authorization": f"Basic {encoded}"},
)
data = res.json()

응답 예시

{
  "items": [
    {
      "categoryId": "cat_019c0c7c2c2f709c930006b1df055765",
      "name": "카페/음료"
    },
    {
      "categoryId": "cat_019c0c7c2c2f709c930006b1df055766",
      "name": "치킨/피자"
    }
  ]
}

쿠폰 목록 조회

GET/v1/coupons

고객사에 할당된 쿠폰 카탈로그를 조회합니다. 브랜드, 카테고리, 키워드 검색으로 필터링할 수 있으며 커서 기반 페이지네이션을 지원합니다.

Query Parameters

capabilitiesstring | string[]

쿠폰 기능 기준 필터링. 여러 값 지정 시 AND 시맨틱으로 동작합니다.

허용 값SENDPIN

brandIdstring

브랜드 ID로 필터링합니다. 브랜드 목록 조회 API에서 받은 brandId를 전달합니다.

categoryIdstring

카테고리 ID로 필터링합니다. 카테고리 목록 조회 API에서 받은 categoryId를 전달합니다.

searchstring

쿠폰명 또는 브랜드명으로 검색합니다. 공백으로 구분된 키워드는 AND 조건으로 동작합니다. (1~100자)

limitnumber

한 번에 조회할 최대 개수 (최소 1, 최대 100)기본값: 20

cursorstring

이전 응답의 nextCursor 값

Response Body

itemsCouponItem[]필수

쿠폰 목록

couponIdstring필수

쿠폰 식별자. 발급/발송 요청에서 사용합니다.

namestring필수

상품명

brandNamestring필수

브랜드명

typestring필수

쿠폰 유형

허용 값VOUCHEREXCHANGEDELIVERY

imageUrlstring | null필수

쿠폰 이미지 URL

pricenumber필수

가격 (원)

validityDaysnumber필수

유효기간 일수

capabilitiesstring[]필수

쿠폰이 지원하는 기능 목록

허용 값SENDPIN

noticestring | null필수

상품 안내사항. 고객에게 전달이 필요한 유의사항입니다.

messageConstraintobject | null필수

SEND 발송 시 메시지 길이 제약사항. SEND capability가 없으면 null입니다.

limitTypestring필수

메시지 길이 제한 방식

허용 값LENGTHBYTE

encodingstring | null필수

바이트 계산 시 사용하는 인코딩. limitType이 BYTE일 때만 유효합니다.

허용 값UTF-8EUC-KR

titleSupportedboolean필수

메시지 제목 지원 여부

titleLimitnumber | null필수

제목 최대 길이/바이트. titleSupported가 false이면 null입니다.

contentLimitnumber필수

본문 최대 길이/바이트

nextCursorstring | null필수

다음 페이지 조회용 커서. 마지막 페이지면 null.

요청 예시

cURL
Node.js
Python
Java

# 전체 조회
curl -u "test_sk_your_key_here:" \
  "https://api.aiconbiz.kr/v1/coupons"

# 브랜드 필터
curl -u "test_sk_your_key_here:" \
  "https://api.aiconbiz.kr/v1/coupons?brandId=brd_019b9b5655b3770e8428fa2114f39219"

# 키워드 검색 + capabilities 필터
curl -u "test_sk_your_key_here:" \
  "https://api.aiconbiz.kr/v1/coupons?search=스타벅스+아메리카노&capabilities=SEND"

# 카테고리 필터 + limit
curl -u "test_sk_your_key_here:" \
  "https://api.aiconbiz.kr/v1/coupons?categoryId=cat_019c0c7c2c2f709c930006b1df055765&limit=10"

# 커서 기반 페이지네이션
curl -u "test_sk_your_key_here:" \
  "https://api.aiconbiz.kr/v1/coupons?cursor=eyJjcmVhdGVkQXQiOi..."

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

// 전체 조회
const res = await fetch('https://api.aiconbiz.kr/v1/coupons', {
  headers: { 'Authorization': `Basic ${encoded}` },
});
const data = await res.json();

// 다음 페이지 조회
if (data.nextCursor) {
  const nextRes = await fetch(
    `https://api.aiconbiz.kr/v1/coupons?cursor=${data.nextCursor}`,
    { headers: { 'Authorization': `Basic ${encoded}` } },
  );
}

import base64
import requests

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

# 전체 조회
res = requests.get("https://api.aiconbiz.kr/v1/coupons", headers=headers)
data = res.json()

# 다음 페이지 조회
if data.get("nextCursor"):
    next_res = requests.get(
        f"https://api.aiconbiz.kr/v1/coupons?cursor={data['nextCursor']}",
        headers=headers,
    )

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());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.aiconbiz.kr/v1/coupons"))
    .header("Authorization", "Basic " + encoded)
    .GET()
    .build();

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

응답 예시

{
  "items": [
    {
      "couponId": "cpn_01JNX8D7W7F6J0QYJ7YQ6G7M2R",
      "name": "스타벅스 아메리카노 T",
      "brandName": "스타벅스",
      "type": "EXCHANGE",
      "imageUrl": "https://cdn.example.com/coupons/starbucks-americano.png",
      "price": 4500,
      "validityDays": 30,
      "capabilities": ["SEND", "PIN"],
      "notice": "유효기간 내 사용 가능하며, 일부 매장에서는 사용이 제한될 수 있습니다.",
      "messageConstraint": {
        "limitType": "BYTE",
        "encoding": "UTF-8",
        "titleSupported": false,
        "titleLimit": null,
        "contentLimit": 100
      }
    }
  ],
  "nextCursor": null
}

쿠폰 상세 조회

GET/v1/coupons/:couponId

couponId로 단건 쿠폰 상세 정보를 조회합니다.

Path Parameters

couponIdstring필수

카탈로그 목록 API에서 받은 쿠폰 식별자

요청 예시

cURL
Node.js
Python
Java

curl -u "test_sk_your_key_here:" \
  https://api.aiconbiz.kr/v1/coupons/cpn_01JNX8D7W7F6J0QYJ7YQ6G7M2R

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

const res = await fetch(
  'https://api.aiconbiz.kr/v1/coupons/cpn_01JNX8D7W7F6J0QYJ7YQ6G7M2R',
  { headers: { 'Authorization': `Basic ${encoded}` } },
);
const data = await res.json();
console.log(data.name); // 스타벅스 아메리카노 T

import base64
import requests

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

res = requests.get(
    "https://api.aiconbiz.kr/v1/coupons/cpn_01JNX8D7W7F6J0QYJ7YQ6G7M2R",
    headers={"Authorization": f"Basic {encoded}"},
)
data = res.json()
print(data["name"])  # 스타벅스 아메리카노 T

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());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(
        "https://api.aiconbiz.kr/v1/coupons/cpn_01JNX8D7W7F6J0QYJ7YQ6G7M2R"))
    .header("Authorization", "Basic " + encoded)
    .GET()
    .build();

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

응답 예시

{
  "couponId": "cpn_01JNX8D7W7F6J0QYJ7YQ6G7M2R",
  "name": "스타벅스 아메리카노 T",
  "brandName": "스타벅스",
  "type": "EXCHANGE",
  "imageUrl": "https://cdn.example.com/coupons/starbucks-americano.png",
  "price": 4500,
  "validityDays": 30,
  "capabilities": ["SEND", "PIN"],
  "notice": "유효기간 내 사용 가능하며, 일부 매장에서는 사용이 제한될 수 있습니다.",
  "messageConstraint": {
    "limitType": "BYTE",
    "encoding": "UTF-8",
    "titleSupported": false,
    "titleLimit": null,
    "contentLimit": 100
  }
}

에러 응답

코드	HTTP	설명
`COUPON_INVALID_COUPON_ID`	400	쿠폰 ID 형식이 올바르지 않습니다.
`COUPON_NOT_FOUND`	404	쿠폰을 찾을 수 없습니다.

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

브랜드 목록 조회​

Response Body​

요청 예시​

응답 예시​

카테고리 목록 조회​

Response Body​

요청 예시​

응답 예시​

쿠폰 목록 조회​

Query Parameters​

Response Body​

요청 예시​

응답 예시​

쿠폰 상세 조회​

Path Parameters​

요청 예시​

응답 예시​

에러 응답​

브랜드 목록 조회

Response Body

요청 예시

응답 예시

카테고리 목록 조회

Response Body

요청 예시

응답 예시

쿠폰 목록 조회

Query Parameters

Response Body

요청 예시

응답 예시

쿠폰 상세 조회

Path Parameters

요청 예시

응답 예시

에러 응답