SPEED — Hệ thống tra cứu vận chuyển

Tính năng chính

Mỗi dịch vụ đều có giao diện tra cứu và API REST.

CJ Logistics

Lộ trình giao hàng. JSON được tối giản và chuẩn hoá trường theo hệ thống.

Trả về carrier, from/to, progresses[], state
Ổn định & dễ ánh xạ

UNIPASS (통관)

Kiểm tra thông quan theo HBL. Nếu không truyền year, hệ thống tự thử năm hiện tại và lùi tối đa 3 năm.

Thời gian, mã cổng/kho, trạng thái xử lý
Trả về cargCsclPrgsInfoQryVo & cargCsclPrgsInfoDtlQryVo[]

Chuẩn hoá địa chỉ

Nhận text/URL ảnh/ảnh upload; hệ thống trích xuất & chuẩn hoá địa chỉ, xác minh qua Kakao.

Đa định dạng đầu vào
Ưu tiên đầu ra dia_chi_xac_minh

Phản hồi được tối giản tự động để thuận tiện tích hợp và giảm nhiễu. Định dạng mặc định: JSON UTF-8.

Tài liệu API rút gọn

Tất cả endpoint trả JSON. Sử dụng HTTPS. Rate-limit theo gói dịch vụ.

CJ Logistics API

GET /api/cj/{key}?ma_van_don=<MA_VAN_DON>

# cURL
curl -sS "https://<domain>/api/cj/{key}?ma_van_don=507064979121" \
  -H "Accept: application/json"

Cấu trúc: carrier, from/to, progresses[], state.

UNIPASS API

GET /api/unipass/{key}?ma_van_don=<HBL>&year=<YYYY>

# cURL
curl -sS "https://<domain>/api/unipass/{key}?ma_van_don=HBL123456&year=2025" \
  -H "Accept: application/json"

Thiếu year → hệ thống tự thử năm hiện tại và lùi tối đa 3 năm.

Chuẩn hoá Địa chỉ

POST /api/dia_chi/{key}

# cURL (text)
curl -sS -X POST "https://<domain>/api/dia_chi/{key}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "tham_so=대구 서구 서대구로64 | 010-1234-5678"

# cURL (upload ảnh)
curl -sS -X POST "https://<domain>/api/dia_chi/{key}?tham_so=영수증" \
  -F "files[]=@/path/label1.jpg" \
  -F "files[]=@/path/label2.png"

Triển khai & Hỗ trợ

Định dạng phản hồi

Mặc định: application/json; charset=utf-8. Thời gian theo ISO-8601 (UTC hoặc local tuỳ nguồn).

Tuỳ chọn: pretty=1 để in đẹp.
Lỗi trả về code, message.

Bảo mật

Khoá API qua ENV, giới hạn IP theo gói. Nhật ký gọi API lưu 7–30 ngày để đối soát.

Hỗ trợ tích hợp

Cung cấp snippet PHP/JS/Apps Script; hỗ trợ mapping dữ liệu & checklist triển khai.

SLA & Rate-limit

Uptime mục tiêu: 99.9%
Thời gian phản hồi điển hình: < 800ms nội địa
Giới hạn mặc định: tuỳ gói (có thể nâng theo nhu cầu)

Liên hệ để cấu hình SLA/rate phù hợp luồng của bạn.

Tích hợp nhanh

PHP

$res = file_get_contents('https://<domain>/api/cj/{key}?ma_van_don=507064979121');
$data = json_decode($res, true);

JavaScript (fetch)

const r = await fetch('/api/unipass/{key}?ma_van_don=HBL123&year=2025');
const data = await r.json();

Apps Script

const r = UrlFetchApp.fetch('<domain>/api/dia_chi/{key}',{
  method:'post', payload:{ tham_so:'서울 강남구 테헤란로 123 | 010-1234-5678' }
});

FAQ

JSON có thay đổi cấu trúc không?

Chúng tôi giữ cấu trúc ổn định; các bổ sung sẽ theo hướng tương thích ngược.

URL tải file không có đuôi mở rộng có dùng được?

Được. Hệ thống cố gắng nhận dạng nội dung và xử lý tự động.

Có sandbox test không?

Có thể cấp endpoint sandbox theo gói.