발신프로필 API

발신프로필은 알림톡을 보내는 주체가 되는 카카오톡 채널 정보입니다. 사이트에 발신프로필이 등록되어 있어야 알림톡을 발송할 수 있으며, 미등록 상태에서 템플릿 자동 검수 신청·검수 요청·검수 취소처럼 카카오 발신프로필 키가 필요한 API를 호출하면 6001 에러가 반환됩니다. 에러 코드 전체는 공통 규약의 에러 형식과 코드를 참고하세요.

등록은 카카오톡 채널 관리자 휴대폰으로 인증번호를 받는 2단계 플로우이며, 그래서 등록 API도 2개입니다.

등록 1단계: 인증번호 요청 — 인증번호 발송을 요청하면, 카카오가 채널 관리자 휴대폰의 카카오톡으로 인증번호를 직접 전달합니다. 인증번호는 알마니를 거치지 않습니다.
채널 관리자(사람)가 카카오톡으로 수신한 인증번호를 확인합니다.
등록 2단계: 프로필 생성 — 수신한 인증번호(token)로 발신프로필을 최종 등록합니다. 성공하면 사이트의 알림톡 발송이 가능해집니다.

완전 무인 자동화는 불가합니다 인증번호를 수신하고 입력하는 주체는 사람(채널 관리자)입니다. 연동 프로그램이나 에이전트는 1단계 요청까지만 자동화할 수 있고, 2단계는 관리자가 확인한 인증번호를 전달받아 호출해야 합니다.

시작 전에 모든 요청에는 인증에서 발급한 API 키(Authorization: Bearer …)와 대상 사이트를 지정하는 X-Site-Id 헤더가 필요합니다. 예시의 ak_live_xxxx 는 더미 키입니다. 두 등록용 POST API는 선택 헤더 Idempotency-Key(최대 100자)를 지원하며, 같은 API 키·엔드포인트·사이트에서 동일한 키와 요청 바디를 사용하면 성공 응답을 24시간 재사용합니다. 사이트별 발신프로필 등록 여부는 사이트 목록 조회 응답의 senderProfileRegistered 필드로도 확인할 수 있습니다.

발신프로필 상태조회

GET /sender-profile

사이트의 발신프로필 등록 상태를 조회합니다. 별도의 파라미터 없이 X-Site-Id 헤더로 지정한 사이트 기준으로 조회됩니다. 필요 스코프: profile:read

Response

registered boolean

발신프로필 등록 여부입니다.

channelId string | null

카카오채널 검색용 ID입니다. 예: @알마니몰

profileName string | null

프로필명입니다.

status string

카카오 프로필 상태를 반영합니다. ACTIVE(정상) · BLOCKED(차단/휴면) · NONE(미등록) 중 하나입니다.

senderKeyMasked string | null

발신프로필 키의 앞 8자만 노출합니다(예: 0d1b245f…). 전문은 노출되지 않습니다.

registeredAt string | null

등록 시각입니다. ISO-8601, KST 오프셋 포함.

요청 예시

curl "https://docs.almani-center.com/open/v1/sender-profile" \
  -H "Authorization: Bearer ak_live_xxxx" \
  -H "X-Site-Id: 1024"

// Java 17 + Spring Framework 6 RestClient
RestClient restClient = RestClient.builder()
        .baseUrl("https://docs.almani-center.com/open/v1")
        .defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer ak_live_xxxx")
        .defaultHeader("X-Site-Id", "1024")
        .build();

String response = restClient.get()
        .uri("/sender-profile")
        .retrieve()
        .body(String.class);

응답 예시

HTTP/1.1 200 OK

{
  "code": "0000",
  "message": "OK",
  "data": {
    "registered": true,
    "channelId": "@알마니몰",
    "profileName": "알마니몰",
    "status": "ACTIVE",
    "senderKeyMasked": "0d1b245f…",
    "registeredAt": "2026-07-01T10:20:00+09:00"
  },
  "meta": {
    "requestId": "req_9f83ab21",
    "quota": {
      "rateLimit": {
        "limit": 120,
        "remaining": 119,
        "resetAt": "2026-07-25T14:31:00+09:00"
      }
    }
  }
}

HTTP/1.1 403 Forbidden

{
  "code": "4005",
  "message": "요청에 필요한 스코프가 없습니다. profile:read 스코프를 포함한 키로 다시 요청해 주세요.",
  "data": null,
  "meta": {
    "requestId": "req_9f83ab21",
    "quota": {
      "rateLimit": {
        "limit": 120,
        "remaining": 119,
        "resetAt": "2026-07-25T14:31:00+09:00"
      }
    }
  }
}

등록 1단계: 인증번호 요청

POST /sender-profile/token

카카오 채널 관리자 휴대폰으로 인증번호를 발송합니다. 필요 스코프: profile:write

인증번호 전달 경로 인증번호는 알마니를 거치지 않고 카카오에서 관리자 휴대폰(카카오톡)으로 직접 전달됩니다. API 응답에는 인증번호가 포함되지 않으며, 수신한 관리자가 직접 확인해 2단계 요청에 입력해야 합니다.

Request Body

channelId 필수 string

카카오채널 검색용 ID입니다. @ 를 포함해 입력합니다.

phoneNumber 필수 string

채널 관리자 휴대폰 번호입니다(010-…). 하이픈은 있어도 되고 없어도 됩니다.

Response

tokenSent boolean

인증번호 발송 성공 여부입니다.

expiresInSec number

인증번호 유효 시간(초)입니다. 유효 시간 안에 2단계 등록을 완료해야 합니다.

요청 예시

curl -X POST "https://docs.almani-center.com/open/v1/sender-profile/token" \
  -H "Authorization: Bearer ak_live_xxxx" \
  -H "X-Site-Id: 1024" \
  -H "Idempotency-Key: 615b33ad-1690-47a9-a710-0e112c5a8b19" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "@알마니몰",
    "phoneNumber": "010-0000-0000"
  }'

// Java 17 + Spring Framework 6 RestClient
RestClient restClient = RestClient.builder()
        .baseUrl("https://docs.almani-center.com/open/v1")
        .defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer ak_live_xxxx")
        .defaultHeader("X-Site-Id", "1024")
        .build();

record TokenRequest(String channelId, String phoneNumber) {}

var request = new TokenRequest("@알마니몰", "010-0000-0000");

String response = restClient.post()
        .uri("/sender-profile/token")
        .header("Idempotency-Key", "615b33ad-1690-47a9-a710-0e112c5a8b19")
        .contentType(MediaType.APPLICATION_JSON)
        .body(request)
        .retrieve()
        .body(String.class);

응답 예시

HTTP/1.1 200 OK

{
  "code": "0000",
  "message": "OK",
  "data": {
    "tokenSent": true,
    "expiresInSec": 300
  },
  "meta": {
    "requestId": "req_9f83ab21",
    "quota": {
      "rateLimit": {
        "limit": 120,
        "remaining": 118,
        "resetAt": "2026-07-25T14:31:00+09:00"
      }
    }
  }
}

HTTP/1.1 400 Bad Request

{
  "code": "4000",
  "message": "phoneNumber: 휴대폰 번호 형식이 올바르지 않습니다.",
  "data": null,
  "meta": {
    "requestId": "req_9f83ab21",
    "quota": {
      "rateLimit": {
        "limit": 120,
        "remaining": 118,
        "resetAt": "2026-07-25T14:31:00+09:00"
      }
    }
  }
}

등록 2단계: 프로필 생성

POST /sender-profile

채널 관리자가 카카오톡으로 수신한 인증번호로 발신프로필을 최종 등록합니다. 성공하면 발신프로필이 등록되고, 사이트의 알림톡 발송이 가능해집니다. 이후 템플릿 API로 템플릿을 등록해 카카오 심사를 진행할 수 있습니다. 필요 스코프: profile:write

Request Body

channelId 필수 string

1단계 요청과 동일한 값을 입력합니다.

phoneNumber 필수 string

1단계 요청과 동일한 값을 입력합니다.

token 필수 string

채널 관리자가 카카오톡으로 수신한 인증번호입니다.

categoryCode 필수 string

발신프로필 카테고리 코드입니다.

Response

registered boolean

발신프로필 등록 완료 여부입니다.

channelId string

등록된 카카오채널 검색용 ID입니다.

senderKeyMasked string

발신프로필 키의 앞 8자만 노출합니다(예: 1a9c33f0…).

registeredAt string

등록 시각입니다. ISO-8601, KST 오프셋 포함.

인증번호 불일치·만료 인증번호가 일치하지 않거나 만료된 경우 6000 에러가 반환되며, message 에 원본 사유가 포함됩니다. 이 경우 1단계 인증번호 요청부터 다시 진행해 주세요.

요청 예시

curl -X POST "https://docs.almani-center.com/open/v1/sender-profile" \
  -H "Authorization: Bearer ak_live_xxxx" \
  -H "X-Site-Id: 1024" \
  -H "Idempotency-Key: fa55ecda-63a5-45e9-a450-e21e9d61ecbc" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "@알마니몰",
    "phoneNumber": "010-0000-0000",
    "token": "123456",
    "categoryCode": "001001"
  }'

// Java 17 + Spring Framework 6 RestClient
RestClient restClient = RestClient.builder()
        .baseUrl("https://docs.almani-center.com/open/v1")
        .defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer ak_live_xxxx")
        .defaultHeader("X-Site-Id", "1024")
        .build();

record CreateSenderProfileRequest(
        String channelId, String phoneNumber,
        String token, String categoryCode) {}

var request = new CreateSenderProfileRequest(
        "@알마니몰", "010-0000-0000", "123456", "001001");

String response = restClient.post()
        .uri("/sender-profile")
        .header("Idempotency-Key", "fa55ecda-63a5-45e9-a450-e21e9d61ecbc")
        .contentType(MediaType.APPLICATION_JSON)
        .body(request)
        .retrieve()
        .body(String.class);

응답 예시

HTTP/1.1 200 OK

{
  "code": "0000",
  "message": "OK",
  "data": {
    "registered": true,
    "channelId": "@알마니몰",
    "senderKeyMasked": "1a9c33f0…",
    "registeredAt": "2026-07-25T14:41:27+09:00"
  },
  "meta": {
    "requestId": "req_9f83ab21",
    "quota": {
      "rateLimit": {
        "limit": 120,
        "remaining": 117,
        "resetAt": "2026-07-25T14:31:00+09:00"
      }
    }
  }
}

HTTP/1.1 502 Bad Gateway

{
  "code": "6000",
  "message": "인증번호가 일치하지 않거나 만료되었습니다. 인증번호를 다시 요청해 주세요.",
  "data": null,
  "meta": {
    "requestId": "req_9f83ab21",
    "quota": {
      "rateLimit": {
        "limit": 120,
        "remaining": 117,
        "resetAt": "2026-07-25T14:31:00+09:00"
      }
    }
  }
}