D42: 알림문서

이 문서는 카카오톡 전자문서의 D42 알림문서 상품 API 사용법을 안내합니다.

시작하기 전에

상품 소개

카카오톡 전자문서의 D42 알림문서는 별도의 원문 없이 일반 텍스트의 안내 문구만 발송하는 상품입니다. 이미지 또는 링크를 포함한 문서가 필요한 경우 간편문서 상품을 사용해야 합니다. 안내 문구에는 개인정보가 포함되지 않아야 하며, 누구에게나 동일한 내용을 전달하는 단순 안내문을 발송할 때 적합합니다.

문서 발송 요청이 성공하면 문서를 생성하고 문서를 수신하는 사용자에게 카카오톡 알림톡으로 문서 수신 알림을 발송합니다. 사용자는 알림톡 또는 카카오톡 전자문서 서비스에서 내용을 확인할 수 있습니다.

알림문서는 원문을 포함하지 않기 때문에 사용자의 본인확인이나 원문 열람 과정이 없고, 열람일시를 기록하지 않는 유통정보만 생성 및 등록이 가능합니다. 유통정보 등록 여부에 따라 세부 상품코드를 구분합니다. 상품 종류와 사용자 흐름을 함께 참고합니다.

문서 발송 및 열람 과정

아래는 D42 상품의 발송 및 상태 조회 과정을 표현한 시퀀스 다이어그램(Sequence Diagram)입니다.

카카오톡 전자문서 D42 시퀀스 다이어그램

이용기관은 문서 발송 API로 문서를 수신할 사용자 정보와 문서 정보를 전달하고 envelopeId(문서 고유 ID)를 발급받습니다.
카카오톡 전자문서 서버는 수신자 정보로 카카오톡 사용자를 식별한 뒤, 해당 사용자에게 문서를 생성하고 문서 수신 알림톡을 발송합니다.
이용기관은 문서 발송 요청 이후 언제든 문서 상태 조회 API를 호출할 수 있습니다.

문서 발송

단건 발송

기본 정보

메서드	URL	인증 방식
`POST`	`https://edoc-gw.kakao.com/v1/envelopes/${PRODUCT_CODE}`	REST API 키

권한	사전 설정	카카오 로그인	동의항목
필요	REST API 키	-	-

문서를 수신할 사용자의 정보와 문서의 정보를 카카오톡 전자문서 서버에 전달하고 문서 생성을 요청합니다.

이 API의 요청 결과로 이용기관은 문서 상태 조회 API 호출 시 필요한 envelopeId를 응답받습니다. 단건 발송으로는 1명의 사용자에게 1건의 문서를 발송할 수 있습니다.

헤더(Header)에 이용기관 앱과 딜러사 앱의 REST API 키, 정산 ID를 담아 POST로 요청합니다. 요청 URL의 ${PRODUCT_CODE} 부분에 상품 코드를 입력해야 합니다. 예를 들어, D42_1 상품 사용 시 요청 URL은 https://edoc-gw.kakao.com/v1/envelopes/D42_1입니다. 사용자 식별을 위한 수신인 정보와 안내 문구 등 문서 정보를 JSON 형식으로 포함해야 합니다.

요청 성공 시 응답은 문서의 envelopeId를 포함하며 사용자에게 문서 수신 알림톡을 발송합니다. 요청 실패 시 에러 코드에서 원인을 확인합니다.

이 API로는 초당 최대 100개의 문서를 발송할 수 있습니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DEALER_REST_API_KEY}` 인증 방식, 딜러사 앱의 REST API 키로 인증 요청	O
Target-Authorization	`Target-Authorization: KakaoAK ${PARTNER_REST_API_KEY}` 인증 방식, 이용기관 앱 REST API 키로 인증 요청	O
settle-id	`settle-id: ${SETTLE_ID}` 정산 ID	O

경로 변수

이름	타입	설명	필수
`${PRODUCT_CODE}`	`String`	상품 코드, 아래 중 하나 `D42_1` `D42_2`	O

본문

사용자 식별을 위한 수신인 정보는 아래 중 한 가지 조합으로 필수 전달해야 합니다.
- ci
- phoneNumber, name, birthday

이름	타입	설명	필수
title	`String`	문서 제목(최대 40자)	O
guide	`String`	문서 정보 안내 화면에 노출할 문구(최대: 500자)	O
payload	`String`	페이로드(Payload, 최대: 200자)	X
ci	`String`	사용자 식별을 위한 수신인 정보, CI(최대: 88자)	X
phoneNumber	`String`	사용자 식별을 위한 수신인 정보, 전화번호 `01012345678` 형식	X
name	`String`	사용자 식별을 위한 수신인 정보, 이름	X
birthday	`String`	사용자 식별을 위한 수신인 정보, 생년월일 `yyyyMMdd` 형식	X
externalId	`String`	문서 매핑(Mapping)용 식별자(최대: 40자)	X

응답

본문

이름	타입	설명	필수
envelopeId	`String`	문서 고유 ID, 34자로 고정	O
externalId	`String`	문서 매핑용 식별자	X

예제

요청

curl -v -X POST "https://edoc-gw.kakao.com/v1/envelopes/D42_1" \
  -H "Target-Authorization: KakaoAK ${PARTNER_REST_API_KEY}" \
  -H "Authorization: KakaoAK ${DEALER_REST_API_KEY}" \
  -H "settle-id: ${SETTLE_ID}" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -d '{
        "title": "기간 도래 안내",
        "guide": "신청이 곧 마감될 예정입니다",
        "payload": "이용기관 페이로드",
        "phoneNumber": "01099999999",
        "name": "홍길동",
        "birthday": "20000303",
        "externalId": "external_id1"
    }'

응답

// HTTP/1.1 200 OK
{
  "externalId": "external_id1",
  "envelopeId": "${ENVELOPE_ID}"
}

다건 발송

기본 정보

메서드	URL	인증 방식
`POST`	`https://edoc-gw.kakao.com/v1/bulk/envelopes/${PRODUCT_CODE}`	REST API 키

권한	사전 설정	카카오 로그인	동의항목
필요	REST API 키	-	-

문서를 수신할 사용자의 정보와 문서의 정보를 카카오톡 전자문서 서버에 전달하고 문서 생성을 요청합니다.

이 API의 요청 결과로 이용기관은 문서 상태 조회 API 호출 시 필요한 envelopeId를 응답받습니다. 다건 발송으로는 최대 100건의 문서를 발송할 수 있습니다.

헤더에 이용기관 앱과 딜러사 앱의 REST API 키, 정산 ID를 담아 POST로 요청합니다. 요청 URL의 ${PRODUCT_CODE} 부분에 상품 코드를 입력해야 합니다. 예를 들어, D42_1 상품 사용 시 요청 URL은 https://edoc-gw.kakao.com/v1/bulk/envelopes/D42_1입니다. 본문에는 사용자 식별을 위한 수신인 정보와 안내 문구 등 각 문서 정보를 JSON 배열 형식으로 포함해야 합니다.

요청 성공 시 응답은 각 문서의 envelopeId를 포함하며 사용자에게 문서 수신 알림톡을 발송합니다. 요청 실패 시 에러 코드에서 원인을 확인합니다.

이 API로는 초당 최대 200개의 문서를 발송할 수 있습니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DEALER_REST_API_KEY}` 인증 방식, 딜러사 앱의 REST API 키로 인증 요청	O
Target-Authorization	`Target-Authorization: KakaoAK ${PARTNER_REST_API_KEY}` 인증 방식, 이용기관 앱 REST API 키로 인증 요청	O
settle-id	`settle-id: ${SETTLE_ID}` 정산 ID	O

경로 변수

이름	타입	설명	필수
`${PRODUCT_CODE}`	`String`	상품 코드, 아래 중 하나 `D42_1` `D42_2`	O

본문

이름	타입	설명	필수
envelopes	`Envelope[]`	각 전자문서 정보를 담은 배열(최대: 100건)	O

Envelope

사용자 식별을 위한 수신인 정보는 아래 중 한 가지 조합으로 필수 전달해야 합니다.
- ci
- phoneNumber, name, birthday

이름	타입	설명	필수
title	`String`	문서 제목(최대 40자)	O
guide	`String`	문서 정보 안내 화면에 노출할 문구(최대: 500자)	O
payload	`String`	페이로드(Payload, 최대: 200자)	X
ci	`String`	사용자 식별을 위한 수신인 정보, CI(최대: 88자)	X
phoneNumber	`String`	사용자 식별을 위한 수신인 정보, 전화번호 `01012345678` 형식	X
name	`String`	사용자 식별을 위한 수신인 정보, 이름	X
birthday	`String`	사용자 식별을 위한 수신인 정보, 생년월일 `yyyyMMdd` 형식	X
externalId	`String`	문서 매핑(Mapping)용 식별자(최대: 40자) 동일 요청에 포함된 각 문서의 `externalId` 값은 유일(Unique)해야 함	O

응답

본문

이름	타입	설명	필수
envelopes	`Result[]`	발송 요청된 문서 목록	X

Result

이름	타입	설명	필수
envelopeId	`String`	문서 고유 ID, 34자로 고정	X
externalId	`String`	문서 매핑용 식별자	X

예제

요청

curl -v -X POST "https://edoc-gw.kakao.com/v1/bulk/envelopes/D42_1" \
  -H "Target-Authorization: KakaoAK ${PARTNER_REST_API_KEY}" \
  -H "Authorization: KakaoAK ${DEALER_REST_API_KEY}" \
  -H "settle-id: ${SETTLE_ID}" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -d '{
        "envelopes": [
            {
                "title": "기간 도래 안내",
                "guide": "신청이 곧 마감될 예정입니다",
                "payload": "이용기관 페이로드",
                "phoneNumber": "01099999999",
                "name": "홍길동",
                "birthday": "20000303",
                "externalId": "external_id1"
            },
            {
                "title": "기간 도래 안내",
                "guide": "신청이 곧 마감될 예정입니다",
                "payload": "이용기관 페이로드",
                "phoneNumber": "01088888888",
                "name": "김철수",
                "birthday": "20010303",
                "externalId": "external_id2"
            }
        ]
    }'

응답

// HTTP/1.1 200 OK
{
  "envelopes": [
    {
      "envelopeId": "${ENVELOPE_ID}",
      "externalId": "external_id1"
    },
    {
      "envelopeId": "${ENVELOPE_ID}",
      "externalId": "external_id2"
    }
  ]
}

문서 상태 조회

기본 정보

메서드	URL	인증 방식
`POST`	`https://edoc-gw.kakao.com/v1/envelopes/status`	REST API 키

권한	사전 설정	카카오 로그인	동의항목
필요	REST API 키	-	-

카카오톡 전자문서로 발송한 문서의 상태를 조회합니다.

한 번에 최대 100건의 문서 상태를 조회할 수 있습니다.

헤더(Header)에 이용기관 앱과 딜러사 앱의 REST API 키, 정산 ID를 담아 POST로 요청합니다. envelopeIds에 상태를 조회할 문서 고유 ID 목록을 전달해야 합니다.

요청 성공 시 응답은 각 문서 상태 정보를 포함합니다. 요청 실패 시 에러 코드에서 원인을 확인합니다.

이 API로는 초당 최대 400개의 문서를 조회할 수 있습니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DEALER_REST_API_KEY}` 인증 방식, 딜러사 앱의 REST API 키로 인증 요청	O
Target-Authorization	`Target-Authorization: KakaoAK ${PARTNER_REST_API_KEY}` 인증 방식, 이용기관 앱 REST API 키로 인증 요청	O
settle-id	`settle-id: ${SETTLE_ID}` 정산 ID	O

본문

이름	타입	설명	필수
envelopeIds	`String[]`	문서 고유 ID 목록	O

응답

본문

이름	타입	설명	필수
envelopeStatus	`EnvelopeStatus[]`	각 문서 상태 정보	O

EnvelopeStatus

이름	타입	설명	필수
envelopeId	`String`	문서 고유 ID	O
externalId	`String`	문서 매핑용 식별자 문서 발송 API 요청 시 지정한 경우에만 응답에 포함	X
status	`String`	문서 상태 `RECEIVED`: 수신	X
sentAt	`String`	문서 송신 일시	X
receivedAt	`String`	문서 수신 일시	X
distributionReceivedAt	`String`	유통정보의 수신 시각, 공인전자주소 활성화와 문서 수신이 모두 완료된 시각	X
isNotificationUnavailable	`Boolean`	사용자의 알림톡 수신 가능 여부	X
userNotifiedAt	`String`	사용자의 알림톡 수신 일시	X
payload	`String`	문서 발송 API 요청 시 전달한 페이로드	X

예제

요청

curl -v -X POST "https://edoc-gw.kakao.com/v1/envelopes/status" \
  -H "Target-Authorization: KakaoAK ${PARTNER_REST_API_KEY}" \
  -H "Authorization: KakaoAK ${DEALER_REST_API_KEY}" \
  -H "settle-id: ${SETTLE_ID}" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -d '{
        "envelopeIds" : [
            "${ENVELOPE_ID}",
            "${ENVELOPE_ID}"
        ]
    }'

응답

// HTTP/1.1 200 OK
{
  "envelopeStatus": [
    {
      "envelopeId": "${ENVELOPE_ID}",
      "externalId": "external_id01",
      "status": "READ",
      "sentAt": "2023-09-25T17:45:14",
      "receivedAt": "2023-09-25T17:45:14",
      "distributionReceivedAt": "2023-09-25T17:45:14",
      "isNotificationUnavailable": false,
      "userNotifiedAt": "2023-09-25T17:45:14",
      "payload": "이용기관 페이로드"
    },
    {
      "envelopeId": "${ENVELOPE_ID}",
      "errorCode": "D404_00",
      "errorMessage": "요청 정보를 찾을 수 없습니다. 문서[${ENVELOPE_ID}]를 찾을 수 없습니다."
    }
  ]
}

유통증명서 발급

기본 정보

메서드	URL	인증 방식
`GET`	`https://edoc-gw.kakao.com/v1/envelopes/${ENVELOPE_ID}/distributions/cert`	REST API 키

권한	사전 설정	카카오 로그인	동의항목
필요	REST API 키	-	-

전담기관 시스템에 등록된 유통정보를 증명하는 유통증명서를 발급합니다.

문서 발송이 정상적으로 완료되었더라도 전담기관 시스템에 유통 정보가 적재되기 전까지는 유통증명서를 발급할 수 없습니다. 유통 정보는 수신자가 공인전자주소를 등록한 경우, 약 1시간 이내에 적재됩니다. 수신자가 공인전자주소를 등록하지 않은 경우, 공인전자주소를 등록하기 전까지 적재되지 않습니다.

헤더(Header)에 이용기관 앱과 딜러사 앱의 REST API 키, 정산 ID를 담아 GET으로 요청합니다. 요청 URL의 ${ENVELOPE_ID} 부분에 유통증명서를 발급할 대상 문서의 고유 ID를 입력하고, 유통증명서 발급 목적을 reason 담아 쿼리 파라미터로 포함해야 합니다.

요청 성공 시 응답은 PDF 포멧의 유통증명서 파일입니다. 요청 실패 시 에러 코드에서 원인을 확인합니다.

권장 사항

유통증명서 발급 목적(reason)은 발급 후 추적 관리를 용이하게 할 수 있도록 명확하게 작성할 것을 권장합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DEALER_REST_API_KEY}` 인증 방식, 딜러사 앱의 REST API 키로 인증 요청	O
Target-Authorization	`Target-Authorization: KakaoAK ${PARTNER_REST_API_KEY}` 인증 방식, 이용기관 앱 REST API 키로 인증 요청	O
settle-id	`settle-id: ${SETTLE_ID}` 정산 ID	O

경로 변수

이름	타입	설명	필수
`${ENVELOPE_ID}`	`String`	문서 고유 ID	O

쿼리 파라미터

이름	타입	설명	필수
reason	`String`	유통증명서 발급 목적(최대: 200자)	O

응답

PDF 포멧의 유통증명서 파일

예제

요청

curl -v -G GET "https://edoc-gw.kakao.com/v1/envelopes/${ENVELOPE_ID}/distributions/cert?reason=${REASON}" \
  -H "Target-Authorization: KakaoAK ${PARTNER_REST_API_KEY}" \
  -H "Authorization: KakaoAK 52de30f310daaa2830105609a6efec97" \
  -H "settle-id: ${SETTLE_ID}" \
  -H "Content-Type: application/json" \
  -o cert.pdf

유통 통계 수치 확인서 발급

기본 정보

메서드	URL	인증 방식
`GET`	`https://edoc-gw.kakao.com/v1/distributions/stats/confirmation`	REST API 키

권한	사전 설정	카카오 로그인	동의항목
필요	REST API 키	-	-

전담기관 시스템에 등록된 유통 정보 수치를 증명하는 유통 통계 수치 확인서를 발급합니다.

전담기관은 유통 통계를 아래 두 가지 기준으로 제공합니다.

조회 기간 내 발송한 문서 중 수신 및 열람 발생 건 수
발송 시점과 상관없이 조회 기간에 수신 및 열람 발생 건 수

전담기관이 제공하는 통계 정보는 실시간으로 반영되지 않습니다. 카카오톡 전자문서 서버가 전담기관 서버에 유통정보를 적재한 익일부터 반영됩니다.

헤더(Header)에 이용기관 앱과 딜러사 앱의 REST API 키, 정산 ID를 담아 GET으로 요청합니다. 요청 시 조회 기간을 period 쿼리 파라미터로 포함해야 합니다. 요청 성공 시 응답은 PDF 포맷의 유통 통계 수치 확인서 파일입니다. 요청 실패 시 에러 코드에서 원인을 확인합니다.

유통 통계 수치 반영

유통 통계 수치는 전담기관 시스템에 적재된 다음날에 반영됩니다. 만약 월말 23:59:59에 사용자가 문서를 열람하고 익월 00:00:01에 KISA에 적재 처리된 경우, 익월 2일에 통계 수치에 반영됩니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DEALER_REST_API_KEY}` 인증 방식, 딜러사 앱의 REST API 키로 인증 요청	O
Target-Authorization	`Target-Authorization: KakaoAK ${PARTNER_REST_API_KEY}` 인증 방식, 이용기관 앱 REST API 키로 인증 요청	O
settle-id	`settle-id: ${SETTLE_ID}` 정산 ID	O

쿼리 파라미터

이름	타입	설명	필수
period	`String`	유통 통계를 조회할 대상 월, `yyyy-MM` 형식	O

응답

PDF 포멧의 유통 통계 수치 확인서 파일

예제

요청

curl -v -X GET "https://edoc-gw.kakao.com/v1/distributions/stats/confirmation?period=${PERIOD}" \
    -H "Target-Authorization: KakaoAK ${PARTNER_REST_API_KEY}" \
    -H "Authorization: KakaoAK ${DEALER_REST_API_KEY}" \
    -H "settle-id: ${SETTLE_ID}" \
    -H "Content-Type: application/json" \
    -o cert.pdf

사이드 메뉴

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

카카오맵

내비게이션

광고

검색

더 보기

D42: 알림문서

시작하기 전에

상품 소개

문서 발송 및 열람 과정

문서 발송

단건 발송

기본 정보

요청

헤더

경로 변수

본문

응답

본문

예제

요청

응답

다건 발송

기본 정보

요청

헤더

경로 변수

본문

Envelope

응답

본문

Result

예제

요청

응답

문서 상태 조회

기본 정보

요청

헤더

본문

응답

본문

EnvelopeStatus

예제

요청

응답

유통증명서 발급

기본 정보

요청

헤더

경로 변수

쿼리 파라미터

응답

예제

요청

유통 통계 수치 확인서 발급

기본 정보

요청

헤더

쿼리 파라미터

응답

예제

요청

더 보기

도움이 되었나요?

D42: 알림문서