알림 게이트웨이 API 개요

알림 게이트웨이 API는 고객사 시스템이 알림톡·문자·이메일을 보내고 발송 결과를 조회하는 RESTful API입니다. 채널마다 발송 경로와 요청 필드만 다르고, 인증·요청 규칙·호출 한도는 모든 채널이 같습니다.

채널

이메일은 준비 중이라 호출하면 501 SEND-5011(해당 채널 발송 기능은 준비 중입니다)로 응답합니다. 그 채널을 쓰도록 허용되지 않은 키는 그보다 먼저 403 RATE-4031을 받습니다.

API 엔드포인트

이 문서의 예시는 주소를 https://{게이트웨이 주소}로 적었습니다. 위 엔드포인트로 바꿔 쓰십시오.

연동 시험 주소에서도 실제로 발송되는지는 주소가 아니라 키가 정합니다(키 환경).

인증

API Key와 Secret Key로 접근 토큰을 받아, API를 호출할 때 Authorization 헤더에 싣습니다. 토큰 하나로 쓰기로 계약한 모든 채널을 호출할 수 있습니다.

1. 키 발급 — API Key와 Secret Key는 담당자가 발급합니다. Secret Key는 발급할 때 한 번만 보여 주므로 서버의 환경 변수나 비밀 저장소에 보관하고, 소스 코드·저장소·로그에 남기지 마십시오. 유출이 의심되면 바로 담당자에게 폐기·재발급을 요청하십시오.
2. 토큰 발급 — 토큰 발급을 호출해 접근 토큰(30분 유효)과 갱신 토큰(14일 유효)을 받습니다.
3. API 호출 — Authorization: Bearer {accessToken} 헤더를 붙여 호출합니다.
4. 토큰 갱신 — 접근 토큰이 만료되기 전에 토큰 갱신이나 토큰 발급을 다시 호출합니다.

키 환경

API Key는 발급할 때 환경이 정해지고, 환경에 따라 실제 발송 여부가 다릅니다. 환경은 바꿀 수 없으며 바꾸려면 새로 발급받습니다.

• 개발 키는 인증·권한·호출 한도와 필수값·치환 변수 검사까지 운영과 같이 거친 뒤, 발송만 하지 않고 SEND-0003(모의 발송으로 접수했습니다)으로 답합니다. 번호 형식·본문 길이처럼 발송할 때 하는 검사는 거치지 않으니, 최종 확인은 검증 키로 합니다.
• 개발 키로 받은 메시지 키와 배치 키는 mock-으로 시작합니다. 발송되지 않았으므로 결과 조회에서는 찾을 수 없습니다(404).
• 실제로 받아 보는 시험은 검증 키로 합니다. 그 건은 쿼터가 차감됩니다.

문서 구성

오퍼레이션

발송 결과는 호출하는 쪽이 조회해서 가져갑니다(폴링). 게이트웨이가 결과를 먼저 보내 주는 방식(웹훅)은 없습니다.

이 문서는 2026년 10월 26일 기준입니다.

연동 순서

처음 연동할 때 따라 하는 순서입니다. 토큰을 받고, 메시지를 보내고, 결과를 가져옵니다. 예시는 알림톡이며 다른 채널도 순서는 같습니다.

1. 준비물 받기

담당자에게 다음을 받습니다.

• API Key와 Secret Key — 실제로 받아 보는 시험에는 검증 키를 받습니다(개발 키는 발송하지 않습니다, 키 환경)
• (알림톡) 카카오 비즈니스 채널의 발신 프로필 키(40자)
• (알림톡) 카카오가 승인한 템플릿의 코드와 본문
• (문자) 받은 API Key로 쓸 수 있게 등록된 발신번호 — 발신번호는 API Key가 속한 프로젝트마다 등록됩니다
• 연동 시험 주소와 하루·한 달 발송 쿼터

2. 토큰 발급

curl -X POST 'https://{게이트웨이 주소}/oauth/token'   -H 'Content-Type: application/json'   -d '{"grantType":"client_credentials","apiKey":"{API Key}","secretKey":"{Secret Key}"}'

응답의 data.accessToken을 30분 동안 재사용합니다(토큰 발급).

3. 알림톡 보내기

대량 발송 API로 한 명에게 보내는 예입니다. Idempotency-Key는 요청마다, itemIdempotencyKey는 수신자마다 새로 만들고 저장해 둡니다.

curl -X POST 'https://{게이트웨이 주소}/api/v1/alimtalk/batches'   -H 'Authorization: Bearer {accessToken}'   -H 'Content-Type: application/json'   -H 'Idempotency-Key: 0c9e7d1a-5b2f-4a38-8e61-3f2d9c4b7a10'   -d '{
  "template": {
    "senderKey": "{발신 프로필 키 40자}",
    "callbackNo": "0212345678",
    "templateCode": "SURVEY_START_01",
    "body": "#{name}님, 『#{surveyName}』 설문이 열렸습니다."
  },
  "items": [
    { "recvNo": "01012345678", "itemIdempotencyKey": "talk7788-25780", "clientRef": "25780",
      "variables": { "name": "홍길동", "surveyName": "도민 만족도 조사" } }
  ]
}'

응답의 data.batchKey와 항목별 messageId를 저장합니다. messageId가 없는 항목은 접수되지 않았습니다(대량 발송).

4. 결과 가져오기

curl -G 'https://{게이트웨이 주소}/api/v1/alimtalk/messages'   -H 'Authorization: Bearer {accessToken}'   --data-urlencode 'batchKey={batchKey}'   --data-urlencode 'size=100'

1분쯤 간격으로, 모든 건이 SUCCESS·FAIL·CANCELLED 중 하나가 될 때까지 조회합니다. 결과는 clientRef로 내 쪽 기록과 맞춥니다(목록 조회).

5. 토큰 관리

• 접근 토큰이 만료되기 전에 토큰 갱신하거나 토큰 발급을 다시 호출합니다.
• 호출 중에 401 AUTH-4013(만료)을 받으면 토큰을 새로 받은 뒤 다시 호출합니다.

Java 예제

Java 8과 Jackson으로 위 순서를 그대로 옮긴 예입니다. 키는 환경 변수에서 읽습니다.

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.util.UUID;

/** 알림 게이트웨이 연동 예제(Java 8, Jackson). 토큰 발급 → 대량 발송 → 결과 조회 */
public class NotifyGatewayExample {

    private static final String BASE_URL = "https://notify.reinno.com";
    private static final ObjectMapper JSON = new ObjectMapper();

    public static void main(String[] args) throws IOException {
        // 1) 토큰 발급. 받은 토큰은 만료(30분) 전까지 재사용한다.
        ObjectNode tokenReq = JSON.createObjectNode();
        tokenReq.put("grantType", "client_credentials");
        tokenReq.put("apiKey", System.getenv("NOTIFY_API_KEY"));
        tokenReq.put("secretKey", System.getenv("NOTIFY_SECRET_KEY"));
        JsonNode token = call("POST", "/oauth/token", null, null, tokenReq);
        String accessToken = token.path("data").path("accessToken").asText();

        // 2) 대량 발송(템플릿 방식, 1건)
        ObjectNode body = JSON.createObjectNode();
        ObjectNode template = body.putObject("template");
        template.put("senderKey", System.getenv("NOTIFY_SENDER_KEY"));
        template.put("callbackNo", "0212345678");
        template.put("templateCode", "SURVEY_START_01");
        template.put("body", "#{name}님, 『#{surveyName}』 설문이 열렸습니다.");
        ObjectNode item = body.putArray("items").addObject();
        item.put("recvNo", "01012345678");
        item.put("itemIdempotencyKey", UUID.randomUUID().toString()); // 다시 보낼 때 같은 값을 쓰도록 저장해 둔다
        item.put("clientRef", "25780");
        ObjectNode vars = item.putObject("variables");
        vars.put("name", "홍길동");
        vars.put("surveyName", "도민 만족도 조사");

        JsonNode sent = call("POST", "/api/v1/alimtalk/batches", accessToken,
                UUID.randomUUID().toString(), body);
        String batchKey = sent.path("data").path("batchKey").asText();
        for (JsonNode r : sent.path("data").path("results")) {
            if (!r.hasNonNull("messageId")) { // messageId 가 없으면 접수되지 않은 항목
                System.out.println("거절 index=" + r.path("index").asInt()
                        + " " + r.path("errorCode").asText() + " " + r.path("errorMessage").asText());
            }
        }

        // 3) 결과 조회. 실제로는 1분쯤 간격으로, 모든 건이 확정될 때까지 반복한다.
        JsonNode list = call("GET", "/api/v1/alimtalk/messages?size=100&batchKey="
                + URLEncoder.encode(batchKey, "UTF-8"), accessToken, null, null);
        for (JsonNode m : list.path("data").path("content")) {
            System.out.println(m.path("clientRef").asText() + " " + m.path("status").asText()
                    + " " + m.path("resultCode").asText("-"));
        }
    }

    private static JsonNode call(String method, String path, String accessToken,
                                 String idempotencyKey, JsonNode body) throws IOException {
        HttpURLConnection conn = (HttpURLConnection) new URL(BASE_URL + path).openConnection();
        conn.setRequestMethod(method);
        conn.setConnectTimeout(5000);
        conn.setReadTimeout(40000); // 대량 발송은 응답까지 최대 35초가 걸릴 수 있다
        if (accessToken != null) {
            conn.setRequestProperty("Authorization", "Bearer " + accessToken);
        }
        if (idempotencyKey != null) {
            conn.setRequestProperty("Idempotency-Key", idempotencyKey);
        }
        if (body != null) {
            conn.setDoOutput(true);
            conn.setRequestProperty("Content-Type", "application/json; charset=UTF-8");
            try (OutputStream out = conn.getOutputStream()) {
                out.write(JSON.writeValueAsBytes(body));
            }
        }
        int status = conn.getResponseCode();
        InputStream in = status < 400 ? conn.getInputStream() : conn.getErrorStream();
        JsonNode res = in == null ? JSON.createObjectNode() : JSON.readTree(in);
        if (status >= 400) {
            // 형식 A 는 code, 형식 B 는 error.code 에 오류 코드가 있다.
            String code = res.has("code") ? res.path("code").asText() : res.path("error").path("code").asText();
            throw new IOException("HTTP " + status + " " + code + " traceId=" + res.path("traceId").asText());
        }
        return res;
    }
}

연동 점검표

• Secret Key를 소스 코드에 넣지 않았다.
• 토큰을 재사용하고, 만료 전에 갱신한다.
• 발송 요청마다 새 Idempotency-Key를 만든다(1~64자).
• 대량 발송 항목마다 itemIdempotencyKey를 만들어 저장하고, 다시 보낼 때 같은 값을 쓴다.
• batchKey·messageId·clientRef를 저장한다.
• 응답의 messageId가 없는 항목을 실패로 처리한다.
• 결과는 1분쯤 간격으로 조회하고, SUCCESS·FAIL·CANCELLED만 최종으로 본다.
• 오류별로 다시 보낼지를 다시 보내기 표대로 판단한다.

토큰 발급

API Key와 Secret Key로 접근 토큰(access token)을 발급받습니다. 발송·조회 API는 이 토큰을 Authorization 헤더에 실어 호출합니다.

요청

요청 헤더

이 API는 Authorization과 Idempotency-Key가 필요 없습니다.

요청 바디

요청 예시

curl -X POST 'https://{게이트웨이 주소}/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{"grantType":"client_credentials","apiKey":"{API Key}","secretKey":"{Secret Key}"}'

응답

응답 바디

응답 상태 코드

응답 예시

{
  "success": true,
  "code": "AUTH-0000",
  "message": "토큰이 발급되었습니다.",
  "data": {
    "accessToken": "eyJraWQiOiJub3RpZnktYXV0aC0uLi4iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOi...",
    "tokenType": "Bearer",
    "expiresIn": 1800,
    "refreshToken": "rt_3q2-7wKx0bVd9mZ4u1Yk8fJcLhTnRpAsQeGiOyWvBxE",
    "scope": "send:sms send:email send:fax send:alimtalk"
  },
  "traceId": "4c1f0a9d2b7e3c55"
}

토큰 갱신

갱신 토큰으로 새 접근 토큰과 새 갱신 토큰을 받습니다. Secret Key를 다시 보내지 않아도 됩니다.

요청

요청 헤더

요청 바디

요청 예시

curl -X POST 'https://{게이트웨이 주소}/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{"grantType":"refresh_token","apiKey":"{API Key}","refreshToken":"{refreshToken}"}'

응답

응답 바디는 토큰 발급과 같습니다.

응답 상태 코드

요청·응답 규칙

모든 채널의 API에 똑같이 적용되는 요청 헤더와 응답 형식입니다.

공통 요청 헤더

응답

API에 따라 응답 형식이 두 가지입니다.

형식 A — 인증·발송 API, 게이트웨이 오류

{
  "success": false,
  "code": "AUTH-4013",
  "message": "인증 토큰이 만료되었습니다. 다시 로그인하세요.",
  "data": null,
  "traceId": "4c1f0a9d2b7e3c55"
}

형식 B — 결과 조회·예약 취소 API

지금은 결과 조회 API와 예약 취소 API(둘 다 알림톡·문자)가 이 형식을 씁니다. 다른 채널의 조회 형식은 각 채널 문서에 적습니다.

응답 헤더

응답 상태 코드

코드별 의미와 대처는 오류 코드를 참조해 주십시오.

시간대

• 응답의 시각은 모두 한국 시간(+09:00)이 붙은 ISO 8601입니다.
• 예약 시각처럼 요청에 넣는 일시에도 시간대를 반드시 붙입니다(예: 2026-10-10T09:00:00+09:00).
• 발송 쿼터의 하루·한 달 경계도 한국 시간 기준입니다.

문의할 때

응답 본문의 traceId와 응답 헤더 X-Trace-Id, 그리고 messageId(또는 batchKey)와 받은 code를 함께 알려 주시면 원인을 빨리 찾을 수 있습니다.

호출 한도

API Key와 프로젝트별로 호출 횟수와 발송 건수에 한도가 있습니다. 하루·한 달 발송 쿼터와 계약 초당 한도는 담당자가 안내합니다.

한도

한도를 넘었을 때

• Retry-After 초만큼 기다린 뒤 새 Idempotency-Key로 다시 보냅니다. 같은 키로 보내면 같은 429가 24시간 동안 돌아옵니다.
• RATE-4292(쿼터 초과)는 응답 헤더 X-Quota-Period(daily | monthly)로 어느 한도인지 알 수 있습니다. 하루 쿼터는 한국 시간 0시, 한 달 쿼터는 매월 1일에 초기화됩니다.
• 발송 API 응답의 X-RateLimit-Remaining으로 남은 호출 횟수를 볼 수 있습니다.

멱등 키와 다시 보내기

같은 발송 요청이 두 번 처리되지 않게 하는 규칙과, 오류를 받았을 때 다시 보내는 방법입니다.

Idempotency-Key

• 발송 요청마다 새로 만듭니다. 영문·숫자·하이픈 1~64자이고 UUID를 권장합니다.
• 같은 키로 24시간 안에 다시 보내면 새로 처리하지 않고 첫 응답을 그대로 돌려줍니다(응답 헤더 Idempotent-Replayed: true). 본문이 달라도 마찬가지이므로 다른 요청에 같은 키를 쓰지 마십시오.
• 오류 응답도 24시간 동안 그대로 돌려줍니다. 오류를 받은 뒤 고쳐서 다시 보낼 때는 새 키를 씁니다. 단 409와 5xx는 저장하지 않습니다 — 둘 다 결과가 아직 나오지 않았다는 뜻이라, 같은 키로 다시 보내면 결과를 확인할 수 있습니다.
• 첫 요청이 아직 처리 중일 때 같은 키로 보내면 409(RATE-4091 또는 SEND-4007)가 옵니다. Retry-After 뒤 같은 키로 다시 보내면 첫 응답을 받습니다.
• 같은 키로 다른 내용을 보내면 첫 응답을 돌려주지 않고 400 RATE-4002(또는 SEND-4002)로 거절합니다. 새 요청에는 새 키를 씁니다. 같은 요청을 다시 직렬화한 것(필드 순서·공백만 다름)은 같은 요청으로 봅니다.

다시 보내기

대량 발송의 항목 멱등 키처럼 채널마다 다른 규칙은 각 채널의 주의 사항에 있습니다(알림톡, 문자).

공통 오류 코드

채널과 상관없이 나오는 코드입니다. 채널별 발송·조회 오류는 각 채널의 오류 코드에 있습니다(알림톡, 문자). 응답 형식은 요청·응답 규칙을 참조해 주십시오.

게이트웨이·인증 (형식 A)

발송 공통 (형식 A)

채널과 상관없이 발송 API에서 나오는 코드입니다.

운영자 재발송·예약 취소

운영자는 콘솔에서 고객사의 실패 건을 다시 보내거나, 대기 중인 예약을 취소할 수 있습니다. 둘 다 고객사의 API Key로 처리되어 결과 조회에 그대로 보입니다. 고객사가 따로 호출할 것은 없지만, 결과를 내 쪽 기록과 맞출 때 알아 두어야 합니다.

재발송

• 운영자가 고른 실패 건만 다시 보냅니다. 자동으로 다시 보내지는 않습니다.
• 고객사의 API Key로 새로 발송합니다. 원래 메시지는 FAIL 그대로 남고, 다시 보낸 메시지는 새 메시지 키를 받습니다.
• 원래 보낸 본문·버튼·발신 정보 그대로, 예약 없이 바로 보냅니다.
• 원래 호출이 대량 발송이면 대량 발송으로 보내고 clientRef를 그대로 싣습니다. batchKey는 새로 생깁니다. 원래 호출이 단건이면 단건으로 보냅니다.
• 보통 발송과 똑같이 발송 쿼터를 씁니다.

다시 보내지 않는 건

• 결과가 실패가 아닌 건 — 대기·성공·취소, 결과를 확인하지 못한 건
• 다시 보내도 같은 결과인 건 — 수신번호 오류, 수신 차단
• 실제로는 도착했을 수 있는 건 — 알림톡 FAIL_TIME 중 도착 여부가 불확실한 건(FAIL_TIME 구분)
• 보낸 지 30일이 지난 건(예약 발송은 예약 시각부터 셉니다)
• 마지막 재발송이 이미 접수된 건

결과를 맞출 때

• 알림톡 결과를 기간으로 목록 조회하면 다시 보낸 메시지가 한 건 더 보입니다. 대량 발송이었다면 같은 clientRef로 보입니다. 같은 clientRef의 메시지 중 하나라도 SUCCESS면 전달된 것으로 보십시오.
• 원래 batchKey로만 조회하면 다시 보낸 메시지는 나오지 않습니다.
• 실패 건을 직접 다시 보내기 전에 담당자와 확인하십시오. 운영자 재발송과 겹치면 두 번 나갑니다.

예약 취소

• 운영자는 콘솔에서 대기 중인 예약을 한 건씩, 또는 대량 발송 단위로 모두 취소할 수 있습니다. 취소된 메시지는 CANCELLED로 조회됩니다.
• 고객사 이용이 정지·해지되면 남은 예약은 모두 자동으로 취소됩니다. 이용을 다시 열어도 취소된 예약은 되살아나지 않으니, 필요하면 새로 예약합니다.
• 프로젝트 정지나 키 폐기만으로는 남은 예약이 취소되지 않습니다.
• 어느 경우든 취소된 건의 발송 쿼터는 돌아옵니다(취소 뒤 몇 분 안).

고객사가 직접 취소할 때는 각 채널의 예약 취소 API를 씁니다(알림톡, 문자).

알림톡 단건 발송

수신자 한 명에게 알림톡을 보냅니다. 응답은 접수 결과이며, 실제로 전달됐는지는 발송 결과 조회로 확인합니다.

요청

요청 헤더

요청 바디

요청 예시

curl -X POST 'https://{게이트웨이 주소}/api/v1/alimtalk' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 6f1c2b8e-4d3a-4f1e-9b2c-7a5d8e9f0a11' \
  -d '{
  "recvNo": "010-1234-5678",
  "content": "#{고객명}님, 주문(#{orderNo})이 접수되었습니다.",
  "callbackNo": "0212345678",
  "alimTalk": {
    "senderKey": "{발신 프로필 키 40자}",
    "templateCode": "ORDER_ACCEPT_01",
    "adFlag": "N",
    "buttons": [
      { "name": "주문 조회", "type": "WL",
        "urlMobile": "https://m.example.com/orders/#{orderNo}",
        "urlPc": "https://www.example.com/orders/#{orderNo}" }
    ]
  },
  "variables": { "고객명": "홍길동", "orderNo": "A1001" }
}'

응답

응답 바디

data.messageId를 저장해 두십시오. 발송 결과 단건 조회의 messageKey로 씁니다. 응답 헤더 X-Message-Key에도 messageId가 들어 있습니다.

응답 상태 코드

응답 예시

{
  "success": true,
  "code": "SEND-0000",
  "message": "요청이 접수되었습니다.",
  "data": {
    "messageId": "100231",
    "channel": "ALIM_TALK",
    "status": "ACCEPTED",
    "acceptedAt": "2026-10-02T14:30:05.123+09:00"
  },
  "traceId": "3f9c2a7b1d4e5f60"
}

필드 검증 오류의 예입니다.

{
  "success": false,
  "code": "CMN-4001",
  "message": "입력값이 올바르지 않습니다.",
  "data": {
    "fieldErrors": [
      { "field": "alimTalk.senderKey", "message": "발신프로필키는 40자여야 합니다." }
    ]
  },
  "traceId": "3f9c2a7b1d4e5f60"
}

알림톡 대량 발송

한 번에 최대 500명에게 알림톡을 보냅니다. 같은 템플릿을 여러 명에게 보낼 때는 공통 템플릿 블록(template)을 한 번만 싣고, 항목에는 수신자와 치환값만 담습니다.

작성 방식

두 방식은 섞을 수 없습니다. template을 보내면서 항목에 content나 alimTalk을 넣으면 요청 전체를 거절합니다(400 CMN-4001).

요청

요청 헤더

단건 발송과 같습니다. Idempotency-Key는 요청(배치)마다 새로 만듭니다.

요청 바디

요청 예시 — 템플릿 방식

curl -X POST 'https://{게이트웨이 주소}/api/v1/alimtalk/batches' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 0c9e7d1a-5b2f-4a38-8e61-3f2d9c4b7a10' \
  -d '{
  "template": {
    "senderKey": "{발신 프로필 키 40자}",
    "callbackNo": "0212345678",
    "templateCode": "SURVEY_START_01",
    "adFlag": "N",
    "body": "#{name}님, 『#{surveyName}』 설문이 열렸습니다.",
    "buttons": [
      { "name": "설문 참여", "type": "WL",
        "urlMobile": "https://m.example.com/surveys/#{surveyId}",
        "urlPc": "https://www.example.com/surveys/#{surveyId}" }
    ]
  },
  "items": [
    { "recvNo": "01012345678", "itemIdempotencyKey": "talk7788-25780", "clientRef": "25780",
      "variables": { "name": "홍길동", "surveyName": "도민 만족도 조사", "surveyId": "S1001" } },
    { "recvNo": "010-9876-5432", "itemIdempotencyKey": "talk7788-25781", "clientRef": "25781",
      "variables": { "name": "김영희", "surveyName": "도민 만족도 조사", "surveyId": "S1001" } }
  ]
}'

응답

응답 바디

응답 헤더 X-Batch-Key에도 batchKey가 들어 있습니다.

응답 상태 코드

응답 예시

{
  "success": true,
  "code": "SEND-0000",
  "message": "배치 요청이 접수되었습니다.",
  "data": {
    "batchKey": "9f86d081884c4d659a2feaa0c55ad015",
    "channel": "ALIM_TALK",
    "accepted": 2,
    "rejected": 0,
    "results": [
      { "index": 0, "messageId": "100246", "status": "ACCEPTED", "errorCode": null, "errorMessage": null },
      { "index": 1, "messageId": "100247", "status": "ACCEPTED", "errorCode": null, "errorMessage": null }
    ]
  },
  "traceId": "a1b2c3d4e5f60718"
}

일부가 거절된 경우입니다.

{
  "success": true,
  "code": "SEND-0002",
  "message": "1건 접수, 1건 거절되었습니다.",
  "data": {
    "batchKey": "9f86d081884c4d659a2feaa0c55ad015",
    "channel": "ALIM_TALK",
    "accepted": 1,
    "rejected": 1,
    "results": [
      { "index": 0, "messageId": "100246", "status": "ACCEPTED", "errorCode": null, "errorMessage": null },
      { "index": 1, "messageId": null, "status": "REJECTED", "errorCode": "SEND-4002",
        "errorMessage": "요청 필드(수신처·발신프로필·발신번호·템플릿·요청시각)가 올바르지 않습니다." }
    ]
  },
  "traceId": "a1b2c3d4e5f60718"
}

알림톡 발송 결과 단건 조회

발송할 때 받은 메시지 키(messageId)로 알림톡 한 건의 발송 상태와 결과를 조회합니다.

요청

요청 헤더

Authorization: Bearer {accessToken}가 필요합니다. 자세한 내용은 공통 요청 헤더를 참조해 주십시오.

요청 경로 파라미터

요청 예시

curl -X GET 'https://{게이트웨이 주소}/api/v1/alimtalk/messages/100245' \
  -H 'Authorization: Bearer {accessToken}'

응답

응답 바디

값이 없는 필드는 null로 오지 않고 키 자체가 빠집니다. 예를 들어 결과를 기다리는 메시지에는 resultCode·resultAt이 없습니다.

응답 상태 코드

응답 예시

{
  "ok": true,
  "data": {
    "messageKey": "100245",
    "status": "SUCCESS",
    "resultCode": "SUCCESS",
    "resultAt": "2026-10-02T14:07:42+09:00",
    "recvNoMask": "010-****-5678",
    "clientRef": "12345",
    "templateCode": "SURVEY_START_01",
    "telecom": "SKT",
    "vendorResultCode": "100",
    "vendorResultCodeLabel": "SJ-100",
    "resultMessage": "정상 발송되었습니다."
  },
  "traceId": "9f1c3a7e5b2d4c60"
}

오류일 때는 data 대신 error가 옵니다.

{
  "ok": false,
  "error": { "code": "CMN-4041", "message": "대상을 찾을 수 없습니다." },
  "traceId": "9f1c3a7e5b2d4c60"
}

알림톡 발송 결과 목록 조회

조건에 맞는 메시지 목록을 조회합니다. 대량 발송 응답의 batchKey로 한 번에 보낸 메시지의 결과를 모아 볼 수 있습니다.

요청

요청 헤더

Authorization: Bearer {accessToken}가 필요합니다. 자세한 내용은 공통 요청 헤더를 참조해 주십시오.

요청 쿼리 파라미터

요청 예시

curl -G 'https://{게이트웨이 주소}/api/v1/alimtalk/messages' \
  -H 'Authorization: Bearer {accessToken}' \
  --data-urlencode 'batchKey=0a085cc5a74e4e38899797a936a369d6' \
  --data-urlencode 'size=100'

응답

응답 바디

결과가 없으면 content는 빈 목록이고 totalPages는 0입니다. 마지막 쪽을 넘는 page를 요청해도 오류 없이 빈 목록을 돌려줍니다.

응답 상태 코드

응답 예시

{
  "ok": true,
  "data": {
    "content": [
      {
        "messageKey": "100247",
        "status": "ACCEPTED",
        "recvNoMask": "010-****-9012",
        "clientRef": "12347",
        "templateCode": "SURVEY_START_01"
      },
      {
        "messageKey": "100246",
        "status": "SENT",
        "resultCode": "UNCERTAIN",
        "resultAt": "2026-10-02T14:07:45+09:00",
        "recvNoMask": "010-****-1234",
        "clientRef": "12346",
        "templateCode": "SURVEY_START_01",
        "vendorResultCode": "7109",
        "vendorResultCodeLabel": "KKO-7109",
        "resultMessage": "발송사가 아직 결과를 확정하지 못했습니다. 잠시 뒤 다시 확인하세요. 카카오가 수신 확인을 회신하지 않았습니다."
      },
      {
        "messageKey": "100244",
        "status": "FAIL",
        "resultCode": "FAIL_TEMPLATE",
        "resultAt": "2026-10-02T14:07:41+09:00",
        "recvNoMask": "010-****-3456",
        "clientRef": "12344",
        "templateCode": "SURVEY_START_01",
        "vendorResultCode": "3016",
        "vendorResultCodeLabel": "KKO-3016",
        "resultMessage": "알림톡 템플릿이 승인되지 않았거나 내용과 맞지 않습니다. 템플릿 심사 상태를 확인하세요."
      }
    ],
    "page": {
      "number": 0,
      "size": 100,
      "totalPages": 1,
      "numberOfElements": 3,
      "first": true,
      "last": true
    },
    "totalElements": 3
  },
  "traceId": "9f1c3a7e5b2d4c60"
}

대량 발송 결과를 모으는 방법

1. 대량 발송 응답의 batchKey와, 항목마다 넣은 clientRef를 저장해 둡니다. 결과는 clientRef로 내 쪽 기록과 맞춥니다(마스킹된 번호는 겹칠 수 있습니다).
2. batchKey로 목록을 조회하고 last가 true가 될 때까지 쪽을 넘깁니다(size=100 권장).
3. status가 SUCCESS·FAIL·CANCELLED인 건은 확정입니다. 나머지는 다음 주기에 다시 조회합니다.
4. 모든 건이 확정되면 그 배치의 조회를 끝냅니다.

알림톡 예약 취소

발송할 때 받은 메시지 키(messageId)로 아직 나가지 않은 알림톡 한 건을 취소합니다.

요청

요청 헤더

Authorization: Bearer {accessToken}가 필요합니다(공통 요청 헤더). Idempotency-Key는 쓰지 않습니다 — 취소는 몇 번 불러도 결과가 같습니다.

요청 경로 파라미터

요청 예시

curl -X DELETE 'https://{게이트웨이 주소}/api/v1/alimtalk/messages/100245' \
  -H 'Authorization: Bearer {accessToken}'

응답

형식 B로 옵니다.

응답 바디

응답 상태 코드

응답 예시

{
  "ok": true,
  "data": {
    "messageKey": "100245",
    "status": "CANCELLED",
    "cancelledAt": "2026-10-19T14:20:33.123+09:00",
    "traceId": "9f1c3a7e5b2d4c60"
  },
  "traceId": "9f1c3a7e5b2d4c60"
}

이미 나가는 중인 메시지를 취소하려 한 경우의 예입니다.

{
  "ok": false,
  "error": {
    "code": "SEND-4004",
    "message": "이미 처리되어 취소할 수 없다",
    "currentStatus": "SENDING",
    "currentStatCd": "1"
  },
  "traceId": "9f1c3a7e5b2d4c60"
}

알림톡 대량 예약 취소

대량 발송 응답의 batchKey로 그 요청에서 아직 나가지 않은 항목을 한꺼번에 취소합니다.

요청

요청 헤더

예약 취소와 같습니다.

요청 경로 파라미터

요청 예시

curl -X DELETE 'https://{게이트웨이 주소}/api/v1/alimtalk/messages/batches/b1f0a2c4111122223333444455556666' \
  -H 'Authorization: Bearer {accessToken}'

응답

형식 B로 옵니다.

응답 바디

응답 상태 코드

응답 예시

{
  "ok": true,
  "data": {
    "batchKey": "b1f0a2c4111122223333444455556666",
    "cancelledCount": 8,
    "skippedCount": 2,
    "status": "CANCELLED",
    "cancelledAt": "2026-10-19T14:25:10.456+09:00",
    "traceId": "9f1c3a7e5b2d4c60"
  },
  "traceId": "9f1c3a7e5b2d4c60"
}

알림톡 데이터 타입

요청과 응답에 쓰이는 객체의 필드를 정리했습니다.

AlimTalkOptions

단건 발송과 항목별 방식 대량 발송의 alimTalk 필드입니다.

AlimTalkButton

name·urlMobile·urlPc에도 #{변수}를 쓸 수 있습니다.

SendBatchTemplate

대량 발송 템플릿 방식의 template 필드입니다. templateCode·body·senderKey·callbackNo는 넷 다 있어야 합니다.

SendBatchItem

SendResult

단건 발송 응답의 data입니다.

SendBatchResult

대량 발송 응답의 data입니다.

Message

발송 결과 조회 응답의 메시지 한 건입니다. 값이 없는 필드는 키 자체가 빠집니다.

치환 변수 (variables)

본문과 버튼의 #{이름} 자리를 variables 값으로 채워서 보냅니다.

규칙

• 이름: 한글·영문·숫자·밑줄(_). 공백·하이픈·마침표는 쓸 수 없고, 대소문자를 구분합니다.
• 적용 위치: 본문(content, template.body)과 버튼의 name·urlMobile·urlPc. 발신 프로필 키·템플릿 코드·발신번호에는 적용되지 않습니다.
• 문자열 값: 같은 이름의 모든 자리에 같은 값이 들어갑니다.
• 문자열 배열 값: 자리마다 순서대로 하나씩 들어갑니다. 본문에 나오는 순서로 먼저 쓰고, 그다음 버튼 순서대로 버튼 하나당 한 칸을 씁니다(한 버튼의 name·urlMobile·urlPc는 같은 칸을 씁니다).
• 배열 길이는 실제로 쓰인 자리 수와 정확히 같아야 합니다. 어디에도 쓰이지 않은 배열 변수도 오류입니다. 쓰이지 않은 문자열 변수는 무시합니다.
• 숫자·참/거짓·객체는 값으로 쓸 수 없습니다. 숫자도 "2"처럼 문자열로 보냅니다.
• 값이 없거나 null이거나 빈 배열이면 오류입니다. variables를 보내지 않아도 본문에 #{…}가 남아 있으면 오류입니다.
• 본문에 글자 그대로의 #{를 쓸 수는 없습니다. 값 안에 든 #{는 그대로 들어갑니다.

배열 예시

{
  "content": "#{고객명}님, 1. #{surveyName} 2. #{surveyName}",
  "alimTalk": {
    "buttons": [
      { "name": "첫 번째 설문", "type": "WL", "urlMobile": "https://example.com/s/#{surveyId}?t=#{token}" },
      { "name": "두 번째 설문", "type": "WL", "urlMobile": "https://example.com/s/#{surveyId}?t=#{token}" }
    ]
  },
  "variables": {
    "고객명": "홍길동",
    "surveyName": ["설문A", "설문B"],
    "surveyId": ["S-1", "S-2"],
    "token": ["t1", "t2"]
  }
}

결과: 본문은 홍길동님, 1. 설문A 2. 설문B, 버튼 링크는 …/s/S-1?t=t1, …/s/S-2?t=t2가 됩니다(요청의 다른 필드는 줄였습니다).

오류 메시지

치환에 실패하면 요청 전체를 400 SEND-4006으로 거절하고, message에 이유를 적습니다. 자리 이름은 본문, 버튼[i].name, 버튼[i].urlMobile, 버튼[i].urlPc이고, 대량 발송에서는 앞에 items[n].이 붙습니다.

알림톡 상태·결과 코드

조회 응답의 status는 메시지가 어디까지 왔는지, resultCode는 최종 결과가 무엇인지 알려 줍니다.

상태 코드 (status)

SENDING은 목록 조회의 statusCd 필터 값으로 받지만, 지금은 이 상태로 남는 메시지가 없습니다.

결과 코드 (resultCode)

resultMessage에는 아래 문구가 그대로 들어갑니다. 내 화면에 사유를 보여 줄 때 그대로 써도 됩니다.

FAIL_TIME 구분

FAIL_TIME에는 성격이 다른 두 경우가 함께 들어 있습니다. vendorResultCode로 나눠 처리해 주십시오.

901·3005·7109에는 resultMessage 끝에 다음 문장이 붙습니다.

• 901: 발송사 결과 대기 시간이 초과되었습니다(세종 E_REP_TIMEOUT).
• 3005, 7109: 카카오가 수신 확인을 회신하지 않았습니다.

FAIL_TEMPLATE 구분

FAIL_TEMPLATE은 고칠 곳에 따라 resultMessage 문구가 다릅니다.

발송사 원본 코드

vendorResultCode는 발송사가 돌려준 원본 코드이고, vendorResultCodeLabel은 출처를 붙인 표기입니다.

문의할 때는 resultCode와 함께 vendorResultCodeLabel을 알려 주시면 원인을 빨리 찾을 수 있습니다.

알림톡 오류 코드

알림톡에서만 나오는 코드입니다. 인증·호출 한도·발송 공통 코드는 공통 오류 코드에 있습니다.

알림톡 발송 (형식 A)

대량 발송 항목 거절 코드

대량 발송 응답 results[].errorCode에 담기는 코드입니다. 해당 항목만 접수되지 않았습니다.

발송 결과 조회 (형식 B)

같은 CMN-4041이라도 게이트웨이(없는 경로)는 형식 A, 조회 API(없는 메시지)는 형식 B로 옵니다.

예약 취소 (형식 B)

알림톡 주의 사항

알림톡을 연동할 때 자주 놓치는 것들입니다. 모든 채널에 같은 규칙은 멱등 키·다시 보내기와 요청·응답 규칙을 참조해 주십시오.

항목 멱등 키 (itemIdempotencyKey)

• 수신자 한 명에게 보내는 한 통을 가리킵니다. 1~64자이고, 같은 배치 안에서 겹치면 안 됩니다.
• 다른 요청과도 겹치지 않게 만듭니다(UUID, 또는 {발송그룹ID}-{수신자ID}처럼 내 쪽에서 유일한 값).
• 같은 항목을 다시 보낼 때는 같은 값을 씁니다. 이미 접수된 항목은 새로 발송하지 않고 처음의 messageId를 돌려줍니다.

응답을 못 받았을 때

500·502·503·504를 받았거나 응답이 오지 않았으면 접수됐는지 알 수 없습니다.

• 대량 발송 — 새 Idempotency-Key로, 항목의 itemIdempotencyKey는 그대로 다시 보냅니다. 이미 접수된 항목은 새로 발송되지 않고 처음의 messageId를 돌려받습니다. 이렇게 돌려받은 항목은 새 batchKey로는 조회되지 않으니 messageId로 조회합니다.
• 단건 발송 — 응답을 못 받았을 때는 같은 Idempotency-Key로 다시 보내십시오. 먼저 보낸 요청이 접수됐으면 처음의 messageId를 그대로 돌려받고, 접수되지 않았으면 그때 발송됩니다. 아직 처리 중이면 409(SEND-4007)와 Retry-After가 오니 그 초만큼 기다린 뒤 같은 키로 다시 확인하십시오. 새 키로 바꿔 보내지 마십시오 — 먼저 보낸 요청이 접수됐는지 알 수 없어 두 번 갈 수 있습니다.

그 밖의 오류는 다시 보내기 표를 따릅니다.

단건과 대량 중 무엇을 쓰나

다시 보내기는 양쪽 모두 안전합니다. 여러 명에게 보내거나 결과를 내 쪽 기록(clientRef)과 맞춰야 하면 대량 발송을 쓰십시오 — 수신자가 한 명이어도 됩니다.

결과 조회

• 발송 응답은 "접수"까지만 알려 줍니다. 전달 결과는 목록 조회나 단건 조회로 가져갑니다.
• 결과 반영 주기가 30초이므로 1분 정도 간격으로 조회하면 충분합니다.
• SUCCESS·FAIL·CANCELLED가 될 때까지 조회합니다. SENT(UNCERTAIN)는 확정이 아니니 다시 보내지 말고 기다립니다.
• 목록 조회는 기본 31일, 최대 92일 범위입니다. 오래된 배치는 from·to를 지정합니다.

예약 발송

• scheduledAt을 넣으면 그 시각에 보냅니다. 지금보다 뒤, 지금부터 30일 안이어야 합니다(정확히 30일 뒤까지 받습니다).
• 응답을 못 받아 다시 보낼 때 예약 시각이 이미 지났다면 — 앞 요청이 접수됐으면 처음 접수 결과를 그대로 돌려받고, 접수되지 않았으면 400 SEND-4002(예약 시각은 지금보다 뒤여야 합니다)입니다. 그때는 새 시각과 새 키로 보냅니다.
• 보내기 전까지 예약 취소(메시지 키)나 대량 예약 취소(batchKey)로 취소할 수 있습니다. 예약 시각이 되어 발송 시스템이 가져간 뒤에는 취소할 수 없습니다(409 SEND-4004).
• 예약 시각까지는 ACCEPTED 상태로 조회됩니다. 취소하면 CANCELLED입니다.
• 운영자도 콘솔에서 예약을 취소할 수 있고, 고객사 이용이 정지·해지되면 남은 예약은 자동으로 취소됩니다(운영자 예약 취소).
• 취소한 건의 발송 쿼터는 돌아옵니다(취소 뒤 몇 분 안).

참조값과 개인정보

• clientRef에는 개인정보(이름·전화번호 등)를 넣지 마십시오. 내 쪽 일련번호 같은 값을 씁니다.
• 조회 응답의 수신번호는 가려서(010-****-5678) 돌려줍니다. 결과는 clientRef나 messageId로 맞춥니다.

문자 단건 발송

수신자 한 명에게 문자를 보냅니다. 본문 길이에 따라 단문(SMS)이나 장문(LMS)으로 나갑니다. 응답은 접수 결과입니다.

요청

요청 헤더

요청 바디

이 밖의 필드는 문자에서 쓰지 않으며 보내도 무시됩니다.

요청 예시

curl -X POST 'https://{게이트웨이 주소}/api/v1/sms' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 2b7e4f1a-9c3d-4e8b-a6f0-5d1c3b9e7a24' \
  -d '{
  "recvNo": "010-1234-5678",
  "content": "[리노] #{name}님, 인증번호는 #{code}입니다.",
  "callbackNo": "02-1234-5678",
  "variables": { "name": "홍길동", "code": "482913" }
}'

예약 발송 — 10월 20일 오전 9시(한국 시간)에 보내는 요청 바디입니다.

{
  "recvNo": "010-1234-5678",
  "content": "[리노] 오늘 오전 10시에 설문이 열립니다.",
  "callbackNo": "02-1234-5678",
  "sms": { "scheduledAt": "2026-10-20T09:00:00+09:00" }
}

응답

응답 바디

응답 헤더 X-Message-Key에도 messageId가 들어 있습니다. 같은 Idempotency-Key로 다시 보내 첫 응답을 돌려받을 때(Idempotent-Replayed: true)는 이 헤더가 없으니 본문의 messageId를 읽습니다.

단문과 장문은 치환한 본문의 길이로 정해지고, 무엇으로 접수됐는지는 data.msgType에 담깁니다. 길이 세는 법으로 미리 알 수도 있습니다.

응답 상태 코드

응답 예시

{
  "success": true,
  "code": "SEND-0000",
  "message": "요청이 접수되었습니다.",
  "data": {
    "messageId": "4f1c2a9e-0b7d-5e3a-9c41-2d8e6f0a1b3c",
    "channel": "SMS",
    "status": "ACCEPTED",
    "acceptedAt": "2026-10-15T10:04:05.123+09:00",
    "msgType": "SMS"
  },
  "traceId": "3f9c2a7b1d4e5f60"
}

본문이 너무 긴 경우의 예입니다.

{
  "success": false,
  "code": "SEND-4003",
  "message": "본문이 2000바이트(한글 1000자)를 넘습니다.",
  "data": null,
  "traceId": "3f9c2a7b1d4e5f60"
}

문자 대량 발송

한 번에 최대 500명에게 문자를 보냅니다. 같은 본문을 여러 명에게 보낼 때는 공통 블록(template)에 본문과 발신번호를 한 번만 싣고, 항목에는 수신자와 치환값만 담습니다.

작성 방식

두 방식은 섞을 수 없습니다. template을 보내면서 항목에 content나 sms를 넣으면 요청 전체를 거절합니다(400 CMN-4001).

요청

요청 헤더

단건 발송과 같습니다. Idempotency-Key는 요청(배치)마다 새로 만듭니다.

요청 바디

이 밖의 필드(발신 프로필 키·템플릿 코드·버튼 같은 알림톡 필드)는 문자에서 쓰지 않으며 보내도 무시됩니다.

요청 예시 — 템플릿 방식

curl -X POST 'https://{게이트웨이 주소}/api/v1/sms/batches' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 6f1e2d3c-4b5a-4c69-8d7e-1f2a3b4c5d6e' \
  -d '{
  "template": {
    "callbackNo": "02-1234-5678",
    "body": "[리노] #{name}님, 『#{surveyName}』 설문이 열렸습니다."
  },
  "items": [
    { "recvNo": "010-1234-5678", "itemIdempotencyKey": "notice7788-25780", "clientRef": "25780",
      "variables": { "name": "홍길동", "surveyName": "도민 만족도 조사" } },
    { "recvNo": "010-9876-5432", "itemIdempotencyKey": "notice7788-25781", "clientRef": "25781",
      "variables": { "name": "김영희", "surveyName": "도민 만족도 조사" } }
  ]
}'

모든 항목을 같은 시각에 예약하려면 template에 "scheduledAt": "2026-11-02T09:00:00+09:00"처럼 시각을 더합니다.

요청 예시 — 항목별 방식

수신자마다 본문과 예약 시각이 다른 요청 바디입니다. 두 번째 항목은 예약 시각이 없어 바로 나갑니다.

{
  "items": [
    { "recvNo": "010-1234-5678", "itemIdempotencyKey": "remind7790-25780", "clientRef": "25780",
      "content": "[리노] 홍길동님, 11월 2일 오전 10시 상담이 예약되어 있습니다.", "callbackNo": "02-1234-5678",
      "sms": { "scheduledAt": "2026-11-01T18:00:00+09:00" } },
    { "recvNo": "010-9876-5432", "itemIdempotencyKey": "remind7790-25781", "clientRef": "25781",
      "content": "[리노] 김영희님, 오늘 오후 3시 상담이 예약되어 있습니다.", "callbackNo": "02-1234-5678" }
  ]
}

응답

응답 바디

응답 헤더 X-Batch-Key에도 batchKey가 들어 있습니다. 같은 Idempotency-Key로 다시 보내 첫 응답을 돌려받을 때는 이 헤더가 없으니 본문의 batchKey를 읽습니다.

응답 상태 코드

응답 예시

{
  "success": true,
  "code": "SEND-0002",
  "message": "1건 접수, 1건 거절되었습니다.",
  "data": {
    "batchKey": "b1f0a2c4111122223333444455556666",
    "channel": "SMS",
    "accepted": 1,
    "rejected": 1,
    "results": [
      { "index": 0, "messageId": "4f1c2a9e-0b7d-5e3a-9c41-2d8e6f0a1b3c", "status": "ACCEPTED",
        "errorCode": null, "errorMessage": null, "msgType": "SMS" },
      { "index": 1, "messageId": null, "status": "REJECTED", "errorCode": "SEND-4002",
        "errorMessage": "수신번호 형식이 올바르지 않습니다." }
    ]
  },
  "traceId": "3f9c2a7b1d4e5f60"
}

문자 발송 결과 단건 조회

발송할 때 받은 메시지 키(messageId)로 문자 한 건의 발송 상태와 결과를 조회합니다.

요청

요청 헤더

Authorization: Bearer {accessToken}가 필요합니다. 자세한 내용은 공통 요청 헤더를 참조해 주십시오.

요청 경로 파라미터

요청 예시

curl -X GET 'https://{게이트웨이 주소}/api/v1/sms/messages/4f1c2a9e-0b7d-5e3a-9c41-2d8e6f0a1b3c' \
  -H 'Authorization: Bearer {accessToken}'

응답

형식 B로 옵니다.

응답 바디

값이 없는 필드는 null로 오지 않고 키 자체가 빠집니다. 예를 들어 결과를 기다리는 문자에는 resultCode·resultAt이 없습니다.

Message

조회 응답의 문자 한 건입니다. 목록 조회의 content에도 같은 모양으로 담깁니다.

본문·발신번호는 응답에 담지 않습니다.

응답 상태 코드

응답 예시

{
  "ok": true,
  "data": {
    "messageKey": "4f1c2a9e-0b7d-5e3a-9c41-2d8e6f0a1b3c",
    "status": "SUCCESS",
    "resultCode": "SUCCESS",
    "resultAt": "2026-10-26T14:07:42+09:00",
    "recvNoMask": "010-****-5678",
    "msgType": "SMS",
    "vendorResultCode": "0",
    "vendorResultCodeLabel": "NSC-0",
    "resultMessage": "정상 발송되었습니다."
  },
  "traceId": "3f9c2a7b1d4e5f60"
}

오류일 때는 data 대신 error가 옵니다.

{
  "ok": false,
  "error": { "code": "CMN-4041", "message": "대상을 찾을 수 없습니다." },
  "traceId": "3f9c2a7b1d4e5f60"
}

문자 발송 결과 목록 조회

조건에 맞는 문자 목록을 조회합니다. 대량 발송 응답의 batchKey로 한 번에 보낸 문자의 결과를 모아 볼 수 있습니다.

요청

요청 헤더

Authorization: Bearer {accessToken}가 필요합니다. 자세한 내용은 공통 요청 헤더를 참조해 주십시오.

요청 쿼리 파라미터

요청 예시

curl -G 'https://{게이트웨이 주소}/api/v1/sms/messages' \
  -H 'Authorization: Bearer {accessToken}' \
  --data-urlencode 'batchKey=b1f0a2c4111122223333444455556666' \
  --data-urlencode 'size=100'

응답

형식 B로 옵니다.

응답 바디

결과가 없으면 content는 빈 목록이고 totalPages는 0입니다. 마지막 쪽을 넘는 page를 요청해도 오류 없이 빈 목록을 돌려줍니다.

응답 상태 코드

응답 예시

{
  "ok": true,
  "data": {
    "content": [
      {
        "messageKey": "9c3e5b1a-7d2f-5a4c-8b6e-1f0a2d4c6e8b",
        "status": "ACCEPTED",
        "recvNoMask": "010-****-9012",
        "clientRef": "25782",
        "msgType": "SMS"
      },
      {
        "messageKey": "5d7a9c1e-3b4f-5e6a-9d8c-7b6a5f4e3d2c",
        "status": "FAIL",
        "resultCode": "FAIL_BLOCKED",
        "resultAt": "2026-10-26T14:07:45+09:00",
        "recvNoMask": "010-****-5432",
        "clientRef": "25781",
        "msgType": "SMS",
        "vendorResultCode": "101",
        "vendorResultCodeLabel": "NSC-101",
        "resultMessage": "수신자가 문자를 받을 수 없는 상태입니다(수신 거부·스팸 차단). 재발송해도 같은 결과입니다."
      },
      {
        "messageKey": "4f1c2a9e-0b7d-5e3a-9c41-2d8e6f0a1b3c",
        "status": "SUCCESS",
        "resultCode": "SUCCESS",
        "resultAt": "2026-10-26T14:07:42+09:00",
        "recvNoMask": "010-****-5678",
        "clientRef": "25780",
        "msgType": "SMS",
        "vendorResultCode": "0",
        "vendorResultCodeLabel": "NSC-0",
        "resultMessage": "정상 발송되었습니다."
      }
    ],
    "page": {
      "number": 0,
      "size": 100,
      "totalPages": 1,
      "numberOfElements": 3,
      "first": true,
      "last": true
    },
    "totalElements": 3
  },
  "traceId": "3f9c2a7b1d4e5f60"
}

대량 발송 결과를 모으는 방법

1. 대량 발송 응답의 batchKey와, 항목마다 넣은 clientRef를 저장해 둡니다. 결과는 clientRef로 내 쪽 기록과 맞춥니다(가린 번호는 겹칠 수 있습니다).
2. batchKey로 목록을 조회하고 last가 true가 될 때까지 쪽을 넘깁니다(size=100 권장).
3. status가 SUCCESS·FAIL·UNCONFIRMED·CANCELLED인 건은 확정입니다. 나머지는 다음 주기에 다시 조회합니다.
4. 모든 건이 확정되면 그 배치의 조회를 끝냅니다.

문자 예약 취소

예약 발송한 문자 한 건을 보내기 전에 취소합니다. 발송할 때 받은 메시지 키(messageId)를 씁니다.

요청

요청 헤더

Authorization: Bearer {accessToken}가 필요합니다(공통 요청 헤더). Idempotency-Key는 쓰지 않습니다 — 취소는 몇 번 불러도 결과가 같습니다.

요청 경로 파라미터

요청 예시

curl -X DELETE 'https://{게이트웨이 주소}/api/v1/sms/messages/4f1c2a9e-0b7d-5e3a-9c41-2d8e6f0a1b3c' \
  -H 'Authorization: Bearer {accessToken}'

응답

형식 B로 옵니다.

응답 바디

응답 상태 코드

응답 예시

{
  "ok": true,
  "data": {
    "messageKey": "4f1c2a9e-0b7d-5e3a-9c41-2d8e6f0a1b3c",
    "status": "CANCELLED",
    "cancelledAt": "2026-10-19T14:20:33.123+09:00",
    "traceId": "3f9c2a7b1d4e5f60"
  },
  "traceId": "3f9c2a7b1d4e5f60"
}

바로 보낸 문자를 취소하려 한 경우의 예입니다.

{
  "ok": false,
  "error": { "code": "SEND-4004", "message": "바로 보낸 문자는 취소할 수 없습니다. 예약 발송만 취소합니다." },
  "traceId": "3f9c2a7b1d4e5f60"
}

문자 대량 예약 취소

대량 발송 응답의 batchKey로 그 요청에서 아직 나가지 않은 예약 항목을 한꺼번에 취소합니다.

요청

요청 헤더

예약 취소와 같습니다.

요청 경로 파라미터

요청 예시

curl -X DELETE 'https://{게이트웨이 주소}/api/v1/sms/messages/batches/b1f0a2c4111122223333444455556666' \
  -H 'Authorization: Bearer {accessToken}'

응답

형식 B로 옵니다.

응답 바디

응답 상태 코드

응답 예시

{
  "ok": true,
  "data": {
    "batchKey": "b1f0a2c4111122223333444455556666",
    "cancelledCount": 8,
    "skippedCount": 2,
    "status": "CANCELLED",
    "cancelledAt": "2026-10-19T14:25:10.456+09:00",
    "traceId": "3f9c2a7b1d4e5f60"
  },
  "traceId": "3f9c2a7b1d4e5f60"
}

문자 상태·결과 코드

조회 응답의 status는 문자가 어디까지 왔는지, resultCode는 최종 결과가 무엇인지 알려 줍니다. 값은 알림톡과 다릅니다 — 알림톡의 SENDING·SENT, FAIL_TEMPLATE 같은 코드는 문자에 없습니다.

상태 코드 (status)

UNCONFIRMED 구분

UNCONFIRMED에는 성격이 다른 두 경우가 함께 들어 있습니다. resultMessage로 나눠 처리해 주십시오.

결과 코드 (resultCode)

resultMessage에는 아래 문구가 그대로 들어갑니다. 내 화면에 사유를 보여 줄 때 그대로 써도 됩니다.

resultCode가 없는 문자(ACCEPTED·RESERVED·PENDING)는 아직 결과를 기다리는 중입니다. PENDING에는 발송사가 보낸 원본 코드(vendorResultCode)만 있을 수 있습니다.

발송사 원본 코드

vendorResultCode는 발송사가 돌려준 원본 코드이고, vendorResultCodeLabel은 출처 NSC-를 붙인 표기입니다(예: NSC-0 성공, NSC-101 수신 거부). 문의할 때는 resultCode와 함께 vendorResultCodeLabel을 알려 주시면 원인을 빨리 찾을 수 있습니다.

문자 오류 코드

문자에서만 나오는 오류입니다. 인증·호출 한도·발송 공통 코드는 공통 오류 코드에 있습니다.

입력 오류 (400)

문자 요청이 규격에 맞지 않으면 400으로 답하고, 이유를 message에 적습니다. 필드 형식은 SEND-4002, 본문은 SEND-4003, 빠진 필드와 읽을 수 없는 값은 CMN-4001입니다. 고친 뒤 새 Idempotency-Key로 보냅니다.

그 밖의 응답

대량 발송 항목 거절 코드

대량 발송 응답 results[].errorCode에 담기는 코드입니다. 해당 항목만 접수되지 않았습니다.

발송 결과 조회 (형식 B)

결과 단건 조회·결과 목록 조회의 오류입니다. 응답은 error.code·error.message에 옵니다.

예약 취소 (형식 B)

예약 취소·대량 예약 취소의 오류입니다. 응답은 error.code·error.message에 옵니다.

문자 주의 사항

문자를 연동할 때 알아 둘 것들입니다. 모든 채널에 같은 규칙은 멱등 키·다시 보내기와 요청·응답 규칙을 참조해 주십시오.

아직 안 되는 것

결과 조회

• 발송 응답은 "접수"까지만 알려 줍니다. 전달 결과는 목록 조회나 단건 조회로 가져갑니다.
• 결과 반영 주기가 30초이므로 1분 정도 간격으로 조회하면 충분합니다.
• SUCCESS·FAIL·UNCONFIRMED·CANCELLED가 될 때까지 조회합니다. PENDING은 확정이 아니니 다시 보내지 말고 기다립니다.
• UNCONFIRMED는 실패가 아닙니다. 다시 보내기 전에 UNCONFIRMED 구분을 봅니다.
• 예약 문자는 예약 시각까지 RESERVED입니다. 목록 조회의 기간은 접수 시각 기준이고 기본 31일, 최대 92일입니다. 오래된 배치는 from·to를 지정합니다.

예약 발송과 취소

• 단건은 sms.scheduledAt, 대량은 template.scheduledAt(템플릿 방식) 또는 items[].sms.scheduledAt(항목별 방식)에 시각을 넣으면 그 시각에 보냅니다. 시간대가 붙은 ISO 8601(예: 2026-10-20T09:00:00+09:00)이고 지금보다 뒤, 지금부터 30일 안이어야 합니다(정확히 30일 뒤까지 받습니다). 초 아래는 버립니다. 시간대가 없으면 400 CMN-4001입니다.
• 항목별 방식에서 template에 scheduledAt만 넣으면 무시되고 바로 나갑니다(작성 방식).
• 보내기 전까지 예약 취소(메시지 키)나 대량 예약 취소(batchKey)로 취소할 수 있습니다. 예약 시각이 되어 발송 시스템이 가져간 뒤에는 취소할 수 없고, 바로 보낸 문자도 취소할 수 없습니다(409 SEND-4004).
• 예약 시각을 바꾸려면 취소한 뒤 새 키로 다시 예약합니다. 같은 키로 예약 시각만 바꿔 보내면 다른 요청으로 보고 거절합니다 — 단건은 400(RATE-4002 또는 SEND-4002), 대량은 같은 Idempotency-Key면 요청 전체가 400 RATE-4002, 아니면 같은 itemIdempotencyKey의 항목이 SEND-4002로 거절됩니다.
• 응답을 못 받아 다시 보낼 때 예약 시각이 이미 지났다면 — 앞 요청이 접수됐으면 처음 접수 결과를 그대로 돌려받고, 접수되지 않았으면 400 SEND-4002(예약 시각은 지금보다 뒤여야 합니다)입니다. 그때는 새 시각과 새 키로 보냅니다.
• 운영자도 콘솔에서 예약을 취소할 수 있고, 고객사 이용이 정지·해지되면 남은 예약은 자동으로 취소됩니다(운영자 예약 취소).
• 예약도 접수할 때 발송 쿼터를 차감하며, 보내는 날이 아니라 접수한 날·달의 쿼터로 셉니다. 취소한 건의 쿼터는 돌아옵니다(취소 뒤 몇 분 안, 호출 한도).

길이 세는 법

본문은 #{변수}를 채운 뒤의 길이로 셉니다.

윈도우 줄바꿈(\r\n)은 \n으로 바꿔서 셉니다. 맥 등에서 자모가 나뉜 채로 온 한글은 완성형으로 합친 뒤 셉니다.

보낼 수 없는 글자

본문은 문자 발송 시스템이 쓰는 한글 문자셋(CP949, 확장 완성형)으로 보냅니다. 여기에 없는 글자가 하나라도 있으면 400 SEND-4003(본문에 문자로 보낼 수 없는 글자(이모지 등)가 있습니다)으로 거절합니다. 워드·웹에서 복사한 본문에 자주 섞이는 글자는 이렇습니다.

다시 보내기

• 응답을 못 받았거나 502·503·504를 받았으면 접수됐는지 알 수 없습니다. 같은 Idempotency-Key로 다시 보내십시오. 먼저 보낸 요청이 접수됐으면 다시 나가지 않고 처음의 messageId를 돌려받습니다.
• 아직 처리 중이면 409 SEND-4007과 Retry-After가 옵니다. 그 초만큼 기다린 뒤 같은 키로 다시 확인합니다.
• 새 키로 바꿔 보내면 두 번 나갈 수 있습니다.
• 400(입력 오류)을 받았으면 고친 뒤 새 키로 보냅니다.
• 대량 발송은 항목마다 판정합니다. 거절된 항목만 모아 새 Idempotency-Key로 보내되, 항목의 itemIdempotencyKey는 바꾸지 않습니다.

개발 키로 시험할 때

• 개발 키로 보낸 문자는 실제로 나가지 않고 SEND-0003으로 답합니다. messageId는 mock-으로 시작합니다.
• 개발 키에서도 필수값(수신번호·본문·발신번호), 치환 변수, 등록된 발신번호인지(SEND-4008), 예약 시각의 형식은 운영과 같이 검사합니다.
• 번호 형식, 본문 길이·글자, 예약 시각이 지났는지·30일 안인지는 실제로 보낼 때 검사합니다. 이것까지 확인하려면 검증 키로 시험합니다.
• 개발 키로 받은 mock- 키는 예약 취소·결과 조회할 수 없습니다(404). 예약 취소와 결과 조회는 검증 키로 보내서 시험합니다.

이메일 API

이메일 발송 API는 준비 중입니다.

개통되면

• 이 묶음에 발송, 대량 발송, 결과 조회, 데이터 타입, 상태·결과 코드, 오류 코드, 주의 사항 문서가 추가됩니다.
• 토큰, 요청·응답 규칙, 호출 한도, 멱등 키·다시 보내기는 공통 문서를 그대로 따릅니다. 알림톡을 이미 연동했다면 같은 토큰으로 같은 방식으로 호출합니다.