# SENDLIVE Kakao API v1 기준: 2026-11-18 운영 API 코드. 기본 주소: `https://kakakapi.sendlive.kr/api/v1`. 기존 `kakao.sendlive.kr`은 유지됩니다. 새 도메인은 동일 발송 서버/DB를 사용하는 API 전용 진입점이며 별도 발송 사업자나 독립 서버가 아닙니다. ## 인증과 연동 준비 모든 API에 `X-API-Key`와 `X-API-Secret` 두 헤더가 필요합니다. JSON POST에는 `Content-Type: application/json`을 지정합니다. 관리자가 기존 카카오 관리자 화면의 API 클라이언트 관리에서 연동 서비스별 클라이언트를 발급하고 잔액/발신 프로필을 준비해야 합니다. 기존 샌드라이브 운영 키를 다른 서비스에 공유하지 마세요. 키는 연동 서비스의 백엔드 환경변수/비밀 저장소에만 보관합니다. 웹 브라우저, 모바일 앱, Git 저장소, URL에 넣지 마세요. 서버 간 연동용이며 CORS는 제공하지 않습니다. 새 도메인을 만든 것만으로 새 클라이언트가 발급되거나 기존 상점 프로필이 복사되지는 않습니다. `profileId`, `templateId`, `requestId`는 해당 API 클라이언트 소유여야 합니다. ```sh curl --fail-with-body https://kakakapi.sendlive.kr/api/v1/balance \ -H "X-API-Key: $SENDLIVE_KAKAO_API_KEY" \ -H "X-API-Secret: $SENDLIVE_KAKAO_API_SECRET" ``` ## API 목록 | Method | Path | 내용 | |---|---|---| | GET | /balance | 클라이언트 ID, 이름, 알림톡 잔액 | | POST | /profiles/token | 채널 관리자 휴대폰으로 인증번호 요청 | | GET / POST | /profiles | 내 발신 프로필 조회 / 등록 | | GET / POST | /templates | 내 템플릿 조회 / 검수 등록 | | POST | /templates/sync | 템플릿 검수 상태 동기화 (최대 200건 검사) | | GET | /fixed-templates | 정산서/독촉 기본 양식 조회 | | GET | /shop-fixed-templates | 상점용 공통 기본 양식 조회 | | POST | /send | 단건 동기 / 여러 수신자 비동기 발송 | | GET | /send/{requestId}/progress | 발송 요청 진행 상태 | | GET | /send/{requestId}/results | 수신자별 결과 (기본 limit=50, offset=0) | 기본 양식은 승인된 발송 템플릿이 아닙니다. 해당 클라이언트의 채널로 등록·승인된 템플릿이 필요합니다. 공개 카테고리 조회 API는 현재 없으므로 카테고리 코드는 관리자에게 확인합니다. ## 권장 순서 1. `/balance`로 인증 확인. `/profiles`에서 해당 클라이언트 프로필 확인. 2. 미등록 채널은 `/profiles/token`에 `yellowId`, `phoneNumber`를 보내고, 받은 `token`과 `categoryCode`를 추가해 `/profiles`에 등록. 3. `/templates`에 `profileId`, `templateName`, `templateContent`, `categoryCode`를 등록. `templateMessageType` 기본 BA, `templateEmphasizeType` 기본 NONE. 선택 항목은 `templateExtra`, `buttons`. 4. `/templates/sync` 후 목록의 `inspection_status`가 `approved`인지 확인. `sender_profile_id`가 보낼 프로필과 일치해야 합니다. 5. `/send`에 DB의 프로필 ID와 템플릿 ID를 전달. 공급사 `senderKey`나 `templateCode`가 아닙니다. 6. 받은 `requestId`를 저장하고 진행 상태와 결과를 조회. 3~5초 간격 조회를 권장하며 완료 또는 오류 시 반복 조회를 종료합니다. ## 발송 요청 예시 아래는 형식 예시입니다. 실제 수신번호와 승인 템플릿에 맞는 변수명으로 바꿔야 합니다. POST는 실제 발송/차감을 일으키므로 테스트 버튼이나 자동 실행은 제공하지 않습니다. ```json { "profileId": "<내 발신프로필 UUID>", "templateId": "<승인 템플릿 UUID>", "recipients": [ { "phone": "<수신번호>", "name": "고객명", "variables": { "고객명": "고객명" } } ] } ``` 단건 응답: `success`, `requestId`, `total`, `sent`, `failed`, `balance`, 실패 시 `error`. 대량 접수 응답: `success`, `requestId`, `total`, `balance`, `message`. HTTP 200이어도 `success: false`일 수 있습니다. `success: true`/`sent`는 접수 또는 공급사 전송 성공이며, 최종 휴대폰 수신을 보장하지 않습니다. 대량 `results`의 `delivered`/`failed`, `result_code`, `result_message`를 확인합니다. 현재 단건 경로는 수신자 결과 행을 별도로 남기지 않아 결과 목록이 비어 있을 수 있습니다. ## 현재 구현의 중요한 제한 - `Idempotency-Key` 및 정확히 한 번 발송 보장은 없습니다. 발송 POST가 타임아웃됐다고 자동 재전송하면 중복 발송될 수 있습니다. 요청 이력을 관리자에게 확인하고 재발송 여부를 결정하세요. - 대량 경로는 수신자별 `variables`를 보존하지 않습니다. 개인별 변수 발송은 현재 단건 순차 호출만 사용하고, 대량 개인화는 별도 개선 전 사용하지 마세요. - 잔액 처리와 동시 발송 확인은 원자적 트랜잭션이 아닙니다. 동일 클라이언트에서는 발송 작업을 직렬화해야 하며, 새 외부 서비스의 고동시성 상용 운영 전 별도 보강이 필요합니다. - 클라이언트 `environment` 값만으로 샌드박스 발송이 보장되지 않습니다. 실제 공급사 환경은 서버의 프로필/템플릿 라우팅 설정으로 결정됩니다. - 현재 v1 발송 코드의 잔액 계산은 수신자당 1입니다. 이를 실제 계약 단가로 해석하지 마세요. 요금·충전 정책은 관리자 확인이 필요합니다. - 새 도메인 요청 본문은 Nginx 기본 제한 1MiB를 적용합니다. 현재 v1은 수신자 수별 공식 상한·SLA·자동 재처리 보장을 제공하지 않습니다. - GET 목록은 무제한 전체 조회를 보장하지 않습니다. 결과 페이지는 `limit`, `offset`, 선택 `status`로 나눠 조회하세요. ## 오류 처리 | HTTP | 의미 | 대응 | |---|---|---| | 400 | 필수 입력 누락/공급사 요청 거절 | error 및 code 확인 | | 401 | 인증 헤더 누락/키 또는 Secret 불일치 | 서버 비밀값 확인 | | 403 | 비활성 API 클라이언트 | 관리자 확인 | | 402 | 잔액 부족 | 충전 후 새 발송 여부 판단 | | 404 | 리소스 없음 또는 다른 클라이언트 소유 | ID와 소유권 확인 | | 409 | 같은 클라이언트 대량 발송 진행 중 | 기존 requestId 진행 조회 | | 413 | 새 도메인 본문 크기 초과 | 크기 축소, 중복 발송 주의 | | 500/502/504 | 내부/업스트림 오류 | POST 자동 재시도 금지, 이력 확인 | 문의 시 시간(KST), HTTP 상태, `X-Request-ID` 응답 헤더, 발급받은 `requestId`, 엔드포인트를 전달하세요. 키·Secret·수신자 전체 개인정보는 보내지 마세요. 새 도메인은 관리자/내부 프록시/크론/결제 콜백을 노출하지 않습니다. `/api/admin`, `/api/proxy`, `/api/payments`, `/dashboard`는 404입니다.