공급자 관리

공급자(Provider) 계정은 채널별 발송 자격증명입니다. 알리고·SOLAPI·Resend 같은 외부 발송 서비스의 API 키를 워크스페이스에 등록해 두면, 발송 요청이 라우팅 규칙을 따라 해당 공급자로 전달됩니다. 등록한 공급자를 채널에 연결하고 우선순위·폴백을 구성하는 방법은 라우팅과 폴백을 참고하세요.

공급자 관리 엔드포인트는 대시보드 API입니다. Authorization: Bearer 헤더에 대시보드 액세스 토큰을 담아 호출하며, 토큰 발급은 대시보드 인증을 참고하세요.

providerKind 목록

providerKind는 “어느 서비스로 어느 채널을 보내는가”를 나타내는 값으로, 등록 후 변경할 수 없습니다. 발송 채널은 서버가 providerKind에서 자동으로 도출합니다.

configJson 키

공급자 자격증명은 configJson에 담아 등록합니다. 값은 전부 문자열이며, 저장 시 전체가 암호화되고 이후 어떤 조회 API에서도 반환되지 않습니다. 발송 어댑터가 실제로 읽는 키는 다음과 같습니다.

• 알림톡(aligo_kakao, solapi_kakao)의 발신프로필 키와 템플릿 ID는 configJson이 아니라 승인된 알림톡 템플릿에서 발송 시 자동 주입됩니다.
• Slack·Discord의 webhook 방식(slack_webhook, discord_webhook)은 등록한 URL에 연결된 채널로 보내므로 recipient.address가 필요 없습니다. bot 방식(slack_bot, discord_bot)은 보낼 채널을 recipient.address에 담아야 하며(Slack은 채널 이름·ID, Discord는 채널 ID), 기본 채널을 configJson에 지정하는 키는 없어 채널은 매 발송의 recipient.address로만 결정됩니다.
• 필수 키가 빠진 채 발송하면 해당 시도가 invalid_request로 실패합니다. 등록 시점에는 키를 검증하지 않으므로, 등록 후 아래 test-send로 설정을 점검하는 것을 권장합니다.

공급자 목록 조회

워크스페이스의 공급자를 생성 순으로 조회합니다. (역할: owner / admin / operator / viewer)

{
  "providers": [
    {
      "id": "3f2a9c1e-…",
      "providerKind": "solapi_sms",
      "displayName": "SOLAPI 운영",
      "enabled": true,
      "createdAt": "2026-07-01T09:00:00.000Z",
      "updatedAt": "2026-07-01T09:00:00.000Z",
      "quota": {
        "period": "month",
        "limit": null,
        "used": 0,
        "remainingCredit": 52340,
        "currency": "KRW"
      }
    }
  ]
}

configJson은 응답에 포함되지 않습니다.

quota는 공급자의 잔여 발송량(잔액) 입니다. SOLAPI(잔액, currency: "KRW")와 알리고(SMS·LMS·MMS 잔여 건수 합산, currency: "count")만 실제 값을 제공하며, 그 외 공급자이거나 조회에 실패하면 quota 필드 자체가 생략됩니다. 조회 결과는 60초간 캐시됩니다.

공급자 등록

새 공급자를 등록합니다. (역할: owner / admin / operator)

curl -X POST https://api.posmit.io/v1/providers \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "providerKind": "solapi_sms",
    "displayName": "SOLAPI 운영",
    "configJson": {
      "solapi_api_key": "NCS…",
      "solapi_api_secret": "X0…",
      "solapi_sender": "0212345678"
    }
  }'

{
  "provider": {
    "id": "3f2a9c1e-…",
    "providerKind": "solapi_sms",
    "displayName": "SOLAPI 운영",
    "enabled": true
  }
}

응답에도 configJson은 포함되지 않습니다.

단건 발송 (test-send)

라우팅·폴백 없이 지정한 공급자 하나로만 1건을 동기 발송합니다. (역할: owner / admin / operator) 채널은 공급자의 providerKind에서 도출되며, 발송 결과는 일반 발송과 동일하게 발송 요청·시도 이력에 기록됩니다.

채널별 주의사항은 다음과 같습니다.

• 알림톡: 자유 본문 발송이 불가하므로 content.templateCode가 필수이며, content.text는 무시되고 승인 템플릿 본문에 변수를 치환해 발송합니다. 템플릿이 미승인이거나 없으면 400, 같은 코드의 템플릿이 다른 공급자 소유이면 403이 반환됩니다.
• webhook 채널: 등록된 URL로 발송되므로 recipient.address를 생략합니다. 단, slack_bot·discord_bot 채널은 주소가 필요합니다.
• 이메일: 수신 차단 목록(suppression)에 있는 주소는 점검 발송이라도 거부되어 502가 반환됩니다.

curl -X POST https://api.posmit.io/v1/providers/3f2a9c1e-…/test-send \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "test",
    "recipient": { "address": "01012345678" },
    "content": { "text": "Posmit 발송 설정 점검 메시지입니다." }
  }'

{
  "requestId": "b7d0c4a2-…",
  "status": "sent",
  "mode": "test",
  "channel": "sms",
  "providerMessageId": "M4V2025…",
  "acceptedAt": "2026-07-11T09:00:00.000Z"
}

공통 에러

모든 공급자 관리 엔드포인트는 실패 시 application/problem+json 형식으로 응답합니다.

에러 형식의 자세한 내용은 에러 처리를 참고하세요.