템플릿 API

템플릿은 알림 본문을 코드 배포 없이 관리하기 위한 리소스입니다. 하나의 템플릿(channel + code + name)은 여러 버전을 가지며, 그중 발행(published) 상태인 버전은 항상 1개입니다. 발송 시점에는 발행 버전의 본문이 사용되므로, 버전을 발행하는 행위가 곧 배포입니다. 개념과 변수 문법은 가이드 › 템플릿을 참고하세요.

템플릿 API는 대시보드 API에 속하며 Bearer 토큰(JWT)으로 인증합니다. 토큰 발급은 대시보드 인증을 참고하세요. 성공 응답은 별도 envelope 없이 아래 예시 그대로 반환되고, 에러는 application/problem+json 형식입니다(에러 코드 참고).

버전 상태

템플릿 목록 조회

워크스페이스의 템플릿을 버전 이력과 함께 모두 조회합니다. (역할: owner / admin / operator / viewer)

쿼리 파라미터는 없습니다. 필터·페이지네이션 없이 전체 목록이 생성일 오름차순으로 반환되며, 각 템플릿의 versions는 버전 번호 오름차순입니다.

{
  "templates": [
    {
      "id": "…",
      "channel": "kakao_alimtalk",
      "code": "order_complete",
      "name": "주문 완료 안내",
      "enabled": true,
      "latestVersion": { "id": "…", "version": 2, "status": "published", "contentText": "…", "variablesSchema": { "고객명": "수신자 이름" }, "createdAt": "…" },
      "versions": [ … ],
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}

템플릿 생성

새 템플릿을 만들며, 버전 1이 published 상태로 자동 발행되어 즉시 발송에 사용할 수 있습니다. (역할: owner / admin / operator)

curl -X POST https://api.posmit.io/v1/templates \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "code": "order_complete",
    "name": "주문 완료 안내",
    "contentText": "#{고객명}님, 주문 #{주문번호} 접수가 완료되었습니다.",
    "variablesSchema": { "고객명": "수신자 이름", "주문번호": "주문 번호" }
  }'

응답은 생성된 템플릿 1건을 담은 { "template": { … } } 형태이며, versions에 발행된 버전 1이 포함됩니다.

새 버전 생성

기존 템플릿에 새 버전을 추가합니다. 버전 번호는 기존 최대 버전 + 1로 자동 부여됩니다. (역할: owner / admin / operator)

status: "published"로 만들면 생성과 동시에 발행되며, 기존 발행본은 archived로 전환됩니다.

{
  "version": {
    "id": "…",
    "version": 3,
    "status": "draft",
    "contentText": "…",
    "contentTitle": null,
    "contentHtml": null,
    "variablesSchema": { "고객명": "수신자 이름" },
    "createdAt": "…"
  }
}

버전 발행

지정한 버전을 발행하며, 요청 본문은 없습니다. (역할: owner / admin / operator)

발행 버전은 템플릿당 1개만 유지되므로, 기존 published 버전은 자동으로 archived로 전환됩니다. 응답은 새 버전 생성과 동일한 { "version": { …, "status": "published" } } 형태입니다.

AI 템플릿 생성

의도(자연어)를 입력하면 LLM이 채널에 맞는 템플릿 초안을 생성합니다. (역할: owner / admin / operator)

curl -X POST https://api.posmit.io/v1/ai/templates/generate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "kakao_alimtalk",
    "intent": "주문 완료를 안내하고 배송 조회를 유도",
    "tone": "정중하게",
    "variableHints": ["고객명", "주문번호"]
  }'

{
  "modelRef": { "provider": "vertex", "model": "gemini-2.5-flash" },
  "template": {
    "contentText": "#{고객명}님, 주문 #{주문번호} 결제가 완료되었습니다. …",
    "contentTitle": null,
    "contentHtml": null,
    "variablesSchema": { "고객명": "수신자 이름", "주문번호": "주문 번호" }
  },
  "validation": { "ok": true, "violations": [] }
}

모델 카탈로그

채널에서 사용 가능한 모델 목록을 조회합니다. channel 쿼리 파라미터는 필수이며, 유효하지 않으면 400이 반환됩니다. 응답은 { "models": [ { "model", "provider", "label", "channels", "recommended?" } ] } 형태입니다. (역할: owner / admin / operator / viewer)

* 텍스트 채널: sms, push_fcm, slack_webhook, slack_bot, discord_webhook, discord_bot

model을 지정하지 않았을 때의 채널 기본 모델은 다음과 같습니다.

자동 검증 violation 코드

생성 결과는 저장 전에 결정론적으로 사전 검증되며, 결과가 validation.violations에 담깁니다. severity: "error"가 하나라도 있으면 validation.ok가 false이며(발송·검수 차단 수준), warning은 권고입니다.

발송에서 사용하기

등록한 템플릿은 알림 API에서 content.templateCode로 참조합니다. 알림 발송 API › 템플릿 발송을 참고하세요.