첫 연결, 세 단계로 시작하세요.
외부 서비스의 백엔드에서 호출합니다. 처음에는 연결 상태와 템플릿 목록을 조회해 준비 여부를 확인하세요.
- 1
계정과 애플리케이션 키 준비
rekeeping 운영 담당자를 통해 계정·애플리케이션·접근 키를 발급받습니다. 공개 회원가입·키 발급 API는 제공하지 않습니다. 최초 조회에는
templates:read권한이 필요합니다. - 2
연결 상태 확인
GET /v1/messaging/connection을 호출합니다.
sendable: false이면blockedReason을 확인하세요. HTTP 200만으로 발송 준비 완료를 뜻하지 않습니다. - 3
승인된 템플릿 조회
GET /v1/messaging/templates에서
id,version,price,variables를 가져옵니다. 빈 배열이면 사용 가능한 승인 템플릿이 없는 상태입니다.
이 문서는 예제를 복사하는 레퍼런스입니다. 브라우저에서 접근 키를 입력하거나 실제 발송·결제를 실행하지 않습니다. 별도 공개 샌드박스는 제공하지 않습니다.
https://rekeeping-api-production.up.railway.app용도에 맞는 키를 사용하세요.
모든 업무 API는 Authorization: Bearer <credential> 헤더로 인증합니다. 요청의 계정과 애플리케이션은 키로 결정됩니다.
애플리케이션 키
msg_app_…연결 확인, 템플릿 조회, 발송·조회·취소, SMS 인증에 사용합니다.
범위: 하나의 애플리케이션계정 관리 키
msg_mgmt_…채널·템플릿 설정, 애플리케이션 관리, 잔액·충전·환불에 사용합니다.
범위: 하나의 계정관리 API에는 applications:manage, wallet:read, orders:write 권한을 용도에 맞게 부여합니다. 발송 API에는 엔드포인트별 최소 권한을 부여하세요. 같은 계정의 애플리케이션 키라도 관리 API는 호출할 수 없습니다.
Content-Type: application/json을 사용하며 최대 본문 크기는 16 KiB입니다.채널과 템플릿을 연결하세요.
계정 관리 키로 검색용 ID와 템플릿 내용을 설정할 수 있습니다. 기본 경로는 /v1/management/applications/{application_id}입니다.
채널 설정
POST /channels에 name과 searchId 또는 channelUrl을 전달합니다. 검색 ID는 이미 보유한 카카오 채널의 ID입니다. 카카오 채널을 새로 만드는 API가 아닙니다.
발신키는 이후 PATCH /channels/{channel_id}로 추가할 수 있습니다. 발신키 자체는 응답에 포함되지 않고 senderKeyConfigured로 설정 여부만 확인합니다. 승인·정지된 채널은 수정할 수 없습니다.
템플릿 초안과 검토 요청
POST /templates로 초안을 만들고 PUT /templates/{template_id}로 전체 내용을 교체합니다. POST /templates/{template_id}/submit은 내부 운영 검토를 요청합니다. 반려된 초안을 수정하면 다시 draft 상태가 됩니다.
초안의 id는 설정·검토용입니다. 승인 후 반환되는 publishedTemplateId를 발송 API의 templateId로 사용하세요. pending은 내부 검토 대기이며 KIS 심사 접수·승인을 뜻하지 않습니다.
운영자가 공급자 승인 원문·버튼·발신 프로필을 확인한 후 코드와 단가를 확정합니다. 고객 요청으로 승인 상태·단가를 지정할 수 없습니다. 승인 내용 변경은 새 등록과 검토가 필요합니다.
접수와 전달 결과를 구분하세요.
POST /v1/messaging/send는 승인된 템플릿과 수신 동의 정보를 받아 발송을 접수합니다. HTTP 202는 접수·금액 예약 완료입니다. 최종 전달 완료가 아닙니다.
| 입력 | 사용 방법 |
|---|---|
templateId / templateVersion | 승인된 목록의 ID와 버전을 사용합니다. |
expectedPrice | 조회한 단가를 정수 KRW로 전달합니다. |
requestId | 논리적 요청마다 UUID를 생성하고 서버에 보관합니다. |
recipientConfirmed | 수신 대상과 동의를 확인한 후 true로 전달합니다. |
variables | 템플릿의 변수명과 정확하게 일치시킵니다. 서비스명은 서버가 채웁니다. |
queued → sending → accepted → reported
pending / delivered / failed / unknown
reserved → charged / released
응답이 끊겼다면 먼저 조회하세요.
GET /v1/messaging/requests/{request_id}로 기존 요청을 확인합니다. 동일한 requestId와 동일한 본문으로 재요청하면 기존 발송을 반환합니다. 내용이 다르면 IDEMPOTENCY_CONFLICT입니다. 불명확한 결과를 새 요청 ID로 자동 재발송하지 마세요.
상태는 GET /deliveries/{delivery_id}로 주기적으로 조회합니다. 웹훅은 제공하지 않습니다. queued 상태에서만 취소할 수 있으며, 템플릿 사용 중지는 이미 접수된 발송을 취소하지 않습니다.
실패를 예측 가능한 흐름으로.
일반 오류는 {"error":{"code":"ERROR_CODE"}} 형태입니다. 아래 기준으로 입력 수정, 상태 조회, 운영 확인을 분리하세요.
| HTTP | 대표 코드 | 처리 |
|---|---|---|
| 401 | INVALID_PROJECT_KEY | Bearer 형식·키·폐기 여부 확인 |
| 403 | INSUFFICIENT_SCOPE | 키 종류와 엔드포인트 권한 확인 |
| 404 | NOT_FOUND, TEMPLATE_NOT_FOUND | ID·소유 애플리케이션·승인 상태 확인 |
| 409 | IDEMPOTENCY_CONFLICT | 기존 요청 조회 후 원래 본문과 비교 |
| 409 | MESSAGE_PRICE_CHANGED, TEMPLATE_VERSION_CHANGED | 템플릿 목록을 다시 조회하고 사용자 확인 |
| 409 | INSUFFICIENT_BALANCE | 사용 가능한 잔액 확인 |
| 413 / 422 | BODY_TOO_LARGE, VALIDATION_ERROR | 본문 크기·필수 필드·타입 확인 |
| 429 | DAILY_MESSAGE_LIMIT, PHONE_SEND_LIMIT | 즉시 반복하지 않고 한도·재시도 간격 확인 |
| 503 | MESSAGING_NOT_CONFIGURED, SHARED_CHANNEL_NOT_APPROVED | 채널·공급자 설정을 운영 담당자에게 확인 |
400 {"detail":"PHONE_CODE_INVALID_OR_EXPIRED"}를 반환합니다.필요한 기능을 단계적으로 연결하세요.
SMS 인증
GET /v1/messaging/phone/config로 사용 가능 여부와 가격을 확인한 후 인증 요청을 생성합니다. subject는 서비스가 관리하는 사용자 UUID이며, 자신의 로그인 세션과 서버에서 연결해야 합니다. 인증번호는 5분간 유효하고 재요청 간격은 60초입니다. 검증 API 자체가 사용자 로그인 세션을 발급하지는 않습니다.
잔액과 결제
GET /v1/management/wallet의 available이 사용 가능한 금액입니다. 충전 주문 → 결제 확인 요청 → 내부 처리 순서로 진행되며, 결제 확인의 202도 최종 충전 완료를 의미하지 않습니다. 충전 주문은 10,000 / 30,000 / 50,000 / 100,000원을 지원합니다.
SMS와 결제는 계정·공급자 설정이 완료되어야 합니다. 미설정 시 각각 SMS_NOT_CONFIGURED, PAYMENTS_NOT_CONFIGURED가 반환됩니다. 경로가 존재한다고 실제 발송·결제가 가능한 것은 아닙니다.