Tích hợp API bên thứ 3 — GPS, Cảng, ePort

Kết nối hệ thống với VietMap GPS, ePort và ADA để tự động nhận vị trí xe và sự kiện container — không cần nhập tay. Route: /settings/integrations.

Tổng quan

Mỗi connector hoạt động như một emitter sự kiện mới — downstream (Fleet, Container, SLA) không thay đổi logic, chỉ nhận thêm nguồn event từ bên ngoài.

Connector	Emitter	Downstream nhận
VietMap GPS	Vị trí xe real-time + gate timestamp	Fleet Trip, Container state
ePort	Container events từ cảng Hải Phòng, Cát Lái	Container lifecycle, SLA, alert
ADA	Thông tin tàu, cảng, lịch trình ETA	Shipment ETA, SLA deadline

Connector = add-on

Mỗi connector là tính năng add-on — chỉ bật được khi có tài khoản thật của nhà cung cấp (VietMap, ePort). Không có mock data. Xem gói dịch vụ để biết connector nào được bao gồm.

Idempotent dedup

Mọi event nhận từ bên ngoài được dedup bằng externalEventId — gửi lại nhiều lần không tạo duplicate trong hệ thống.

VietMap GPS

Kết nối VietMap Fleet API để nhận vị trí xe real-time và phát hiện tự động khi xe vào/ra khu vực cảng (geofence).

Tính năng sau khi kết nối:

Tính năng	Mô tả
Vị trí real-time	Tọa độ GPS cập nhật mỗi 30–60 giây từ thiết bị trên xe
Gate timestamp (geofence)	Tự nhận biết xe vào/ra cổng cảng — thay nhập tay gate time
Trip IN_PROGRESS tự cập nhật	Khi xe bắt đầu di chuyển, Trip tự chuyển sang IN_PROGRESS
DELIVERED auto-detect	Khi xe dừng tại địa chỉ đích > 10 phút, đề xuất mark DELIVERED

Các bước kết nối:

Lấy VietMap API key — Đăng nhập tài khoản VietMap Fleet → API Management → tạo API key với quyền read vehicle location.
Kết nối trong TKHQ — Vào /settings/integrations → VietMap GPS → nhập API key → nhấn Kết nối. Credentials được mã hóa AES-256 trước khi lưu.
Map biển số xe — Trong danh sách xe Fleet → mỗi xe có trường vietmapDeviceId. Nhập ID thiết bị GPS tương ứng để liên kết.
Cấu hình geofence cảng — Vào /settings/geofences → thêm khu vực cổng cảng (polygon trên bản đồ). Hệ thống tự phát hiện xe vào/ra và ghi gate timestamp.

ePort / ADA

ePort (Tân Cảng) và ADA (cảng Hải Phòng) cung cấp API theo dõi container real-time. Kết nối để TKHQ tự nhận sự kiện thay vì nhập tay từ email/zalo.

Sự kiện nhận từ cảng và tác động:

Sự kiện nhận từ cảng	Tác động trong TKHQ
DISCHARGED (tàu dỡ hàng)	Container → DISCHARGED, SLA bắt đầu tính DEM
GATE_OUT (container ra cảng)	Container → GATE_OUT, SLA DEM kết thúc, DET bắt đầu
GATE_IN (container vào cảng)	Container → GATE_IN, tự update seal number
VESSEL_DEPARTED (tàu rời cảng)	Booking → ON_VESSEL, ETA cập nhật
EMPTY_RETURNED	Container → RETURNED, DET kết thúc, tính phí nếu có

SLA và Alert tự chạy

Sau khi kết nối ePort/ADA, SLA Engine nhận event tự động — không cần nhập thủ công. Alert DEM/DET sẽ đúng thời gian thực thay vì phụ thuộc người cập nhật.

Các bước kết nối:

Đăng ký API tại cảng — Liên hệ ePort (Tân Cảng Sài Gòn) hoặc ADA (cảng Hải Phòng) để đăng ký tài khoản API doanh nghiệp. Nhận username/password hoặc API key.
Nhập credentials vào TKHQ — Vào /settings/integrations → chọn ePort hoặc ADA → nhập credentials → test kết nối.
Map container với account cảng — Hệ thống tự lắng nghe event cho tất cả container trong workspace. Chỉ nhận event cho container có số container khớp trong danh sách.

Bảo mật & add-on

Bảo mật credentials:

Biện pháp	Chi tiết
Mã hóa at-rest	AES-256-GCM — credentials không lưu plaintext
Không log credentials	API key không xuất hiện trong access log hay error log
Revoke bất kỳ lúc	Nhấn Ngắt kết nối → credentials xóa khỏi hệ thống ngay
Per-workspace isolation	Credentials của workspace A không dùng được ở workspace B

Add-on activation:

Add-on	Yêu cầu gói
VietMap GPS connector	Pro trở lên + tài khoản VietMap thật
ePort connector	Pro trở lên + tài khoản ePort doanh nghiệp
ADA connector	Pro trở lên + tài khoản ADA

External API = emitter mới, downstream không đổi

Khi bật connector, chỉ có nguồn event thay đổi (từ nhập tay sang tự động). Toàn bộ logic downstream (SLA, alert, container state machine) hoạt động y hệt — không cần cấu hình lại.

SePay — Thanh toán VietQR

SePay là cổng thanh toán chính cho subscription và top-up token. Hệ thống nhận xác nhận tự động qua webhook HMAC-SHA256.

Luồng thanh toán đầy đủ:

Người dùng chọn gói
    → Hệ thống tạo order + QR code SePay
    → Người dùng quét QR + chuyển khoản
    → SePay nhận tiền → gọi webhook đến TKHQ
    → TKHQ xác thực HMAC-SHA256
    → Cập nhật subscription / token wallet
    → Emit payment.succeeded → Outbox → downstream

Nội dung chuyển khoản: Format TKHQ-{orderCode} được sinh tự động — không sửa. Webhook match theo nội dung này.

Idempotency: Nếu SePay gửi webhook 2 lần (retry), hệ thống chỉ xử lý lần đầu nhờ idempotencyKey = orderCode.

Webhook xác thực HMAC

TKHQ từ chối mọi webhook không có chữ ký HMAC-SHA256 hợp lệ từ SePay — bảo vệ chống fake payment notification.

Telegram Notifier

Gửi alert đến team nội bộ qua Telegram Bot. Hỗ trợ Message Thread ID để phân loại alert vào từng topic riêng trong supergroup.

Các loại alert gửi qua Telegram:

Loại alert	Kênh khuyến nghị
DEM/DET sắp hết	#logistics-alerts
Lead mới từ website	#sales
SLA breach	#ops-urgent
Thanh toán thành công	#finance
Xe sắp hết đăng kiểm	#fleet

Cấu hình nhiều topic → mỗi loại alert đi đúng thread, tránh noise.

Xem hướng dẫn cài đặt chi tiết → Thông báo Telegram & Zalo.

Chế độ sandbox (môi trường phát triển)

VietMap GPS và ePort hoạt động ở chế độ sandbox trên môi trường dev/staging:

Không có dữ liệu thật từ xe/cảng
Dữ liệu được giả lập từ fixture
Cần tài khoản thật của VietMap / ePort để dùng trên production

Gated integrations

Các connector GPS và ePort chỉ hoạt động với tài khoản API thật. Không có chế độ demo trên production. Đây là chính sách đã thay đổi từ 2026-06-09 — các claim "live GPS tracking" trên marketing đã được cập nhật để phản ánh đúng thực tế.

Retry và error recovery

Tất cả event nhận từ bên ngoài (ePort, SePay webhook) đều đi qua queue BullMQ với 3 lần retry + exponential backoff:

Lần thử	Delay	Hành động nếu vẫn fail
1	Ngay lập tức	—
2	30 giây	—
3	5 phút	Move vào dead-letter queue
Sau dead-letter	—	Alert admin, cần xử lý thủ công

Dead-letter queue được xem tại Bull Board UI — admin có thể retry thủ công sau khi fix nguyên nhân gốc.

Tích hợp API bên thứ 3 — GPS, Cảng, ePort ​

Tổng quan ​

VietMap GPS ​

ePort / ADA ​

Bảo mật & add-on ​

SePay — Thanh toán VietQR ​

Telegram Notifier ​

Chế độ sandbox (môi trường phát triển) ​

Retry và error recovery ​