메시지 리포트

메시지 리포트 연동은 가져오기(Polling) 또는 수신받기(Webhook) 중 하나를 기본 방식으로 사용합니다.
기본 방식으로 일부 누락이 발생한 경우 개별조회(Inquiry)로 보완 조회합니다.

연동 방식

아래 버튼으로 각 연동 방식 섹션으로 이동할 수 있습니다.

가져오기(Polling)

가져오기(GET)

GET/api/comm/v1/report/polling

샌드박스로 테스트하기

처리 완료된 리포트를 Pull 방식으로 조회합니다. 반환된 reportId는 수신 확인(DELETE)에 사용합니다.

Query Parameters

(none)

요청 파라미터는 없습니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

상세 결과 데이터입니다.

reportId

String

수신 확인(DELETE)에 사용하는 리포트 ID입니다. 전달할 리포트가 없으면 빈 문자열입니다.

report

Object Array

메시지 리포트 목록입니다. 전달할 리포트가 없으면 null입니다.

serviceType

String

서비스 타입입니다.

msgType

String

메시지 타입입니다.

reportType

String

리포트 종류입니다.

carrier

String

(문자메시지) 이통사 코드입니다.

userType

String

(카카오 브랜드메시지) 메시지 발송 처리 타입입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/report/polling" \
  -H "Authorization: {ApiKey}" \
  -H "Accept: application/json"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"header-value-X-Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "reportId":"REPORT-20260331-0001",
      "report": [
        {
          "msgKey":"SMS20260331-000001",
          "serviceType":"SMS",
          "msgType":"SM",
          "sendTime":"2026-03-31T09:30:00+09:00",
          "reportTime":"2026-03-31T09:30:11+09:00",
          "reportType":"0",
          "reportCode":"10000",
          "reportText":"Success",
          "carrier":"10001",
          "userType":"",
          "resCnt":"",
          "ref":"요청 시 입력한 데이터"
        }
      ]
    }
  }
}

수신 확인(DELETE)

DELETE/api/comm/v1/report/polling/{reportId}

샌드박스로 테스트하기

가져오기(GET) 응답의 reportId를 전달해 수신 확인 처리합니다.

Path Parameters

reportId

필수String

가져오기(GET) 응답에서 받은 리포트 아이디입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

요청 예시

curl -X DELETE "https://mars.ibapi.kr/api/comm/v1/report/polling/REPORT-20260331-0001" \
  -H "Authorization: {ApiKey}" \
  -H "Accept: application/json"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"header-value-X-Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success"
  }
}

수신받기(Webhook)

POST{등록한 Webhook URL}

사전에 등록한 Webhook URL로 리포트를 Push 방식으로 전달받습니다. 리포트 1건당 1회 요청되며, 수신 후 규격에 맞는 응답을 반환해야 합니다. 응답이 없거나 규격이 맞지 않으면 실패로 간주합니다. 타임아웃은 5초이며, 최대 3회까지 재시도합니다. Webhook URL 등록 및 방화벽 설정이 필요합니다. 방화벽 및 보안 프로토콜

Header

X-IB-Timestamp

필수String

Webhook 전송 시점의 타임스탬프입니다.

X-IB-Signature

필수String

보안 서명입니다. HmacSHA256(secret, X-IB-Timestamp)로 생성됩니다. secret은 고객계정 별 별도 관리됩니다. 검증을 위해 값 확인이 필요한 경우 영업담당자에 요청해주세요.

필수String

application/json

Content-Type

필수String

application/json

Body Parameters

{}JSON

msgKey

필수String

메시지 키입니다.

serviceType

필수String

서비스 타입입니다.

msgType

String

메시지 타입입니다.

sendTime

String

전송 처리 일시입니다. (ISO 8601, yyyy-MM-dd'T'HH:mm:ss.SSS)

reportTime

필수String

리포트 수신 일시입니다. (ISO 8601, yyyy-MM-dd'T'HH:mm:ss.SSS)

reportType

필수String

리포트 종류입니다.

reportCode

필수String

리포트 코드입니다.

reportText

String

리포트 상세 내용입니다.

carrier

String

(문자메시지) 이통사 코드입니다.

userType

String

(카카오 브랜드메시지) 메시지 발송 처리 타입입니다.

resCnt

String

(국제메시지) 메시지 분할 수입니다.

ref

String

요청 시 입력한 참조 필드입니다.

Returns

msgKey

필수String

수신한 메시지 키를 그대로 반환해야 합니다. 응답을 보내지 않거나 규격이 맞지 않으면 수신 실패로 간주되어 재전송이 발생합니다.

요청 예시

curl -X POST "{등록한 Webhook URL}" \
  -H "Content-Type: application/json" \
  -H "X-IB-Timestamp: 1743381600000" \
  -H "X-IB-Signature: {HmacSHA256(secret, X-IB-Timestamp)}" \
  -d '{
  "msgKey": "SMS20260331-000001",
  "serviceType": "SMS",
  "msgType": "SM",
  "sendTime": "2026-03-31T09:30:00.000+09:00",
  "reportTime": "2026-03-31T09:30:11.000+09:00",
  "reportType": "0",
  "reportCode": "10000",
  "reportText": "Success",
  "carrier": "10001",
  "userType": "",
  "resCnt": "",
  "ref": "요청 시 입력한 데이터"
}'

응답 예시

{
  "msgKey":"SMS20260331-000001"
}

개별조회(Inquiry)

GET/api/comm/v1/report/inquiry/{msgKey}

샌드박스로 테스트하기

특정 메시지 키(msgKey)의 리포트를 단건 조회합니다. 최대 30일 이전의 리포트를 조회할 수 있습니다.

Path Parameters

msgKey

필수String

조회할 메시지 키입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

상세 결과 데이터입니다.

report

Object Array

메시지 리포트 목록입니다.

serviceType

String

서비스 타입입니다.

msgType

String

메시지 타입입니다.

reportType

String

리포트 종류입니다.

carrier

String

(문자메시지) 이통사 코드입니다.

userType

String

(카카오 브랜드메시지) 메시지 발송 처리 타입입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/report/inquiry/SMS20260331-000001" \
  -H "Authorization: {ApiKey}" \
  -H "Accept: application/json"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"header-value-X-Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "report": [
        {
          "msgKey":"SMS20260331-000001",
          "serviceType":"SMS",
          "msgType":"SM",
          "sendTime":"2026-03-31T09:30:00+09:00",
          "reportTime":"2026-03-31T09:30:11+09:00",
          "reportType":"0",
          "reportCode":"10000",
          "reportText":"Success",
          "carrier":"10001",
          "userType":"",
          "resCnt":"",
          "ref":"요청 시 입력한 데이터"
        }
      ]
    }
  }
}