2. 단일 건 발송

개요

특정 대상자에게 즉시 또는 단발성 메시지 발송이 필요한 경우 사용하는 방식입니다.

본 발송 방식은 사용자 편의를 위해 서로 다른 브랜드 메시지를 최대 100건까지 한 번에 묶어 전송할 수 있으며, 메시지 정보 내 치환 문구가 존재하는 경우, 대상자별로 해당 값을 치환하여 발송할 수 있습니다.

단, 과도한 단일건 발송 API 호출로 서비스의 트래픽을 발생시킬 경우 사전경고 없이 서비스의 제약을 받을 수 있습니다.

API Server URL: https://bizmsgapi.fingerpush.com/rest/kkb/v1/sendDirectBrandMsg/free

발송 방법 및 전송/수신 파라미터 정의

HTTPS Headers

파라미터명	필수 여부	설명
Content-Type	필수	application/json
authorization	필수	Bearer {token} 토큰 발급 API에서 발급받은 JWT 토큰 값

HTTPS Parameters

SSL Protocol을 이용하여 파라미터들을 API Server에 전달합니다.

API Server로 전달해야 할 파라미터들은 아래 표를 참조해 주세요.

[표 2.1] 단일 건 발송 HTTPS, Parameters

파라미터명	필수 여부	Data Type	설명
senderKey	필수	text(40)	카카오 발신프로필 키
sendStatus	선택	text(4)	0001: 바로 발송(default) 0002: 예약발송
sendDate	선택	text(20)	발송 시간 yyyy-MM-dd HH:mm:ss
msgData	필수	list	발송용 메시지 JSON Array
msgData.senderKey	필수	text(40)	카카오 발신프로필 키
msgData.msgKey	필수	text	구분용 키
msgData.messageType	필수	text(2)	메시지 유형 FT – 텍스트형 FI – 이미지형 FW – 와이드 이미지형 FL – 와이드 아이템 리스트형 FC – 캐러셀 피드형 FP – 프리미엄 동영상형 FM – 커머스형 FA – 캐러셀 커머스형
msgData.recipient	필수	text(20)	수신자 번호
msgData.idType	선택	text(3)	수신 대상자 타입 RCT: 수신자 전화번호 (default) AUI: 앱유저 아이디 KUK: 카카오톡 채널 사용자 식별 키
msgData.orgCode	선택	text(20)	부서 코드 (핑거푸시 사이트에서 발급받은 부서 코드)
msgData.header	선택	text(20)	와이드 아이템리스트, 프리미엄 동영상형 메시지 타입에 표기할 제목
msgData.message	선택	text	사용자에게 전달될 메시지 텍스트형 - 최대 1,000자 (줄바꿈: 최대 33개, URL 형식 입력 가능) 이미지형 - 최대 400자 (줄바꿈: 최대 29개) 와이드 이미지형 - 최대 76자 (줄바꿈: 최대 1개) 프리미엄 동영상형 - 최대 76자 (줄바꿈: 최대 1개)
msgData.additional_content	선택	text(34)	부가 정보 (공백 포함 34자로 제한) 커머스 타입(FM, FA)에서 사용
msgData.attach	선택	object	버튼/이미지/아이템/커머스 정보 등
msgData.carousel	선택	object	캐러셀 정보
msgData.adult	선택	text(1)	성인용 메시지 여부 (default: N)
msgData.useFailback	선택	text(1)	문자 재처리 사용 여부(N:사용안함, Y:사용)
msgData.mmsAttach	선택	object	전환 발송용 문자 재처리 정보 JSON
msgData.mmsAttach.mmsContent	필수	byte(2000)	문자 메시지 내용 (90Byte이하일 경우 : SMS로 발송, 90Byte초과시는 LMS로 발송)
msgData.mmsAttach.subject	필수	byte(40)	문자 메시지 제목
msgData.mmsAttach.callback	필수	text(25)	사전 등록된 발신자 전화번호
msgData.mmsAttach.originCid	선택	text(9)	특부가 사업번호(특부가 사업자의 경우 필수)
msgData.elementSet	선택	object	치환문구 JSON 템플릿 내 존재하는 치환 변수 및 암호화가 필요한 값을 지정 ex) {"#{이름}": "홍길동", "#{수신번호}": "01012345678"}

Request JSON Sample

{
  "senderKey": "abc123def456abc123def456abc123def456abc1",
  "sendStatus": "0001",
  "msgData": [
    {
      "senderKey": "abc123def456abc123def456abc123def456abc1",
      "msgKey": "free_direct_001",
      "messageType": "FT",
      "recipient": "01012345678",
      "message": "안녕하세요 #{이름}님!\n봄맞이 20% 할인 혜택을 확인해보세요.",
      "useFailback": "Y",
      "attach": {
        "button": [
          {
            "name": "혜택 확인하기",
            "type": "WL",
            "url_mobile": "https://example.com/event",
            "url_pc": "https://example.com/event"
          }
        ]
      },
      "mmsAttach": {
        "mmsContent": "안녕하세요 #{이름}님!\n봄맞이 20% 할인 혜택을 확인해보세요.",
        "subject": "봄맞이 할인 혜택 안내",
        "callback": "0212345678"
      },
      "elementSet": {
        "#{이름}": "홍길동"
      }
    }
  ]
}

메시지 유형별 발송 예시는 3. 자유형 발송 유형별 샘플을 확인해주세요.

Response JSON

API 서버에서 전달 받은 파라미터 처리 후 결과를 JSON 형태로 제공합니다.

{
  "code": "200",
  "message": "메시지 등록이 완료 되었습니다.",
  "data": [
    {
      "result": {
        "code": "C200",
        "desc": "정상처리 됨",
        "msgKey": "free_direct_001"
      },
      "msgIdx": "12345678913"
    }
  ]
}

[표 2.2] 발송 JSON 결과

값	설명
code	결과 코드
message	결과 메시지
data	결과 데이터 List
data.result	수신 대상별 처리 결과 JSON
data.result.code	수신 대상별 처리 결과 코드
data.result.desc	수신 대상별 처리 결과 메시지
data.msgIdx	생성된 브랜드 메시지 메시지 IDX

[표 2.3] 발송 JSON 결과의 result code 유형

코드	내용	비고
200	정상처리 됨
401	접근 권한이 없습니다.	계정 서비스 권한 여부
403	필수 값이 없습니다.
4033	메시지에 대한 접근 권한이 없습니다.	브랜드 메시지 메시지 정보 없음
4035	유효한 호출이 아닙니다.	인증 토큰 누락
4036	유효한 호출이 아닙니다.	인증 토큰 만료
4037	유효한 호출이 아닙니다.	화이트리스트에 존재하지 않는 IP
500	서버 에러	결과 메시지 참고

[표 2.4] 발송 JSON 결과의 수신 대상별 처리 결과 코드

코드	내용	비고
C200	정상처리 됨
C3000	유효하지 않은 senderKey
C3001	senderKey 길이 제한 오류
C3002	유효하지 않은 tmpltCode
C3003	tmpltCode 길이 제한 오류
C3006	유효하지 않은 recipient
C3007	recipient 길이 제한 오류
C3008	등록된 callback과 일치하지 않음
C3009	유효하지 않은 callback
C3010	유효하지 않은 subject
C3011	유효하지 않은 mmsContnet
C3012	유효하지 않은 mmsAttach
C3014	유효하지 않은 msgKey
C3024	유효하지 않은 치환변수