2. 단일 건 발송

개요

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

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

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

API Server URL: https://bizmsgapi.fingerpush.com/rest/mms/v1/sendDirectMms

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

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	설명
sendStatus	선택	text(4)	0001: 바로 발송(default) 0002: 예약발송
sendDate	선택	text(20)	발송 시간 yyyy-MM-dd HH:mm:ss
msgData	필수	list	발송용 메시지 JSON Array
msgData.msgKey	필수	text	구분용 키
msgData.callback	필수	text(25)	사전 등록된 발신자 전화번호
msgData.recipient	필수	text(20)	수신자 번호
msgData.subject	필수	byte(40)	문자 메시지 제목
msgData.message	필수	byte(2000)	문자 메시지 내용
msgData.fileKeys	선택	list	첨부파일 fileKey [문자 > 이미지 관리 > 발급된 파일키]
msgData.orgCode	선택	text(20)	부서 코드 (핑거푸시 사이트에서 발급받은 부서 코드)
msgData.originCid	선택	text(9)	특부가 사업번호(특부가 사업자의 경우 필수)
msgData.elementSet	선택	object	치환문구 JSON 문자 제목, 본문 내 존재하는 치환 변수 및 암호화가 필요한 값을 지정

Request JSON Sample

SMS, LMS 발송

{
  "sendStatus": "0001",
  "msgData": [
    {
      "msgKey": "direct_mms_001",
      "callback": "0212345678",
      "recipient": "01012345678",
      "subject": "주문 완료 안내",
      "message": "#{이름}님, 주문이 완료되었습니다. #{주문번호}",
      "elementSet": {
        "#{이름}": "홍길동",
        "#{주문번호}": "ORD-20250401-001"
      }
    }
  ]
}

MMS 발송

{
  "sendStatus": "0001",
  "msgData": [
    {
      "msgKey": "direct_mms_002",
      "callback": "0212345678",
      "recipient": "01087654321",
      "subject": "봄맞이 이벤트 안내",
      "message": "안녕하세요 #{이름}님.\n봄맞이 특별 이벤트에 초대합니다.\n\n이벤트 기간: 2025-04-01 ~ 2025-04-30\n혜택: 최대 30% 할인",
      "fileKeys": ["FILE_KEY_001"],
      "elementSet": {
        "#{이름}": "홍길동"
      }
    }
  ]
}

Response JSON

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

성공

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

일부 실패 데이터 포함

{
  "code": "200",
  "message": "메시지 등록이 완료 되었습니다.",
  "data": [
    {
      "result": {
        "code": "C200",
        "desc": "정상처리 됨",
        "msgKey": "direct_mms_001"
      },
      "msgIdx": "12345678914"
    },
    {
      "result": {
        "code": "C3006",
        "desc": "유효하지 않은 recipient",
        "msgKey": "direct_mms_002"
      },
      "msgIdx": ""
    }
  ]
}

[표 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	정상처리 됨
C3007	recipient 길이 제한 오류
C3008	등록된 callback과 일치하지 않음
C3009	유효하지 않은 callback
C3010	유효하지 않은 subject
C3011	유효하지 않은 mmsContnet
C3012	유효하지 않은 mmsAttach
C3014	유효하지 않은 msgKey
C3015	유효하지 않은 fileKeys	fileKeys 파싱 실패
C3016	유효하지 않은 fileKeys	fileKeys 파일 없음
C3017	유효하지 않은 fileKeys	만료된 fileKeys
C3018	유효하지 않은 fileKeys	fileKeys 갱신 실패
C3024	유효하지 않은 치환변수