알림톡 관리 API

카카오 알림톡 템플릿의 원본은 공급자(SOLAPI/알리고) 측에 있습니다. 템플릿 등록과 검수는 공급자 콘솔에서 진행하며, Posmit은 동기화 API로 가져온 스냅샷을 카탈로그로 캐시해 두고 발송 시 바인딩에 사용합니다. 검수 흐름과 바인딩 개념은 가이드 › 카카오 알림톡을 참고하세요.

이 문서의 엔드포인트는 모두 대시보드 API이며, 대시보드 인증의 로그인 세션(JWT) Bearer 토큰을 사용하고, 알림 API 키(HMAC)와는 별개입니다.

카탈로그의 본문·검수 상태는 마지막 동기화 시점의 스냅샷입니다. 공급자 쪽에서 검수 결과가 바뀌어도 다시 동기화하기 전까지는 반영되지 않습니다.

검수 상태

템플릿의 inspectionStatus는 다음 네 가지 값을 가집니다.

값	의미
`NONE`	검수 전
`INSPECTING`	검수 중
`APPROVED`	승인됨 — 발송에 사용할 수 있는 상태입니다.
`REJECTED`	반려됨 — 반려 사유는 `comments` 필드에서 확인합니다.

발신프로필 목록

GEThttps://api.posmit.io/v1/kakao/senders

동기화된 카카오 비즈채널 발신프로필 목록을 조회합니다. (역할: owner / admin / operator / viewer)

요청 파라미터는 없으며, 워크스페이스의 발신프로필 전체를 등록 순으로 반환합니다.


{
  "senderProfiles": [
    {
      "pfId": "KA01PF2510...",
      "name": "포스밋 스토어",
      "providerKind": "solapi_kakao",
      "searchId": "@posmit"
    }
  ]
}

필드	설명
`pfId`	발신프로필 키(senderKey). 알림톡에서 발신번호 역할을 합니다.
`name`	카카오톡 채널 이름
`providerKind`	연결된 공급자. `solapi_kakao` 또는 `aligo_kakao`
`searchId`	채널 검색용 아이디. 없으면 생략됩니다.

코드	HTTP	의미
`NOTI-40100`	401	Bearer 토큰이 없거나 유효하지 않음
`NOTI-40300`	403	워크스페이스 미선택

알림톡 템플릿 카탈로그

GEThttps://api.posmit.io/v1/kakao/templates

동기화된 알림톡 템플릿 카탈로그를 조회합니다. (역할: owner / admin / operator / viewer)

쿼리 파라미터는 없으며, 워크스페이스의 템플릿 전체를 등록 순으로 반환합니다.


{
  "alimtalkTemplates": [
    {
      "id": "9f3c...",
      "providerKind": "solapi_kakao",
      "pfId": "KA01PF2510...",
      "templateCode": "ORDER_SHIPPED",
      "name": "배송 시작 안내",
      "content": "#{고객명}님, 주문하신 상품이 발송되었습니다.",
      "messageType": "BA",
      "emphasizeType": "NONE",
      "securityFlag": false,
      "buttons": [
        { "buttonType": "WL", "buttonName": "배송 조회", "linkMo": "https://...", "linkPc": "https://..." }
      ],
      "quickReplies": [],
      "variables": ["고객명"],
      "inspectionStatus": "APPROVED",
      "source": "imported",
      "lastSyncedAt": "2026-07-10T09:00:00.000Z"
    }
  ]
}

필드	설명
`templateCode`	발송 시 매칭에 쓰는 템플릿 코드. `providerTemplateId`는 공급자 측 템플릿 ID입니다.
`content`	본문. 변수는 카카오 표기 `#{변수}`를 사용하며, 추출된 변수명이 `variables` 배열로 제공됩니다.
`messageType`	메시지 유형. `BA`(기본형) / `EX`(부가정보형) / `AD`(채널추가형) / `MI`(복합형)
`emphasizeType`	강조 유형. `NONE` / `TEXT`(강조표기형) / `IMAGE`(이미지형) / `ITEM_LIST`(아이템리스트형). 유형에 따라 `emphasizeTitle`, `emphasizeSubtitle`, `imageUrl`, `header`가 함께 제공됩니다.
`buttons` / `quickReplies`	버튼·빠른답장 배열. 각 항목은 `buttonType`(예: `WL` 웹링크, `AL` 앱링크), `buttonName`, `linkMo`, `linkPc`(버튼만)로 구성됩니다.
`inspectionStatus` / `comments`	검수 상태와 검수 코멘트(반려 사유 등). `requestedAt` / `inspectedAt`으로 검수 요청·완료 시각을 확인합니다.
`securityFlag`	보안 템플릿 여부
`source`	등록 출처. 동기화로 가져온 템플릿은 `imported`입니다.

코드	HTTP	의미
`NOTI-40100`	401	Bearer 토큰이 없거나 유효하지 않음
`NOTI-40300`	403	워크스페이스 미선택

템플릿 동기화

POSThttps://api.posmit.io/v1/kakao/templates/sync

공급자에서 알림톡 템플릿과 발신프로필을 가져와 카탈로그에 반영합니다. (역할: owner / admin / operator)

필드	타입	제약
`providerKind`	string	선택. `solapi_kakao` 또는 `aligo_kakao`를 지정하면 해당 공급자만 동기화합니다. 생략하면 전체 카카오 공급자가 대상입니다.


curl -X POST https://api.posmit.io/v1/kakao/templates/sync \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'


{
  "alimtalkTemplates": [ ... ],
  "added": 2,
  "updated": 5,
  "syncedAt": "2026-07-10T09:00:00.000Z"
}

alimtalkTemplates에는 동기화 후의 전체 카탈로그가 담기며, added / updated는 이번 동기화에서 새로 추가·갱신된 템플릿 수입니다.

동기화 동작은 다음과 같습니다.

워크스페이스에 등록된 활성화된(enabled) 카카오 공급자 계정만 대상으로 합니다.
템플릿은 providerKind + pfId + templateCode 조합을 식별 키로 upsert됩니다. 같은 키가 있으면 본문·검수 상태 등을 덮어쓰고, 없으면 새로 추가합니다. 발신프로필은 providerKind + pfId 조합으로 upsert됩니다.
부분 실패를 허용합니다. 한 공급자 계정의 조회가 실패해도 나머지 계정의 동기화는 계속 진행되며, 응답은 성공으로 반환됩니다. 실패한 계정의 템플릿은 added / updated에 반영되지 않습니다.

코드	HTTP	의미
`NOTI-40000`	400	`providerKind`가 허용 값이 아니거나, 정의되지 않은 필드 포함
`NOTI-40100`	401	Bearer 토큰이 없거나 유효하지 않음
`NOTI-40300`	403	viewer 역할이거나 워크스페이스 미선택

발송과의 관계

발송 시 Posmit 템플릿이 카탈로그의 알림톡 템플릿을 바인딩하고 승인(APPROVED) 여부를 검사하는 동작은 알림 발송 API를 참고하세요.