카카오 알림톡 API

사전 승인된 템플릿으로 카카오 알림톡을 발송합니다. 실패 시 SMS로 자동 대체(failover)됩니다.

템플릿 생명주기

가맹점이 imsend 에 등록한 알림톡 템플릿은 4 단계 상태를 갖습니다.

REGISTERED ─[검수요청]─▶ INSPECTING ─[승인]─▶ APPROVED ─[삭제]─▶ DELETED
    ▲                                    │
    │              ◀─[반려]─┘
    └────[수정·재등록]──────────────────────┘

카카오 설정 조회

GET /api/v1/tenant/kakao

가맹점에 등록된 카카오 채널 ID·발신프로필 키·활성 상태·SMS 자동 대체 설정을 조회합니다. senderKey 는 보안상 마스킹되어 반환됩니다.

GET /api/v1/tenant/kakao
X-API-Key: your_api_key_here

응답 예시

{
  "success": true,
  "data": {
    "kakaoChId": "@문피디",
    "senderKey": "2b5cc1be***c371c3",
    "enabled": true,
    "failover": true,
    "updatedAt": "2026-05-26T00:26:53+09:00"
  }
}

설정이 없으면 data: null 을 반환합니다.

카카오 설정 등록·수정 (upsert)

PUT /api/v1/tenant/kakao

가맹점이 자신의 카카오 채널과 발신프로필 키를 직접 등록/수정합니다. 이미 있으면 갱신, 없으면 INSERT.

PUT /api/v1/tenant/kakao
X-API-Key: your_api_key_here
Content-Type: application/json

{
  "kakaoChId": "@myshop",
  "senderKey": "2b5cc1be902831e85479985a97012e28e7c371c3",
  "enabled": true,
  "failover": true
}

템플릿 목록 조회

GET /api/v1/alimtalk/templates

등록된 알림톡 템플릿 목록을 조회합니다.

GET /api/v1/alimtalk/templates?status=ALL
X-API-Key: your_api_key_here

응답 예시

{
  "success": true,
  "count": 1,
  "templates": [
    {
      "template_id": 123,
      "template_code": "WELCOME001",
      "template_name": "회원가입 환영",
      "content": "안녕하세요 #{name}님, #{serviceName}에 가입하신 것을 환영합니다.",
      "buttons": null,
      "variables": "[\"name\",\"serviceName\"]",
      "status": "APPROVED",
      "reject_reason": null,
      "inspected_at": null,
      "approved_at": "2026-05-25T23:17:38",
      "created_at": "2026-05-25T23:14:55"
    }
  ]
}

템플릿 상세

GET /api/v1/alimtalk/templates/{id}

특정 템플릿의 상세 정보(본문·버튼·변수·상태·이력)를 조회합니다.

GET /api/v1/alimtalk/templates/123
X-API-Key: your_api_key_here

응답 예시

{
  "success": true,
  "template": {
    "template_id": 123,
    "template_code": "mpd_005",
    "template_name": "이용권 만료 안내",
    "content": "[문피디] 이용권 만료 안내\n\n#{이름}님, ...",
    "buttons": "[{\"name\":\"연장하기\",\"type\":\"WL\",\"url_mobile\":\"...\",\"url_pc\":\"...\"}]",
    "variables": "[\"이름\",\"기간\",\"이용권정보\"]",
    "msg_type": "A",
    "status": "APPROVED",
    "reject_reason": null,
    "draft_content": null,
    "draft_status": null,
    "inspected_at": null,
    "approved_at": "2026-05-25T23:17:38",
    "created_at": "2026-05-25T23:14:55",
    "updated_at": "2026-05-25T23:17:38"
  }
}

템플릿 등록

POST /api/v1/alimtalk/templates/register

새 알림톡 템플릿을 imsend 에 등록합니다. 등록 시 상태는 REGISTERED 이며, 발송 가능하게 하려면 별도로 검수 요청 → 승인 단계가 필요합니다.

POST /api/v1/alimtalk/templates/register
X-API-Key: your_api_key_here
Content-Type: application/json

{
  "templateName": "이용권 만료 안내",
  "templateCode": "mpd_005",
  "content": "[문피디] 이용권 만료 안내\n\n#{이름}님, 귀하의 이용권이 #{기간}일 후에 만료됩니다.\n중단 없는 서비스를 원하신다면, 이용권을 갱신해 주세요!\n\n#{이용권정보}",
  "buttons": [
    {"name":"연장하기","type":"WL","url_mobile":"http://moonpd.ai/Home/H40000/priceInfo","url_pc":"http://moonpd.ai/Home/H40000/priceInfo"}
  ]
}

응답 예시

{
  "success": true,
  "templateId": 123,
  "templateCode": "mpd_005",
  "status": "REGISTERED",
  "variables": ["이름","기간","이용권정보"],
  "message": "템플릿이 등록되었습니다. 검수 요청 후 카카오 심사가 진행됩니다."
}

템플릿 수정

PUT /api/v1/alimtalk/templates/{id}

등록된 템플릿을 수정합니다. 현재 상태에 따라 동작이 다릅니다:

• REGISTERED · REJECTED → 본문·버튼 즉시 수정 후 상태 REGISTERED 로 초기화 (재검수 필요)
• APPROVED → draft 컬럼에 저장. 기존 본문은 유지되어 발송에 계속 사용. 재검수 통과 시 draft 가 main 으로 승격
• INSPECTING → 거부 (검수 진행 중)

PUT /api/v1/alimtalk/templates/123
X-API-Key: your_api_key_here
Content-Type: application/json

{
  "templateName": "이용권 만료 안내 v2",
  "content": "[문피디] 이용권 만료 안내\n\n...",
  "buttons": [ ... ]
}

검수 요청

POST /api/v1/alimtalk/templates/{id}/inspect

등록·수정된 템플릿(REGISTERED·REJECTED)을 imsend 관리자 검수 요청 상태(INSPECTING)로 전환합니다. 승인 완료 시 카카오 비즈센터 등록·발송에 사용 가능한 상태(APPROVED)로 바뀝니다.

POST /api/v1/alimtalk/templates/123/inspect
X-API-Key: your_api_key_here

응답 예시

{
  "success": true,
  "templateId": 123,
  "status": "INSPECTING",
  "message": "검수 요청이 완료되었습니다. 심사 결과는 1~3영업일 내 반영됩니다."
}

템플릿 삭제

DELETE /api/v1/alimtalk/templates/{id}

등록된 알림톡 템플릿을 삭제합니다. soft delete 방식으로 처리되어 발송 로그·감사 추적은 그대로 보존됩니다.

DELETE /api/v1/alimtalk/templates/123
X-API-Key: your_api_key_here

응답 예시

{
  "success": true,
  "templateId": 123,
  "status": "DELETED",
  "message": "템플릿이 삭제되었습니다."
}

알림톡 발송

POST /api/v1/alimtalk/send

승인된 템플릿(status='APPROVED')으로 알림톡을 발송합니다. senderKey·callback·버튼은 서버에서 자동 조회되므로 호출자는 보내지 않아도 됩니다.

요청 파라미터

요청 예시

POST /api/v1/alimtalk/send
X-API-Key: your_api_key_here
Content-Type: application/json

{
  "phone": "01012345678",
  "templateCode": "mpd_005",
  "variables": {
    "이름": "홍길동",
    "기간": "7",
    "이용권정보": "프리미엄 이용권",
    "상세주소": "Home/H40000/priceInfo"
  }
}

응답 예시

{
  "success": true,
  "batchId": "1e383c58",
  "mseq": 38949,
  "type": "ALIMTALK",
  "templateCode": "mpd_005",
  "unitPrice": 10,
  "maxChargeIfFailover": 35
}

• batchId: 추적용 UUID 앞 8자
• mseq: GT Agent 큐의 MSEQ. 발송 이력 조회 시 사용
• unitPrice: 알림톡 단가. 가맹점·설정별로 다를 수 있음 (PriceResolver 가 tenant 단가표 → config → 기본값 순으로 해석; fallback 기본 10원)
• maxChargeIfFailover: failover 발동 시 청구 가능 최대 금액 (LMS 단가, fallback 기본 35원)

// 템플릿 본문: "[문피디] #{이름}님, 귀하의 이용권이 #{기간}일 후에 만료됩니다."
// 템플릿 버튼 URL: "http://moonpd.ai/#{상세주소}"
// 요청 variables:
{
  "이름": "홍길동",
  "기간": "7",
  "상세주소": "Home/H40000/priceInfo"
}
// 발송 본문: "[문피디] 홍길동님, 귀하의 이용권이 7일 후에 만료됩니다."
// 발송 URL: "http://moonpd.ai/Home/H40000/priceInfo"

발송 이력

GET /api/v1/alimtalk/logs

알림톡 발송 이력을 조회합니다. (참고: 채널 무관 통합 이력은 /api/v1/sms/logs 사용 가능)

GET /api/v1/alimtalk/logs?page=1&size=20&status=DELIVERED
X-API-Key: your_api_key_here

필드 상세 안내

templateCode

가맹점이 imsend 에 등록한 템플릿의 식별 코드입니다. 대소문자·하이픈·언더스코어 자유로 사용 가능 (예: mpd_005, orderShipped001, WELCOME-V1). 단 카카오 비즈센터에 등록된 코드와 정확히 일치해야 발송 시 매칭됩니다.

senderKey

카카오 비즈센터에서 발급받은 40자리 소문자 16진수 발신프로필 키입니다.

형식: ^[0-9a-f]{40}$

보안상 응답 시 일부 마스킹되어 반환됩니다 (예: 2b5cc1be***c371c3).

kakaoChId

@ 로 시작하는 카카오 채널 ID. 현재 정규식 ^@[A-Za-z0-9_\-]{1,49}$ 검증 (영문·숫자·하이픈·언더스코어). 한글 채널명은 self-service API 에서 거부되므로 관리자 직접 등록이 필요합니다.

content (템플릿 본문)

imsend 가 등록·수정 시 각 라인 끝의 공백·탭을 자동 제거합니다. 카카오 비즈센터 등록본과의 글자 단위 일치를 위함입니다.

에러 / K-코드 진단

알림톡 발송·템플릿 엔드포인트 에러 (/api/v1/alimtalk/*)

알림톡 발송·템플릿 관리 엔드포인트의 일반 에러 응답에는 code 필드가 없으며 HTTP 상태 코드와 message 로 오류를 전달합니다. 예외: 발송 시 카카오 설정 관련 두 종(409)만 code 를 포함합니다.

{
  "success": false,
  "message": "사람이 읽을 수 있는 설명"
}

카카오 설정 엔드포인트 에러 (/api/v1/tenant/kakao)

카카오 설정 조회·등록(GET·PUT) 엔드포인트는 code 필드를 포함합니다.

{
  "success": false,
  "code": "ERROR_CODE",
  "message": "사람이 읽을 수 있는 설명"
}

참고: 카카오 / 게이트웨이 다운스트림 코드