알림톡 채널 일괄 연결 | Bootpay 결제 매뉴얼

리셀러가 자기 프로젝트에서 OTP 로 등록한 카카오 알림톡 채널을 하위 프로젝트들의 알림 설정에 연결한다. 하위 판매자마다 채널 OTP 를 다시 받지 않아도 되고, 그 채널에 이미 승인된 템플릿도 그대로 쓸 수 있다. 이 API 는 알림톡을 보내지 않는다 — 보내기는 아래 「하위 판매자 명의로 보내기」를 본다.

핵심 요약

연결할 수 있는 채널은 리셀러가 소유한 채널뿐이다: 리셀러 프로젝트에서 OTP 로 새로 발급받은 채널이고, 지금 리셀러 프로젝트에 연결돼 있어야 한다. 다른 가맹점이 발급한 채널을 키나 목록으로 가져와 연결만 한 경우는 소유가 아니다.
app_ids 는 본인 리셀러 하위 프로젝트만, 한 번에 20개까지. 결과는 프로젝트마다 하나씩(linked · exists · failed) 온다 — 일부가 실패해도 나머지는 연결된다.
하위 프로젝트가 자기 채널을 이미 쓰고 있으면 덮어쓰지 않는다(RESELLER_CHANNEL_TARGET_IN_USE). 판매자가 그 채널 연결을 해제한 뒤 다시 부른다. 같은 리셀러 소유의 다른 채널을 쓰던 프로젝트는 바꿔 끼운다.
이미 같은 채널이 연결된 프로젝트는 exists 로 오고 아무것도 바뀌지 않는다 — 실패한 것만 골라 다시 불러도 되고, 같은 목록으로 다시 불러도 안전하다.
연결하면 그 채널의 자체 템플릿을 하위 프로젝트도 보고·쓸 수 있다(템플릿은 채널 단위다). 하위 판매자가 콘솔에서 템플릿을 고칠 수 있다는 점을 알고 쓴다.
판매자가 콘솔에서 리셀러 채널을 스스로 가져다 쓸 수는 없다. 연결은 이 API 로 리셀러만 한다.

API 정보

POSThttps://api.bootpay.co.kr/v2/reseller/alimtalk/channel/linkBasic Auth (리셀러 계정 키)

요청 파라미터

파라미터	타입	필수	설명
`ksp_id`	String	필수	연결할 채널(발신 프로필) id. 리셀러 프로젝트 키로 `GET /alimtalk/senders` 를 부르면 나온다
`app_ids`	Array	필수	채널을 연결할 하위 프로젝트 `app_id` 목록. 1~20개, 같은 값은 한 번만 처리한다

코드 예제

import fetch from 'node-fetch'

const RESELLER_AUTH = 'Basic ' + Buffer
  .from(`${process.env.BOOTPAY_RESELLER_CLIENT_KEY}:${process.env.BOOTPAY_RESELLER_SECRET_KEY}`)
  .toString('base64')

const res = await fetch('https://api.bootpay.co.kr/v2/reseller/alimtalk/channel/link', {
    method: 'POST',
    headers: {
        'Authorization': RESELLER_AUTH,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        ksp_id: '6718a0aa8f1b5b00367a0300',
        app_ids: ['65a1c0ab8f1b5b00367a0002', '65a1c0ab8f1b5b00367a0003']
    })
})
const data = await res.json()
data.list.filter((row) => row.status === 'failed').forEach((row) => console.log(row.app_id, row.error_code))javascript

import base64, os, requests

auth = 'Basic ' + base64.b64encode(
    f"{os.environ['BOOTPAY_RESELLER_CLIENT_KEY']}:{os.environ['BOOTPAY_RESELLER_SECRET_KEY']}".encode()
).decode()

res = requests.post(
    'https://api.bootpay.co.kr/v2/reseller/alimtalk/channel/link',
    headers={'Authorization': auth},
    json={
        'ksp_id': '6718a0aa8f1b5b00367a0300',
        'app_ids': ['65a1c0ab8f1b5b00367a0002', '65a1c0ab8f1b5b00367a0003']
    }
)
print(res.json())python

RESELLER_AUTH=$(printf '%s' "$BOOTPAY_RESELLER_CLIENT_KEY:$BOOTPAY_RESELLER_SECRET_KEY" | base64)

curl -X POST 'https://api.bootpay.co.kr/v2/reseller/alimtalk/channel/link' \
  -H "Authorization: Basic $RESELLER_AUTH" \
  -H 'Content-Type: application/json' \
  -d '{"ksp_id":"6718a0aa8f1b5b00367a0300","app_ids":["65a1c0ab8f1b5b00367a0002","65a1c0ab8f1b5b00367a0003"]}'bash

응답

{
  "ksp_id": "6718a0aa8f1b5b00367a0300",
  "list": [
    {
      "app_id":               "65a1c0ab8f1b5b00367a0002",
      "status":               "linked",
      "project_id":           "65a1c0ab8f1b5b00367a0006",
      "ksp_id":               "6718a0aa8f1b5b00367a0300",
      "yellow_id":            "@example_channel",
      "channel_name":         "예시 채널",
      "group_key_registered": true
    },
    {
      "app_id":     "65a1c0ab8f1b5b00367a0003",
      "status":     "failed",
      "error_code": "RESELLER_CHANNEL_TARGET_IN_USE",
      "message":    "하위 프로젝트에 이미 다른 알림톡 채널이 연결되어 있습니다. 하위 가맹점이 연결을 해제한 뒤 다시 시도해 주세요."
    }
  ],
  "success_count": 1,
  "failure_count": 1
}json

응답 파라미터

파라미터	타입	설명
ksp_id	String	요청한 채널 id
list	Array	프로젝트별 결과(요청 순서, 중복 제거)
list[].app_id	String	하위 프로젝트 식별자
list[].status	String	`linked` 이번에 연결 · `exists` 이미 연결돼 있음 · `failed` 실패
list[].project_id	String	커머스 프로젝트 식별자(성공일 때)
list[].yellow_id	String	채널 검색용 아이디(성공일 때)
list[].channel_name	String	채널 이름(성공일 때)
list[].group_key_registered	Boolean	공식 템플릿을 쓸 수 있는 채널인지(부트페이 그룹 등록). `false` 면 자체 템플릿만 쓸 수 있다
list[].error_code	String	실패 원인 코드(`failed` 일 때, 아래 표)
list[].message	String	실패 사유(`failed` 일 때)
success_count	Number	`linked` + `exists` 수
failure_count	Number	`failed` 수

프로젝트별 실패 원인 (`list[].error_code`)

코드	메시지	대처 방법
`RESELLER_CHANNEL_NOT_OWNER`	리셀러가 직접 등록한 알림톡 채널만 하위 프로젝트에 연결할 수 있다	리셀러 프로젝트에서 그 채널을 OTP 로 직접 등록한 경우에만 연결할 수 있다
`SENDER_NOT_LINKED`	연결된 발신 프로필이 없다	`ksp_id` 가 맞는지, 그 채널이 지금 리셀러 프로젝트에 연결돼 있고 막히지 않았는지 본다
`RESELLER_CHANNEL_TARGET_IN_USE`	하위 프로젝트에 이미 다른 알림톡 채널이 연결되어 있다	판매자가 알림 설정에서 기존 채널 연결을 해제한 뒤 다시 부른다
`PROJECT_NOT_FOUND`	커머스 프로젝트가 없다	커머스 연동 재시도 로 먼저 만든다
`APP_NOT_FOUND`	프로젝트를 찾지 못했다	`app_id` 가 올바른지 확인한다
`APP_NOT_PERMIT`	본인 하위 프로젝트가 아니다	본인 리셀러 하위 셀러의 프로젝트인지 확인한다
`(없음)`	커머스 연동 서버에 닿지 못했다	그 뒤 프로젝트는 부르지 않고 같은 사유로 실패 처리된다. 잠시 뒤 같은 목록으로 다시 부른다

요청 전체 오류: ALIMTALK_CHANNEL_LINK_INVALID(8193, HTTP 400) — ksp_id 가 비었거나 app_ids 가 0개·21개 이상. API_ONLY_RESELLER — 리셀러 계정 키가 아니다.

하위 판매자 명의로 보내기

하위 판매자(강사)의 채널로 수강생에게 보내는 흐름이다. 새 발송 API 는 없고, 기존 알림톡 API(https://message.bootapi.com/alimtalk)를 하위 프로젝트의 커머스 키로 부른다.

채널 준비 — 둘 중 하나.
- 리셀러 프로젝트 키로 그 판매자의 카카오 채널을 OTP 로 등록한다(POST /alimtalk/senders/otp → POST /alimtalk/senders). 그다음 이 API 로 판매자의 하위 프로젝트에 연결한다. 리셀러 프로젝트에는 채널이 하나만 연결되므로, 다음 판매자 채널을 등록하기 전에 먼저 연결해 둔다.
- 또는 처음부터 하위 프로젝트 커머스 키로 OTP 등록을 한다. 이때 채널은 그 판매자 것이 되고 이 API 는 필요 없다.
템플릿 — 자체 템플릿은 채널에 묶인다. 그 채널에 승인된 자체 템플릿은 연결된 모든 하위 프로젝트에서 쓸 수 있다. 공식 템플릿은 group_key_registered: true 인 채널에서 쓸 수 있다.
보내기 — 리셀러 서버가 POST https://message.bootapi.com/alimtalk/send 를 하위 프로젝트의 커머스 키(생성 응답의 commerce.key_chain)로 부른다. 채널은 그 프로젝트에 연결된 채널로 정해지고, 발송 결과 웹훅은 하위 프로젝트 설정이나 요청의 webhook_url 로 받는다.
요금 — 발송 비용은 그 하위 판매자의 메시지 요금제에서 나간다. 하위 판매자가 선불(첫 충전 완료) 또는 직접 납부 요금제가 아니면 NOTIFICATION_NEED_PAYMENT(3503)·SERVICE_PAYMENT_BLOCKED(11100)·MESSAGE_PREPAID_NOT_CHARGED(11101, 선불 첫 충전 전)로 막힌다. 리셀러 잔액에서 하위 발송분을 빼는 기능은 아직 없다.