택배조회API FAQ

CJ대한통운, 롯데택배, 한진택배, 우체국택배 등 국내 주요 13개 택배사의 배송 조회·등록·관리를 하나의 REST API로 통합한 개발자용 SaaS 서비스입니다.

가입 없이 https://www.deliveryapi.co.kr/api-test 에서 데모 키로 동일 IP 기준 하루 20회까지 실제 API를 호출해볼 수 있습니다(응답의 demoUsage 필드에서 남은 횟수 확인). 실제 연동은 종량 요금제 구독이 필요하며, 한국 신규 가입자에게는 무료 플랜이 발급되지 않습니다.

종량 요금제 하나입니다. 월 29,900원에 3,000건이 포함되고, 초과분만 사용한 만큼 뒤에 붙습니다.

• 3,001~10,000건: 건당 7원
• 10,001~30,000건: 건당 5원
• 30,001건~: 건당 4원

최대 결제금액을 직접 정할 수 있고, 그 금액에 도달하면 조회가 멈추므로 상한을 넘겨 청구되지 않습니다. 해외 택배사 조회는 1건이 10건으로 과금됩니다. 웹훅은 등록 시 1건만 차감되고 이후 자동 폴링은 과금되지 않습니다.

택배사 계정을 등록해 배송 등록·대량 발송을 쓰려면 슬롯 결제가 별도로 필요합니다(1번째 슬롯 50,000원/월, 2~10번째 30,000원, 11~100번째 10,000원, 101~200번째 5,000원).

무료·스타터·플러스·그로스·프로·비즈니스 등급은 기존 이용자 전용이며 신규 판매하지 않습니다.

1. https://www.deliveryapi.co.kr/auth/register 에서 이메일 가입(6자리 인증 코드) → 2) API Key + Secret Key 자동 발급 → 3) https://www.deliveryapi.co.kr/plan 에서 종량 요금제 구독 → 4) Authorization: Bearer {apiKey}:{secretKey} 헤더로 호출. 구독 전에는 https://www.deliveryapi.co.kr/api-test 의 데모 키로 먼저 체험해 보실 수 있습니다.

1. 가입 후 API Key/Secret Key를 발급받고 종량 요금제를 구독합니다. 모든 호출에 Authorization: Bearer {apiKey}:{secretKey} 헤더를 사용합니다.
2. 단발성 조회는 송장번호로 POST /v1/tracking/trace를 호출합니다(택배사 계정 불필요).
3. 지속 추적은 tracking/trace를 반복 호출하지 말고 웹훅을 쓰세요 — POST /v1/webhooks/endpoints로 알림 받을 URL을 등록한 뒤 POST /v1/webhooks/register(recurring:true)로 송장을 등록하면 14일간 1시간 간격으로 자동 폴링되어 상태가 바뀔 때 콜백이 옵니다. 등록 건당 1회만 과금되고 이후 폴링은 무과금입니다.

문서 https://www.deliveryapi.co.kr/docs · 테스트 https://www.deliveryapi.co.kr/api-test

CJ대한통운, 롯데택배, 한진택배, 우체국택배, 로젠택배, 경동택배, 대신택배, 합동택배, 쿠팡택배, 우리택배, CU편의점택배, GS편의점택배, 롯데백화점택배 총 13개입니다. 배송 등록(발송)은 롯데·CJ대한통운 계정 등록 시 가능합니다.

네. 송장번호만 있으면 택배 계정 없이 POST /v1/tracking/trace로 배송 조회가 가능합니다.

결과(배송 상태)는 같은 소스라 동일하고, 확인하는 방식이 다릅니다.

• 조회(POST /v1/tracking/trace) — Pull 방식. 필요할 때 호출해 그 시점의 최신 상태를 즉석에서 받아옵니다(예: 고객이 '배송조회' 버튼 클릭). 계속 알려면 반복 호출해야 하는데 요청 제한에 걸립니다.
• 추적(POST /v1/webhooks/register) — Push 방식. 송장을 한 번 등록하면 저희가 대신 주기적으로 폴링(recurring:true → 14일간 1시간 간격)하고, 상태가 바뀔 때 등록한 콜백 URL로 알림을 보냅니다. 등록 시 건당 1회만 과금되고 이후 폴링은 무과금입니다.

요약하면 조회는 '내가 매번 당겨오기', 추적은 '한 번 등록하고 변경 시 밀어받기'입니다.

POST https://api.deliveryapi.co.kr/v1/webhooks/endpoints로 수신할 URL을 등록합니다(API Key당 최대 10개). 응답의 webhookSecret은 최초 1회만 표시되므로 안전하게 보관하세요. 수신 시에는 X-Webhook-Signature 헤더를 "{timestamp}.{JSON body}"의 HMAC-SHA256(webhookSecret) 값과 비교해 검증하는 것을 권장합니다. 등록 현황은 GET /v1/webhooks/subscriptions로 확인할 수 있습니다.

아니요. endpoints는 '알림 받을 콜백 URL'을 등록하는 것이라 송장·상품별이 아니며, 보통 서버 URL 1개만 등록해 두면 됩니다. 추적할 송장은 POST /v1/webhooks/register로 한 번에 최대 100건까지 등록합니다. 정리하면 '콜백 URL은 endpoints로 1회 등록 → 추적할 송장들은 register로 일괄 등록 → 상태 변경 시 그 URL로 알림 수신' 구조입니다.

권장하지 않습니다. 추적 등록에는 Secret Key가 필요하므로 프론트엔드가 아니라 백엔드에서 호출해야 하고, 버튼 클릭마다 등록하면 같은 송장이 중복 등록되며 등록 건당 사용량에 포함됩니다. 백엔드에서 해당 송장이 이미 구독 중인지 먼저 확인(자체 DB 또는 GET /v1/webhooks/subscriptions)한 뒤 미등록일 때만 등록하세요. 상태 변경 알림을 받아 DB에 저장한 값을 화면에 보여주는 구조를 권장합니다.

안 됩니다. POST /v1/tracking/trace를 포함한 모든 호출은 Authorization: Bearer {apiKey}:{secretKey} 헤더가 필요한데, Secret Key는 브라우저 등 클라이언트에 절대 노출하면 안 됩니다.

'프론트엔드 버튼 → 여러분의 백엔드 엔드포인트 → 백엔드에서 tracking/trace 호출 → 결과를 프론트로 전달' 구조를 사용하세요. Secret Key는 서버에만 남고 프론트는 여러분의 서버하고만 통신합니다. 웹훅 추적으로 갱신되는 상태와 tracking/trace 조회 결과는 같은 배송 건의 현재 상태이므로 서로 일치합니다.

유출이 의심되면 새 Secret Key를 추가 발급받아 교체한 뒤 기존 키를 폐기하세요.

인증 헤더 Authorization: Bearer {apiKey}:{secretKey}(콜론 연결, 공백 없음)를 붙여 사용량에 포함되지 않는 GET /v1/tracking/couriers(지원 택배사 목록)를 호출해 보세요. 응답의 isSuccess가 true이면 키가 정상입니다. 401 UNAUTHORIZED가 나오면 키 값과 헤더 형식, Base URL(https://api.deliveryapi.co.kr/v1)을 확인하세요. 브라우저에서는 https://www.deliveryapi.co.kr/api-test 에서 바로 테스트할 수 있습니다.

두 종류가 함께 적용됩니다.

• IP별 전역 제한: 인증 여부와 무관하게 동일 IP에서 분당 600회. 모든 플랜 공통입니다.
• 키별 한도: 종량 요금제는 분당 300회이고 시간·일 단위 제한은 없습니다. 월 한도는 직접 지정한 최대 결제금액에서 역산된 건수입니다. 기존 무료 플랜(신규 발급 중단)은 분 5회 · 시간 10회 · 하루 10회 · 월 100회입니다.

초과 시 429 응답의 limitType·limit 필드로 어떤 제한에 걸렸는지 확인할 수 있습니다. 가입 전 데모 키는 별도로 동일 IP 기준 하루 20회입니다.

롯데택배는 ID/PW만 입력하면 즉시 등록됩니다. CJ대한통운은 ID/PW 입력 후 문자 인증이 필요합니다 — 1522-7513에서 문자가 오면 "99"를 답장하고 3분 이내에 OTP 검증 API를 호출하면 됩니다.

한 번에 최대 1,000건까지 등록할 수 있습니다. 송장번호는 등록 시점이 아니라 대부분 송장 출력 시점에 발급된다는 점에 주의하세요.

카드 한도·유효기간·해외결제 차단 여부를 먼저 확인해 주세요. 그래도 결제가 되지 않으면 [email protected] 또는 카카오톡 오픈채팅으로 가입 이메일과 함께 문의해 주시면 결제 상태를 확인해 드립니다. (카드번호 등 결제 수단 정보는 채팅에 직접 입력하지 마세요.)

택배API는 각 택배사가 제공하는 조회 채널을 자동화해 배송 정보를 수집·표준화하는 시스템을 자체 운영합니다. 택배사마다 조회 방식과 응답 형태가 달라, 이를 하나의 통일된 REST API와 공통 배송 상태 코드로 정리해 제공하는 것이 서비스의 핵심입니다. 수집 계층의 세부 구현(접속 방식·인증 처리·서버 구성 등)은 서비스 안정성과 보안을 위해 외부에 공개하지 않습니다.

네. 무료 제공하는 엑셀 VBA 매크로(https://www.deliveryapi.co.kr/tools/excel-tracker)로 송장번호를 일괄 조회할 수 있습니다. Windows + Excel(매크로 활성화) 환경이 필요합니다.

네. REST API이므로 카페24, 메이크샵, 고도몰, 스마트스토어 등 어떤 쇼핑몰이든 연동 가능합니다. JavaScript, Python, Java, PHP, C# 샘플 코드와 SDK(npm/pip deliveryapi)를 제공하며 평균 30분이면 연동됩니다.

카카오톡 오픈채팅(https://open.kakao.com/o/gat9mvki) 또는 [email protected] 로 문의하시면 됩니다. API 문서는 https://www.deliveryapi.co.kr/docs 에 있습니다.