T14: 모바일티켓

이 문서는 카카오톡 전자문서의 T14 모바일티켓 상품 API 사용법을 안내합니다.

시작하기 전에

상품 소개

카카오톡 전자문서의 T14 모바일티켓 상품은 카카오 인증서로 사용자의 본인 확인을 거친 이후 티켓을 열람할 수 있도록 하는 상품입니다. 티켓 발송 요청이 성공하면 티켓을 수신하는 사용자에게 카카오톡 알림톡으로 티켓 수신 알림을 발송하고, 사용자의 본인 확인 이후 이용기관 앱으로 연결합니다.

현재는 이용기관 앱으로 연결하는 형태의 상품(T14)만 제공합니다. 향후 이용기관 웹으로 연결하거나 HTML 원문으로 제공하는 등 티켓의 원문 형태에 따라 세부 상품 코드가 구분될 수 있습니다.

모바일티켓 상품 정책

모바일티켓 상품은 전반적으로 다른 전자문서 상품과 동일한 정책을 적용받지만, 일부 정책이 다를 수 있습니다. 카카오톡 전자문서에서 제공하는 다른 상품 및 전반적인 흐름에 대한 이해는 상품 종류와 사용자 흐름을 참고합니다.

사용자에게 표시되는 문서 목록 UI에서 모바일티켓 상품으로 발송된 전자문서는 다른 형태로 구분되어 표시될 수 있습니다.
발송 요청이 성공했을 때 수신자에게 카카오톡 알림톡으로 발송하는 알림 메시지의 구성이 일부 다를 수 있습니다.
모바일티켓 상품으로 발송된 전자문서는 리마인드 알림 발송 대상에서 제외됩니다.
모바일티켓 상품은 유통정보의 생성 및 등록을 지원하지 않습니다.

문서 발송 및 열람 과정

T14: 앱링크 타입

앱링크 타입의 모바일티켓 전자문서 상품은 T14_1 상품코드로 한 종류의 상품을 사용할 수 있습니다.

상품코드	원문 형태	열람 시 본인 확인	원문 전자서명	유통정보 등록
`T14_1`	앱링크	카카오 인증서로 인증 후 열람	없음	유통정보 미등록

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

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

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

알림

문서 수신 알림톡 구성 요소

T14 모바일티켓 전자문서 발송 요청 성공 시 카카오톡 알림톡으로 수신자에게 발송하는 알림 메시지의 구성 요소를 안내합니다. 아래 이미지와 항목별 설명을 참고합니다.

모바일티켓 문서 수신 알림톡 구성 요소

구성 요소	설명	표시 상품
[A] 알림톡 도착 헤더	카카오톡 전자문서 전용 알림톡 도착 헤더	모든 상품
[B] 알림톡 썸네일 이미지	카카오톡 전자문서 티켓 상품 전용 썸네일 이미지	`T14`
[C] 문서 제목	발송한 문서 제목(`title`), 최대 30자까지만 표시하며 글자 수 초과 시 27자와 `...` 문구로 표시	모든 상품
[D] 열람기한	지정한 열람 만료 일시(`readExpiresAt`)	`D10`, `D20`, `D31`, `T14`
[E] 안내문구	문서 정보 안내 화면에 노출할 문구(`guide`)	모든 상품
[F] 고객센터	등록한 고객센터 번호 또는 카카오톡 채널 URL	모든 상품
[G] 카카오 지정 안내문구	카카오에서 지정한 문구로 고정	`T14`
[H] 열람 버튼	전자문서 열람 버튼 이용기관 앱링크 티켓 페이지로 연결	`T14`

썸네일 이미지와 리마인드 알림

모바일티켓 상품에 대한 문서 수신 알림톡의 썸네일 이미지는 카카오톡 전자문서가 제공합니다. 또한, 모바일티켓 상품으로 발송한 티켓 문서는 발송일 기준 리마인드 알림과 만료일 기준 리마인드 알림의 대상에서 제외됩니다.

문서 발송

단건 발송

기본 정보

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

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

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

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

헤더(Header)에 이용기관 앱과 딜러사 앱의 REST API 키, 정산 ID를 담아 POST로 요청합니다. 요청 URL의 ${PRODUCT_CODE} 부분에 상품 코드를 입력해야 합니다. 예를 들어, T14_1 상품 사용 시 요청 URL은 https://edoc-gw.kakao.com/v1/envelopes/T14_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`	상품 코드, `T14_1`	O

본문

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

이름	타입	설명	필수
title	`String`	티켓 문서 제목(최대 40자) 중요: 사용자가 식별할 수 있는 공연, 경기 등 이벤트 이름	O
content	`Content`	티켓 페이지로 접근할 수 있는 앱링크	O
guide	`String`	문서 정보 안내 화면에 노출할 문구(최대: 500자) 중요: 공연, 경기 등 이벤트의 일시와 장소 등을 포함	O
payload	`String`	페이로드(Payload, 최대: 200자)	X
readExpiresAt	`String`	티켓의 만료 일시 지정(최대: 요청 일시로부터 14일 이내) `yyyy-MM-dd'T'HH:mm:ss` 형식 중요: 티켓의 사용이 만료되어야 하는 시점으로 설정	O
ci	`String`	사용자 식별을 위한 수신인 정보, CI(최대: 88자)	X
phoneNumber	`String`	사용자 식별을 위한 수신인 정보, 전화번호 `01012345678` 형식	X
name	`String`	사용자 식별을 위한 수신인 정보, 이름	X
birthday	`String`	사용자 식별을 위한 수신인 정보, 생년월일 `yyyyMMdd` 형식	X
externalId	`String`	문서 매핑(Mapping)용 식별자(최대: 40자) 중요: 발송기관 내부에서 활용하는 예매 번호 관리 등에 사용	X

Content

이름	타입	설명	필수
appLink	`String`	이용기관의 티켓 페이지 앱링크 URL, `T14` 상품 사용 시 필수 영문과 키보드에서 입력 가능한 특수문자만 지원(최대: 1,000자)	O

응답

본문

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

예제

요청

curl -v -X POST "https://edoc-gw.kakao.com/v1/envelopes/T14_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": "2026-01-01 라이언 콘서트 티켓",
        "content": {
            "appLink": "myapp://my/ticket"
        },
        "guide": "라이언 콘서트 입장 티켓을 보내드려요.\n\n입장일시: 2026-01-01\n장소: 라이언스타디움",
        "payload": "이용기관 페이로드",
        "readExpiresAt": "2026-01-01T22:00:00",
        "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, 문서 열람 처리 API, 문서 상태 조회 API 호출 시 필요한 envelopeId를 응답받습니다. 다건 발송으로는 최대 100건의 문서를 발송할 수 있습니다.

헤더(Header)에 이용기관 앱과 딜러사 앱의 REST API 키, 정산 ID를 담아 POST로 요청합니다. 요청 URL의 ${PRODUCT_CODE} 부분에 상품 코드를 입력해야 합니다. 예를 들어, T14_1 상품 사용 시 요청 URL은 https://edoc-gw.kakao.com/v1/bulk/envelopes/T14_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`	상품 코드, `T14_1`	O

본문

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

Envelope

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

이름	타입	설명	필수
title	`String`	티켓 문서 제목(최대 40자) 중요: 사용자가 식별할 수 있는 공연, 경기 등 이벤트 이름	O
content	`Content`	티켓 페이지로 접근할 수 있는 앱링크	O
guide	`String`	문서 정보 안내 화면에 노출할 문구(최대: 500자) 중요: 공연, 경기 등 이벤트의 일시와 장소 등을 포함	O
payload	`String`	페이로드(Payload, 최대: 200자)	X
readExpiresAt	`String`	티켓의 만료 일시 지정(최대: 요청 일시로부터 14일 이내) `yyyy-MM-dd'T'HH:mm:ss` 형식 중요: 티켓의 사용이 만료되어야 하는 시점으로 설정	O
ci	`String`	사용자 식별을 위한 수신인 정보, CI(최대: 88자)	X
phoneNumber	`String`	사용자 식별을 위한 수신인 정보, 전화번호 `01012345678` 형식	X
name	`String`	사용자 식별을 위한 수신인 정보, 이름	X
birthday	`String`	사용자 식별을 위한 수신인 정보, 생년월일 `yyyyMMdd` 형식	X
externalId	`String`	문서 매핑(Mapping)용 식별자(최대: 40자) 중요: 발송기관 내부에서 활용하는 예매 번호 관리 등에 사용	O

Content

이름	타입	설명	필수
appLink	`String`	이용기관의 티켓 페이지 앱링크 URL, `T14` 상품 사용 시 필수 영문과 키보드에서 입력 가능한 특수문자만 지원(최대: 1,000자)	O

응답

본문

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

Result

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

예제

요청

curl -v -X POST "https://edoc-gw.kakao.com/v1/bulk/envelopes/T14_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": "2026-01-01 라이언 콘서트 티켓",
                "content": {
                    "appLink": "myapp://my/ticket"
                },
                "guide": "홍길동님의 라이언 콘서트 입장 티켓을 보내드려요.\n\n입장일시: 2026-01-01\n장소: 라이언스타디움",
                "payload": "이용기관 페이로드",
                "readExpiresAt": "2026-01-01T22:00:00",
                "phoneNumber": "01099999999",
                "name": "홍길동",
                "birthday": "20000303",
                "externalId": "external_id1"
            },
            {
                "title": "2026-01-01 라이언 콘서트 티켓",
                "content": {
                    "appLink": "myapp://my/ticket"
                },
                "guide": "홍길순님의 라이언 콘서트 입장 티켓을 보내드려요.\n\n입장일시: 2026-01-01\n장소: 라이언스타디움",
                "payload": "이용기관 페이로드",
                "readExpiresAt": "2026-01-01T22: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"
    }
  ]
}

토큰 검증

기본 정보

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

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

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

제약 조건

전자문서 원문이 앱링크인 경우에만 사용하는 API입니다. 문서 발송 및 열람 과정을 참고합니다.

토큰 검증에 성공한 경우에만 사용자에게 티켓 페이지 접근을 허용해야 합니다.

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

myapp://my/ticket?token=${TOKEN}&envelopeId=${ENVELOPE_ID}

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

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

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

요청

헤더

이름	설명	필수
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
`${TOKEN}`	`String`	일회용 토큰	O

응답

본문

이름	타입	설명	필수
envelopeId	`String`	문서 고유 ID	O
externalId	`String`	문서 매핑용 식별자 문서 발송 API 요청 시 지정한 경우에만 응답에 포함	X
status	`String`	문서 상태, 아래 중 하나 `RECEIVED`: 수신, 미열람 `READ`: 열람 `EXPIRED`: 열람 만료 일시 초과	O
sentAt	`String`	문서 송신 일시	O
receivedAt	`String`	문서 수신 일시	O
readAt	`String`	문서 열람 일시	X
authenticatedAt	`String`	문서 열람 인증 일시	X
ottVerifiedAt	`String`	토큰 검증 일시	X
isNotificationUnavailable	`Boolean`	사용자의 알림톡 수신 가능 여부	X
userNotifiedAt	`String`	사용자의 알림톡 수신 일시	X
payload	`String`	문서 발송 API 요청 시 전달한 페이로드	X

예제

요청

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": "2026-01-01T17:45:14",
  "receivedAt": "2026-01-01T17:45:15",
  "readAt": "2026-01-01T17:51:22",
  "authenticatedAt": "2026-01-01T17:51:20",
  "ottVerifiedAt": "2026-01-01T17:51:21",
  "userNotifiedAt": "2026-01-01T17:45:16",
  "payload": "이용기관 페이로드"
}

문서 열람 처리

기본 정보

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

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

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

주의

전자문서 원문이 앱링크인 경우, 문서 열람 처리 API 요청과 별개로 이용기관의 의무에 따른 조치가 필요합니다.

제약 조건

전자문서 원문이 앱링크인 경우에만 사용하는 API입니다. 문서 발송 및 열람 과정을 참고합니다.

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

문서를 열람 상태로 변경하지 않으면, 사용자가 문서를 열람했더라도 문서 상태는 읽지 않음으로 유지됩니다. 이 경우, 문서 상태 조회 API 호출 시 열람시간 데이터를 응답받을 수 없습니다.

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

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

요청

헤더

이름	설명	필수
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

예제

요청

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

문서 상태 조회

기본 정보

메서드	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`: 수신, 미열람 `READ`: 열람 `EXPIRED`: 열람 만료 일시 초과	X
sentAt	`String`	문서 송신 일시	X
receivedAt	`String`	문서 수신 일시	X
readAt	`String`	문서 열람 일시	X
readExpiredAt	`String`	문서 열람 만료 일시	X
authenticatedAt	`String`	문서 열람 인증 일시	X
ottVerifiedAt	`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": "2026-01-01T17:45:14",
      "receivedAt": "2026-01-01T17:45:15",
      "readAt": "2026-01-01T17:51:22",
      "readExpiredAt": "2026-01-01T22:00:00",
      "authenticatedAt": "2026-01-01T17:51:20",
      "ottVerifiedAt": "2026-01-01T17:51:21",
      "userNotifiedAt": "2026-01-01T17:45:16",
      "payload": "이용기관 페이로드"
    },
    {
      "envelopeId": "${ENVELOPE_ID}",
      "errorCode": "D400_00",
      "errorMessage": "문서[${ENVELOPE_ID}]를 찾을 수 없습니다"
    }
  ]
}

사이드 메뉴

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

카카오맵

내비게이션

광고

검색

더 보기

T14: 모바일티켓

시작하기 전에

상품 소개

문서 발송 및 열람 과정

T14: 앱링크 타입

알림

문서 수신 알림톡 구성 요소

문서 발송

단건 발송

기본 정보

요청

헤더

경로 변수

본문

Content

응답

본문

예제

요청

응답

다건 발송

기본 정보

요청

헤더

경로 변수

본문

Envelope

Content

응답

본문

Result

예제

요청

응답

토큰 검증

기본 정보

요청

헤더

경로 변수

응답

본문

예제

요청

응답

문서 열람 처리

기본 정보

요청

헤더

경로 변수

예제

요청

응답

문서 상태 조회

기본 정보

요청

헤더

본문

응답

본문

EnvelopeStatus

예제

요청

응답

더 보기

도움이 되었나요?

T14: 모바일티켓