이 문서는 카카오톡 전자문서의 D10, D11 전자우편 상품 API 사용법을 안내합니다.

카카오톡 전자문서의 D10 또는 D11, 전자우편 상품은 카카오 인증서로 사용자의 본인 확인을 거친 이후 문서를 열람할 수 있도록 하는 상품입니다. 문서 발송 요청이 성공하면 문서를 수신하는 사용자에게 카카오톡 알림톡으로 문서 수신 알림을 발송하고, 사용자의 본인 확인 이후 전자문서 원문이 무엇인지에 따라 이용기관 웹으로 연결(D10)하거나 HTML 원문 내용을 열람(D11)하도록 합니다.

D10과 D11은 유통정보 생성 및 등록을 지원하며, 그에 따라 세부적인 상품 코드를 구분합니다. 상품 종류와 사용자 흐름을 함께 참고합니다.

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

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

1. 이용기관은 문서 발송 API로 문서를 수신할 사용자 정보와 문서 정보를 전달하고 envelopeId(문서 고유 ID)를 발급받습니다.
2. 카카오톡 전자문서 서버는 수신자 정보로 카카오톡 사용자를 식별한 뒤, 해당 사용자에게 문서를 생성하고 문서 수신 알림톡을 발송합니다.
3. 사용자가 문서를 열람할 때 카카오 인증서로 본인 확인 과정을 수행합니다.
4. 사용자가 인증에 성공하여 이용기관의 웹링크로 진입할 때, 이용기관은 일회용 토큰(One Time Token, token)과 envelopeId로 토큰 검증 API를 호출합니다.
   • 사용자가 실제 문서 페이지에 접속할 때 토큰 검증 없이 바로 접속을 허용하지 않도록 합니다.
   • 토큰 검증 결과가 정상인 경우만 사용자에게 접속을 허용해야 합니다.
   • token과 envelopeId는 웹링크에 포함돼 있습니다.
5. 토큰 검증이 완료되면 문서 열람 처리 API를 호출합니다.
   • 이용기관의 페이지가 사용자에게 전부 노출된 시점에 해당 API를 호출해야 합니다.
   • 문서 열람 처리 API의 요청 성공 시각이 유통증명서의 열람시간으로 등록됩니다.
   • 문서 열람 처리 API를 호출하지 않는 경우, 문서는 열람한 것으로 처리되지 않으며 유통정보의 열람시간 또한 등록되지 않습니다.
6. 이용기관은 문서 발송 요청 이후 언제든 문서 상태 조회 API를 호출할 수 있습니다.

아래는 D11 상품의 발송 및 열람 과정을 표현한 시퀀스 다이어그램입니다.

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

1. 이용기관은 문서 발송 API로 문서를 수신할 사용자 정보와 문서 정보를 전달하고 envelopeId(문서 고유 ID)를 발급받습니다.
2. 카카오톡 전자문서 서버는 수신자 정보로 카카오톡 사용자를 식별한 뒤, 해당 사용자에게 문서를 생성하고 문서 수신 알림톡을 발송합니다.
3. 사용자가 문서를 열람할 때 카카오 인증서로 본인 확인 과정을 수행합니다.
4. 사용자가 인증에 성공하면, 카카오톡 전자문서 서버가 유효성 검증 후 전자문서의 원문 HTML 내용을 카카오톡 앱에서 출력합니다.
5. 사용자가 전자문서 원문을 정상적으로 조회하면 문서가 열람 처리되고, 문서 열람시간이 등록됩니다.
   • 문서 열람시간은 유통증명서상 열람시간에 해당합니다.
6. 이용기관은 문서 발송 요청 이후 언제든 문서 상태 조회 API를 호출할 수 있습니다.

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

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

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

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

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

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

curl -v -X POST "https://edoc-gw.kakao.com/v1/envelopes/D10_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": "전자문서",
        "content": {
            "link": "https://nps.or.kr"
        },
        "guide": "국민연금 공단에서 보내는 문서입니다.",
        "payload": "이용기관 페이로드",
        "readExpiresAt": "2023-12-31T10:00:00",
        "reviewExpiresAt": "2023-12-31T13:00:00",
        "useNonPersonalizedNotification": true,
        "phoneNumber": "01099999999",
        "name": "홍길동",
        "birthday": "20000303",
        "externalId": "external_id1"
    }'

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

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

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

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

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

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

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

curl -v -X POST "https://edoc-gw.kakao.com/v1/bulk/envelopes/D10_2" \
  -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": "전자문서",
                "content": {
                    "link": "https://nps.or.kr"
                },
                "hash": "${HASH}",
                "guide": "국민연금 공단에서 보내는 문서입니다.",
                "payload": "이용기관 페이로드",
                "readExpiresAt": "2024-12-31T10:00:00",
                "reviewExpiresAt": "2025-03-31T13:00:00",
                "phoneNumber": "01099999999",
                "name": "홍길동",
                "birthday": "20000303",
                "externalId": "external_id1"
            },
            {
                "title": "전자문서",
                "content": {
                    "link": "https://nps.or.kr"
                },
                "hash": "${HASH}",
                "guide": "국민연금 공단에서 보내는 문서입니다.",
                "payload": "이용기관 페이로드",
                "readExpiresAt": "2024-12-31T10:00:00"
                "reviewExpiresAt": "2025-03-31T13:00:00",
                "ci": "${CI}",
                "externalId": "external_id2"
            }
        ]
    }'

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

사용자가 이용기관 웹링크로 문서 열람을 요청할 때, 일회용 토큰(One Time Token, token)과 문서 고유 ID(envelopeId)로 유효한 요청인지 검증합니다.

토큰 검증에 성공한 경우에만 사용자에게 문서를 제공해야 합니다.

카카오톡 전자문서 서버는 이 API 요청에 필요한 token, envelopeId 값을 웹링크의 쿼리스트링(Query String)으로 전달합니다. 쿼리스트링을 제외한 웹링크의 URL은 문서 발송 요청 시 전달한 content 값입니다. 아래는 웹링크 예시입니다.

https://kakao.com?token=${TOKEN}&envelopeId=${ENVELOPE_ID}

사용자가 여러 차례 문서 열람을 요청할 수 있으므로, token 값은 문서 열람 요청마다 새로 발급됩니다. 토큰 발급 시점부터 10분 내로 토큰 검증을 요청해야 합니다. 동일한 토큰에 대해 2회 이상 검증을 요청할 경우 에러가 발생합니다.

헤더(Header)에 이용기관 앱과 딜러사 앱의 REST API 키, 정산 ID를 담아 GET으로 요청합니다. 요청 URL의 ${ENVELOPE_ID} 부분에 문서 고유 ID, ${TOKEN} 부분에 일회용 토큰 값을 입력해야 합니다.

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

curl -v -G GET "https://edoc-gw.kakao.com/v1/envelopes/${ENVELOPE_ID}/tokens/${TOKEN}/verify" \
  -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"

// HTTP/1.1 200 OK
{
  "envelopeId": "${ENVELOPE_ID}",
  "externalId": "external_id01",
  "status": "READ",
  "sentAt": "2023-09-25T17:45:14",
  "receivedAt": "2023-09-25T17:45:14",
  "readAt": "2023-09-25T17:45:14",
  "authenticatedAt": "2023-09-25T17:45:14",
  "ottVerifiedAt": "2023-09-25T17:45:14",
  "userNotifiedAt": "2023-09-25T17:45:14",
  "payload": "이용기관 페이로드"
}

사용자가 이용기관 웹링크로 문서를 열람했을 때, 문서를 열람 상태로 변경합니다.

토큰 검증 API 요청 결과 유효한 문서 열람 요청인 경우, 이용기관은 사용자에게 문서를 제공한 후 이 API를 호출해야 합니다. 토큰 검증 시점부터 30분 내로 문서 열람 처리를 요청해야 합니다.

문서를 열람 상태로 변경하지 않으면, 사용자가 문서를 열람했더라도 문서 상태는 읽지 않음으로 유지됩니다. 이 경우, 문서 상태 조회 API 호출 시 열람시간 데이터를 응답받을 수 없고, 유통정보의 열람시간 또한 등록되지 않으므로 이후 유통증명서를 발급하더라도 열람시간이 기재되어 있지 않습니다.

헤더(Header)에 이용기관 앱과 딜러사 앱의 REST API 키, 정산 ID를 담아 POST로 요청합니다. 요청 URL의 ${ENVELOPE_ID} 부분에 문서 고유 ID를 입력해야 합니다.

요청 성공 시 응답의 HTTP 상태 코드는 204 No Content이고 본문은 비어 있습니다. 요청 실패 시 에러 코드에서 원인을 확인합니다.

curl -v -X POST "https://edoc-gw.kakao.com/v1/envelopes/${ENVELOPE_ID}/read" \
  -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"

HTTP/1.1 204 No Content

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

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

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

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

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

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",
      "readAt": "2023-09-25T17:45:14",
      "readExpiredAt": "2023-12-25T17:45:14",
      "authenticatedAt": "2023-09-25T17:45:14",
      "ottVerifiedAt": "2023-09-25T17:45:14",
      "userNotifiedAt": "2023-09-25T17:45:14",
      "distributionReceivedAt": "2023-09-25T17:45:14",
      "payload": "이용기관 페이로드"
    },
    {
      "envelopeId": "${ENVELOPE_ID}",
      "errorCode": "D400_00",
      "errorMessage": "문서[${ENVELOPE_ID}]를 찾을 수 없습니다"
    }
  ]
}

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

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

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

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

• 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

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

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

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

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

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

• 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

• 이해하기
• D20: 간편문서
• D31: 전자서명문서
• D42: 알림문서
• 에러 코드
• 디자인 가이드