GS편의점택배 조회 API

GS편의점택배(GS Postbox) 소개

운영사는 주식회사 GS네트웍스이며, 예전 사명인 CVSnet이 지금도 공식 도메인과 조회 화면 주소에 남아 있습니다. 코드값에 cvsnet이 별칭으로 들어가 있는 것도 이런 이력 때문입니다. 브랜드 표기는 GS Postbox이고, 이용자에게는 GS25 편의점택배로 더 알려져 있습니다.

상품군은 국내택배, 반값택배, 내일택배, 방문택배, 국제택배까지 다섯 가지입니다. 점포에서 접수하는 상품과 기사가 찾아오는 방문택배가 한 브랜드 안에 함께 있어서, 같은 송장이라도 물건이 처음 시스템에 잡히는 지점이 다를 수 있습니다. 공식 조회 화면은 GS Postbox 예약·조회 페이지입니다.

기본 정보

택배사명	GS편의점택배
운영사	주식회사 GS네트웍스 (구 사명 CVSnet)
서비스 브랜드	GS Postbox
API courier code	gspostbox (별칭: gspost, cvsnet)
고객센터	1577-1287 (국내택배·내일택배) / 1544-4101 (반값택배)
취급 상품	국내택배, 반값택배, 내일택배, 방문택배, 국제택배
지원 범위	조회(tracking) 전용 — 계정 기반 등록·출력은 지원하지 않습니다

송장번호 형식

GS편의점택배 송장번호는 숫자만 8~12자리입니다. 하한이 8이고 상한이 12인 넓은 구간이라, 자릿수만 보고 택배사를 자동 판별하려 하면 다른 택배사와 겹칠 가능성이 큽니다. 발송처에서 courier code를 함께 받아 두는 편이 안전합니다.

이 범위는 공식 조회 화면의 입력 규칙에서 나온 값입니다. 상품 탭에 따라 요구하는 최소 길이가 달라 국내택배는 10자리 이상, 내일택배는 8자리 이상을 요구하며, 입력칸의 maxlength는 12로 묶여 있습니다. 결국 전체 허용 폭은 8~12자리가 되고, 숫자 이외의 문자는 조회 대상이 아니므로 하이픈·공백은 요청 전에 제거해 주세요.

API 연동 예시

조회는 단일 엔드포인트 호출로 끝납니다. {API_KEY}와 {SECRET_KEY}에는 발급받은 키 쌍을 넣으세요.

curl -X POST https://api.deliveryapi.co.kr/v1/tracking/trace \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_KEY}:{SECRET_KEY}" \
  -d '{
    "items": [
      {
        "courierCode": "gspostbox",
        "trackingNumber": "210604362986"
      }
    ]
  }'

items는 배열이므로 GS편의점택배 송장 여러 건을 한 번에, 또는 다른 택배사 송장과 함께 묶어 보낼 수 있습니다. 응답 필드 정의와 오류 코드는 API 문서를 참고하세요.

배송 경로와 단계

GS편의점택배의 이력은 점포에서 시작해 두 종류의 센터를 거친 뒤 다시 점포로 돌아오는 흐름으로 쌓입니다. 접수 점포에서 걷어 온 물건이 지역 집화센터에 모이고, 다시 전국 물량을 갈라 주는 허브센터를 통과한 다음, 수령 측 점포로 내려가는 구조입니다.

순서	이력 문구	의미
1	점포에서 접수	GS25 점포에서 운송장이 발행되고 물건이 맡겨진 시점
2	집화센터에 도착	점포에서 걷어 온 물건이 지역 집화센터에 들어옴
3	허브센터에 도착	권역 간 분류 거점을 통과하며 목적지 방향으로 이동
4	점포에 도착	수령 점포까지 왔지만 아직 수령인이 찾아가지 않음
5	고객에게 전달	수령인이 물건을 받아 배송이 종료됨

4단계 점포에 도착을 배송 완료로 처리하면 안 됩니다. 이 시점의 물건은 점포 보관대에 놓여 있을 뿐이고, 실제로 손에 들어가는 건 수령인이 점포를 방문한 뒤입니다. 운송 구간이 끝난 것과 인수가 끝난 것을 나누어 보는 것이 이 택배사를 다룰 때의 핵심입니다.

배송 상태 코드 매핑

위 다섯 문구는 API에서 아래와 같이 통합 상태값으로 정규화되어 나갑니다. 택배사 원문 대신 이 상태값을 기준으로 분기하면 다른 택배사와 같은 코드로 처리할 수 있습니다.

GS Postbox 표기	통합 상태	설명
점포에서 접수	REGISTERED	운송장이 등록되었고 아직 운송이 시작되지 않았습니다.
집화센터에 도착	PICKED_UP	택배사가 물건을 인수해 집화센터에 입고했습니다.
허브센터에 도착	IN_TRANSIT	분류 거점을 거쳐 목적지 방향으로 이동 중입니다.
점포에 도착	IN_TRANSIT	수령 점포까지 도착했으나 수령 전이라 운송 중으로 유지됩니다.
고객에게 전달	DELIVERED	수령인에게 물건이 전달되었습니다.

자주 묻는 질문 (FAQ)

GS편의점택배의 courier code는 무엇인가요?

표준값은 gspostbox이며, 요청 본문에 "courierCode": "gspostbox"로 넣으면 됩니다. 과거 코드 체계를 쓰던 시스템이라면 gspost나 cvsnet을 그대로 보내도 되며, 별칭으로 등록되어 있어 동일한 결과를 받습니다.

송장번호 자릿수를 검증해도 되나요?

숫자만 8~12자리라는 범위 검사까지는 안전합니다. 다만 12자리(210604362986)만 유효하다고 가정하면 8~9자리 내일택배 송장이 걸러져 버립니다. 상품마다 길이가 다르다는 점을 전제로 느슨하게 받아 두고, 최종 판정은 API 응답에 맡기는 쪽을 권합니다.

'점포에 도착'인데 왜 아직 DELIVERED가 아닌가요?

GS편의점택배는 수령 점포를 최종 인수 지점으로 쓰기 때문에, 점포 도착과 고객 인수 사이에 시간 간격이 생깁니다. 그래서 점포에 도착은 IN_TRANSIT으로 두고, 고객에게 전달이 찍힌 뒤에 DELIVERED로 넘어갑니다. 수령 안내 알림을 보내는 서비스라면 바로 이 4단계에서 "찾아가세요" 문구를 띄우는 것이 자연스럽습니다.

운송장 발행이나 출력도 API로 되나요?

되지 않습니다. GS편의점택배는 조회(tracking)만 지원합니다. 접수는 GS25 점포나 방문택배 신청을 통해 이루어지고, 발행된 송장번호를 받아 조회하는 용도로 API를 쓰게 됩니다.

배송 문의 전화번호가 두 개인 이유는 무엇인가요?

상품별로 응대 창구가 나뉘어 있습니다. 국내택배와 내일택배는 1577-1287, 점포 간 배송인 반값택배는 1544-4101로 문의하면 됩니다.