변경 이력

API 변경 사항을 기록합니다. 하위 호환이 되는 변경(필드 추가, 코드 추가)은 버전을 올리지 않고 반영되며, 호환이 깨지는 변경은 새 경로(/v2)로 제공하며, 이전 버전은 사전 공지 후 종료합니다.

v1

2026-11-07 — 발신번호 API 허용 절차 간소화

  • API 연동 화면에서 발신번호별 “API 사용 허용”을 별도 본인 인증 없이 스위치로 켜고 끌 수 있습니다. (관리자가 번호를 재승인하면 허용이 자동 해제되는 규칙은 동일)

2026-11-07 — API 키 허용 IP·만료일은 관리자가 관리

  • 보안 강화를 위해 키의 허용 IP 와 만료일은 관리자만 등록·변경합니다. 회원 사이트에서는 조회만 가능하며, 변경이 필요하면 1:1 문의로 요청해 주세요.
  • 허용 IP 가 등록되지 않은 키는 정책 적용 후 403 IP_WHITELIST_REQUIRED 로 거절됩니다. 키 발급 후 API 서버의 고정 공인 IP 를 알려 주세요.

2026-11-07 — 예약 취소 상태·금액 표시 정정, 프로필 사용 가능 표시 정정

  • 예약을 전부 취소하면 발송 건 status 가 CANCELLED 로 표시됩니다. (이전에는 COMPLETED 로 표시되던 오류) status=CANCELLED 필터도 동작합니다.
  • 취소·환불된 수신자의 charged 와 발송 건 amount 가 환불 후 0 으로 표시됩니다.
  • GET /v1/kakao/profiles 의 usable 이 정상 상태(차단·휴면 아님)인 프로필에서 true 가 됩니다. 정상이 아닌 프로필로 알림톡·브랜드를 보내면 422 PROFILE_NOT_USABLE 입니다.
  • 서버 내부 오류는 상세 문구 없이 500 INTERNAL_ERROR(request_id 로 문의)로 응답합니다.

2026-11-07 — 알림톡·브랜드메시지 “실패 시 문자 대체 발송” 제거

  • 알림톡·브랜드메시지 요청의 fallback 필드와 오류 코드 FALLBACK_SENDER_NOT_APPROVED 를 제거했습니다. 실패 시 문자로 대체 발송하지 않으며, 실패 건은 FAILED 로 종료되고 요금이 환불됩니다.
  • fallback 필드를 보내면 422 INVALID_REQUEST 를 반환합니다.

2026-11-07 — 접수 거절 상태(REJECTED) · 결과 코드 설명

  • 수신자 상태 REJECTED 와 Webhook 이벤트 message.rejected 추가 — 접수 후 발송 대행 단계에서 거절된 건이며 요금은 환불됩니다. 모르는 값은 “종료(실패)”로 처리하고 재발송 여부는 고객이 판단하세요.
  • 실패·성공 결과에 result.code / result.message(코드 설명) 제공 — 코드 표는 Webhook 문서 참고

2026-11-07 — 수신자 수 한도 명시

  • 한 요청 수신자 수: 동일 문구 1,000명 / 개별 문구 SMS·알림톡 1,000명, LMS·MMS 500명 (422 TOO_MANY_RECIPIENTS, details.max)

2026-11-06 — 최초 공개

  • 발송: SMS · LMS · MMS · 알림톡 · 브랜드메시지 (POST /v1/messages/{channel})
  • MMS 이미지 업로드 (POST /v1/files/mms)
  • 조회: 발송 목록 · 상세 · 수신자별 결과 (커서 페이지네이션), 예약 취소
  • 결과 Webhook: HMAC-SHA256 서명, 최대 100건 배치, 자동 재시도, 수동 재전송
  • 잔액 · 발신번호 · 카카오 발신프로필/템플릿 조회, 헬스 체크
  • 멱등성(Idempotency-Key), dry_run, client_ref, 부분 접수(rejected[])
  • API 키 해시 저장, 허용 IP(CIDR), 만료일, 발신번호별 API 허용

호환성 정책

  • 응답에 새 필드가 추가될 수 있습니다. 모르는 필드는 무시하도록 구현하세요.
  • error.code 목록에 새 코드가 추가될 수 있습니다.
  • 열거형 값(예: status)이 추가될 수 있으므로, 모르는 값은 “진행 중”으로 간주하고 조회 API 로 재확인하세요.
  • 필드 삭제·의미 변경은 하지 않습니다. 필요한 경우 새 버전 경로로 제공합니다.

OpenAPI 명세

기계가 읽을 수 있는 명세는 /v1/openapi.yaml 에서 내려받을 수 있으며, Postman·Insomnia 로 가져오거나 코드 생성기(openapi-generator 등)로 SDK 를 만들 수 있습니다.