Tích hợp

Trang Quản lý tích hợp dành cho doanh nghiệp muốn đặt đơn từ hệ thống của mình qua API. Đơn tạo qua API cũng hiện ở Quản lý đơn hàng.

Trang có 6 tab: Tổng quan · API key · Webhook · Nhật ký callback · Kiểm thử · Giả lập đơn hàng.

Quy trình 4 bước tới go-live

1. Gửi yêu cầu→2. Nhận tài khoản Staging→3. Tích hợp và kiểm thử→4. Go-live Production

Tab Tổng quan: quy trình 4 bước và thông tin môi trường Staging

Điều kiện go-live

Sau khi tích hợp trên Staging, bạn phải chạy và đạt toàn bộ test case bắt buộc ở tab Kiểm thử. Ahamove chỉ mở tài khoản Production khi tất cả test case ở trạng thái Đạt. Sau đó bấm Gửi yêu cầu Go-live ở tab Kiểm thử.

Môi trường Staging	Giá trị
API domain	`https://partner-apistg.ahamove.com`
Portal	`https://business-stg.ahamove.com`
Chi phí	Sandbox, không phát sinh chi phí

Tài liệu chi tiết các API: developers.ahamove.com/docs/api-reference.

API key

Key dùng để xác thực các lệnh gọi server-to-server tới Ahamove API.

Cột	Ý nghĩa
Tên	Tên đặt cho key, kèm ngày hết hạn. Nhãn IP mới: có địa chỉ IP mới dùng key trong 30 ngày qua, xem ở chi tiết key
Key	Chỉ hiện dạng đã che, ví dụ `sk_test_••••••••Z7MK`. Không xem lại được toàn bộ key trên portal
Ngày tạo	Ngày tạo key
Lấy token gần nhất	Lần gần nhất hệ thống của bạn dùng key này. Key lâu không dùng nên thu hồi
Trạng thái	Ví dụ Đang hoạt động

Key staging có tiền tố sk_test_.
Key có ngày hết hạn. Tạo key mới và thay vào hệ thống của bạn trước ngày đó.

Giữ API key bí mật

Tạo lại key ngay khi nghi bị lộ. Tuyệt đối không để lộ key Production trong mã phía client, ứng dụng di động hay repository công khai. Key cho phép đặt đơn và trừ tiền thay mặt công ty.

Tạo API key mới

Bấm + Tạo API key mới

Đặt Tên key (bắt buộc)

Ghi rõ key dùng ở đâu, ví dụ Order service (production), để sau này biết key nào cần thu hồi.

Chọn Thời hạn

Không hết hạn, 30 ngày, 90 ngày (mặc định) hoặc 1 năm.

Giới hạn IP (khuyến nghị)

Nhập địa chỉ IP (VD 203.0.113.24) hoặc dải IP (VD 10.0.0.0/16) của máy chủ gọi API, bấm + Thêm IP. Để trống nghĩa là cho phép mọi IP.

Bấm Tạo key, sao chép key ngay

Key đầy đủ chỉ hiển thị duy nhất một lần ngay sau khi tạo. Lưu ngay vào nơi an toàn (VD biến môi trường hoặc kho bí mật của máy chủ). Lỡ mất thì tạo key mới và thu hồi key cũ.

Key xuất hiện trong danh sách, ở dạng đã che.

Nên tạo key riêng cho từng hệ thống

Mỗi hệ thống (VD Order service, Kho) dùng một key riêng, có giới hạn IP. Khi một hệ thống bị lộ key, bạn chỉ cần thu hồi đúng key đó.

Chi tiết key: giới hạn IP và lịch sử sử dụng

Bấm vào một dòng key để mở trang chi tiết.

Trang chi tiết API key: cảnh báo IP mới, giới hạn theo IP và lịch sử sử dụng

Giới hạn theo IP. Nhập IP hoặc dải IP vào Danh sách IP cho phép, bấm + Thêm IP rồi Lưu. Chỉ những IP trong danh sách mới dùng được key. Để trống nghĩa là cho phép mọi IP.

Lịch sử sử dụng. Liệt kê từng địa chỉ IP đã dùng key:

Cột	Ý nghĩa
Địa chỉ IP	IP đã gọi bằng key này. IP xuất hiện lần đầu trong 30 ngày có nhãn Mới
Client	Phần mềm gọi API, ví dụ `PostmanRuntime/2.6.0`
Lần đầu / Gần nhất	Thời điểm IP này dùng key lần đầu và lần gần nhất
Bị chặn	Số lần key bị từ chối vì IP không nằm trong danh sách cho phép
Lần ghi nhận	Mỗi IP ghi tối đa 1 lần/phút, nên không phải số request. Chỉ để phân biệt IP dùng một lần với IP dùng thường xuyên

Thấy nhãn "IP mới" thì làm gì?

Mở chi tiết key và xem các IP có nhãn Mới:

IP của hệ thống bạn (máy chủ mới, đổi nhà mạng…): thêm IP đó vào Danh sách IP cho phép để key chỉ dùng được từ các IP này.
IP bạn không nhận ra: thu hồi key ngay và tạo key mới.

Thu hồi key

Ở trang chi tiết key, bấm Thu hồi key (nút đỏ, góc trên bên phải), rồi bấm Thu hồi trong hộp thoại xác nhận. Bấm Huỷ nếu đổi ý.

Key đã thu hồi không dùng được nữa. Tạo key mới và cập nhật vào hệ thống của bạn để thay thế.

Token lấy từ key này cũng hết hạn ngay

Khi thu hồi key, mọi token đã lấy bằng key đó cũng hết hạn ngay, kể cả token chưa tới hạn. Các request API đang dùng những token này sẽ bị từ chối. Hãy cập nhật key mới vào hệ thống và lấy token mới trước khi thu hồi key cũ, để không bị gián đoạn lên đơn.

Riêng khi key bị lộ, thu hồi ngay. Mọi token đã lấy từ key đó cũng bị vô hiệu theo.

Webhook

Webhook là địa chỉ (endpoint) trên hệ thống của bạn để Ahamove gửi sự kiện cập nhật đơn.

Mỗi endpoint hiện phương thức (ví dụ POST), loại xác thực (ví dụ BASIC-AUTH, API-KEY) và timeout (ví dụ 5 giây).
Có thể đăng ký nhiều endpoint. Ahamove gửi sự kiện theo thứ tự đăng ký.
Endpoint cần phản hồi mã 2xx trước khi hết thời gian chờ, nếu không lần gửi bị tính là lỗi. Xem ở Nhật ký callback.
Bấm biểu tượng bút để sửa, thùng rác để xoá.

Thêm webhook

Bấm + Thêm webhook để mở form.

Trường	Giá trị
URL *	Địa chỉ endpoint của bạn, ví dụ `https://partner.example.com/callback`
Method	`GET`, `POST` (mặc định), `PUT`, `PATCH`, `DELETE`
Timeout (giây)	Thời gian tối đa chờ endpoint phản hồi. Mặc định 5
Headers tuỳ chọn	Các header thêm vào mỗi request. Bấm + Thêm header để thêm dòng
Loại xác thực *	Cách Ahamove xác thực với endpoint của bạn, xem bảng dưới

Loại xác thực	Cần điền
`NONE`	Không cần xác thực bổ sung (mặc định)
`API-KEY`	Header name , Scheme* (tuỳ chọn), Token *
`BEARER-TOKEN`	Token *
`BASIC-AUTH`	Username , Password* *

Phần Preview hiện request mẫu sẽ được gửi: endpoint, headers (Content-Type: application/json) và body JSON của một sự kiện đơn hàng. Bấm Sao chép curl để tự gửi thử request này tới endpoint, kiểm tra endpoint trả 2xx trước khi lưu.

Nên dùng xác thực

Chọn API-KEY, BEARER-TOKEN hoặc BASIC-AUTH để endpoint của bạn chỉ nhận request từ Ahamove. NONE chỉ nên dùng khi thử nghiệm.

Nhật ký callback

Theo dõi các lần Ahamove gọi webhook của bạn để dò lỗi tích hợp.

Phần	Gồm
Chỉ số	Tổng callback (kèm số thành công) · Tỷ lệ nhận · Độ trễ p95 (kèm p50) · Callback lỗi
Lưu lượng và tỉ lệ lỗi	Số callback theo thời gian, chia Đã nhận / Chưa tới nơi, kèm đường tỉ lệ lỗi
Độ trễ phản hồi	p95, p50 so với ngưỡng timeout (ví dụ 5.0 giây)
Bảng chi tiết	Thời điểm · Đơn hàng · Trạng thái gửi · Kết quả · Độ trễ. Lọc Kết quả, tìm theo mã đơn hoặc tracking

Đọc bảng chi tiết:

Đơn hàng: mã đơn Ahamove, bên dưới là mã nội bộ của bạn (nếu có).
Trạng thái gửi: trạng thái đơn trong sự kiện, ví dụ CANCELLED.
Kết quả: mã HTTP endpoint của bạn trả về. 200 là nhận thành công; mã khác (ví dụ 429) là lỗi.
Bấm biểu tượng con mắt cuối dòng để xem chi tiết lần gọi.

Callback lỗi nhiều?

Kiểm tra endpoint có trả 2xx đủ nhanh không. Nếu độ trễ p95 sát ngưỡng timeout, hãy để endpoint trả 2xx ngay rồi xử lý sau (bất đồng bộ).

Kiểm thử

Bộ test case bắt buộc trước khi được mở Production.

Chỉ có trên Staging

Tab Kiểm thử chỉ hỗ trợ môi trường Staging để chạy thử tích hợp. Đơn tạo ra để kiểm thử là đơn sandbox, không phát sinh chi phí.

Mỗi case yêu cầu bạn tạo một đơn thật trên Staging theo đúng yêu cầu, rồi nhập mã đơn để hệ thống đối chiếu.

Tab Kiểm thử: danh sách test case theo loại hình Xe máy và chi tiết một case

Chọn loại hình dịch vụ (Xe máy hoặc Xe tải)

Chọn một test case ở cột trái

Đọc phần Yêu cầu với đơn và Dịch vụ chấp nhận (ví dụ SGN-BIKE, SGN-TRUCK-500).

Tạo đơn trên Staging bằng API theo đúng yêu cầu

Nhập mã đơn vào ô bên phải, bấm Kiểm tra

Case chuyển sang Đạt hoặc Không đạt; hệ thống đối chiếu từng tiêu chí (4–5 tiêu chí mỗi case).

Đạt hết test case bắt buộc thì bấm Gửi yêu cầu Go-live

Xem Gửi yêu cầu go-live bên dưới.

Gửi yêu cầu go-live

Khi toàn bộ test case bắt buộc của loại hình đang chọn ở trạng thái Đạt, phía trên danh sách hiện thông báo xanh Đã đạt toàn bộ … test case bắt buộc — sẵn sàng go-live Production.

Bấm Gửi yêu cầu Go-live

Yêu cầu được gửi ngay, không có bước xác nhận. Biên bản kiểm thử được gửi kèm trong email.

Chờ Ahamove liên hệ

Thông báo đổi thành Đã gửi yêu cầu lúc [thời gian]. Đội vận hành sẽ đối soát hợp đồng, hạn mức COD rồi kích hoạt tài khoản Production.

Bấm Tải biên bản kiểm thử để lưu một bản kết quả kiểm thử cho hệ thống của bạn.
Sau khi gửi, nút đổi thành Gửi lại yêu cầu nếu bạn cần gửi lại.
Không thấy thông báo xanh? Vẫn còn case bắt buộc Không đạt hoặc Chưa chạy. Mở case đó, xem dòng lệch ở bảng Đối chiếu tiêu chí, tạo đơn mới đúng yêu cầu rồi bấm Kiểm tra lại.

Danh sách test case

Xe máy (8 bắt buộc)
Xe tải (5 bắt buộc)

Nhóm	Mã	Test case
Tạo đơn	TC-A1	Đơn 1 điểm giao, giao ngay, trả bằng ví đối tác (`payment_method = BALANCE`, `order_time = 0`)
Tạo đơn	TC-A2	Đơn 2 điểm giao có COD, người gửi trả phí
Tạo đơn	TC-A4	Đơn xe máy có dịch vụ kèm theo (TIP, BULKY)
Tạo đơn	TC-A6	Đơn hẹn giờ
Tạo đơn	TC-A7	Tra đơn bằng mã nội bộ của đối tác
Vòng đời đơn	TC-B1-BIKE	Đơn giao thành công, đủ chuỗi trạng thái
Vòng đời đơn	TC-B2-BIKE	Giao thất bại một điểm, hoàn hàng về người gửi
Vòng đời đơn	TC-B3-BIKE	Đối tác tự huỷ đơn trước khi tài xế nhận
Vòng đời đơn	TC-B4-BIKE	Hết thời gian tìm tài xế, hệ thống tự huỷ

Nhóm	Mã	Test case
Tạo đơn	TC-A3	Đơn xe tải đa điểm, tối ưu lộ trình, có kích thước gói hàng (1 điểm lấy + 3 điểm giao)
Tạo đơn	TC-A5	Đơn xe tải có bốc xếp và phí chờ
Vòng đời đơn	TC-B1-TRUCK	Đơn giao thành công, đủ chuỗi trạng thái
Vòng đời đơn	TC-B2-TRUCK	Giao thất bại một điểm, hoàn hàng về người gửi
Vòng đời đơn	TC-B3-TRUCK	Đối tác tự huỷ đơn trước khi tài xế nhận
Vòng đời đơn	TC-B4-TRUCK	Hết thời gian tìm tài xế, hệ thống tự huỷ

Test case loại hình Xe tải: TC-A3 đơn đa điểm tối ưu lộ trình

Giả lập đơn hàng

Bạn điều khiển một tài xế sandbox trên đơn Staging của mình (nhận đơn, lấy hàng, giao từng điểm, trả hàng, huỷ) và đối chiếu callback Ahamove gửi tới webhook của bạn sau từng thao tác.

Chỉ có trên Staging

Đơn giả lập là đơn Staging, không phát sinh chi phí. Tài xế sandbox do Ahamove cấp sẵn. Nếu chọn tài xế bằng số điện thoại hoặc tài xế gần điểm lấy, đó là tài khoản tài xế thật trên Staging: chỉ dùng tài xế của nhóm bạn hoặc người đã đồng ý cho kiểm thử.

Mở công cụ bằng một trong hai cách:

Tab Giả lập đơn hàng ở trang Tích hợp, rồi chọn đơn.
Trong chi tiết đơn, bấm biểu tượng Giả lập đơn hàng (hình bình thí nghiệm) hoặc tab cùng tên, rồi bấm Mở trong Giả lập đơn hàng.

Tab Giả lập đơn hàng: danh sách đơn thử và bảng Hành động đã kiểm chứng

Đơn thử của bạn liệt kê đơn Staging của tài khoản trong 7 ngày gần nhất, gồm đơn tạo qua API và đơn tạo ở Lên đơn. Đơn cũ hơn thì tìm theo mã đơn.

Hành động đã kiểm chứng theo dõi 8 hành động cho mỗi loại đơn (Giao ngay và Giao gộp chuyến), tổng 16. Một hành động chỉ được tính đạt khi mọi callback của nó tới webhook với HTTP 2xx. Bảng cũng nhắc nếu bạn chưa thử đơn nhiều điểm (giao điểm 2 trở đi).

Màn hình giả lập một đơn

Giả lập một đơn: bản đồ tài xế, hành trình đơn hàng với các thao tác của bước tiếp theo

Bản đồ: tài xế chạy theo đường thật. Mỗi thao tác lấy hàng, giao hàng, trả hàng sẽ tự đưa tài xế tới điểm đó trước khi thực hiện, nên bạn không bắt buộc phải bấm Chạy tới…. Dùng Ghim vị trí khi muốn đặt tài xế ở một chỗ cụ thể để thử callback vị trí.
Hành trình đơn hàng: các bước của đơn theo thứ tự, mỗi điểm giao là một bước riêng. Bước đang chờ có nhãn BƯỚC TIẾP THEO kèm nút thao tác. Mục Hủy đơn ở cuối có Tài xế hủy và Bạn hủy đơn.
Bên dưới bản đồ: khu vực Callback tới webhook của bạn, thông tin các điểm, chi tiết thanh toán, hàng hoá và người tạo đơn.

Các thao tác tài xế

Thao tác	Hiện khi	Kết quả	Callback mong đợi
Nhận đơn	Đơn đang tìm tài xế	Chọn tài xế (xem bên dưới), đơn được giao thẳng cho tài xế đó	`status=ACCEPTED` (gửi trễ khoảng 1 giây theo thiết kế)
Ghép chuyến 1-1	Đơn giao gộp (VD `SGN-2H`) chờ tài xế	Ghép đơn vào chuyến gộp `SGN-POOL` trước, sau đó mới nhận đơn	Theo chuyến gộp
Đến nơi	Tài xế đã nhận đơn	Tài xế tới điểm lấy hàng	`sub_status=ARRIVED`, chỉ gửi nếu bạn bật `ARRIVED` trong `support_sub_status`
Đã lấy hàng	Tài xế đã nhận đơn	Đơn chuyển Đang giao hàng	`status=IN PROCESS`
Giao thành công	Từng điểm giao, sau khi lấy hàng	Điểm đó Đã giao hàng	`path[i].status=COMPLETED` (callback theo điểm, `_id` dạng `MÃĐƠN-i`)
Giao thất bại	Từng điểm giao, sau khi lấy hàng	Chọn lý do. Điểm đó Giao hàng không thành công; nếu hàng phải hoàn về (VD điểm có COD), đơn sang Đang hoàn hàng về điểm lấy	`path[i].status=FAILED` kèm lý do
Đã nhận hàng trả	Đơn đang hoàn hàng	Hàng đã về điểm lấy, đơn kết thúc	`sub_status=RETURNED` (luôn gửi, không cần bật)
Tài xế hủy	Tài xế đã nhận, trước khi lấy hàng	Chọn lý do. Đơn được tìm tài xế lại, hoặc bị huỷ nếu dịch vụ không cho tìm lại	`status=ASSIGNING` (hoặc `CANCELLED`)
Bạn hủy đơn	Trước khi lấy hàng	Chọn lý do. Đơn bị huỷ với người huỷ là bạn (đối tác)	`status=CANCELLED`

Khi điểm giao cuối cùng được xử lý xong (thành công hay thất bại), đơn gửi thêm status=COMPLETED.

COMPLETED chưa phải là đã giao

status=COMPLETED chỉ nghĩa là tài xế đã xử lý xong mọi điểm. Kết quả từng điểm nằm ở path[i].status (COMPLETED hoặc FAILED). Hệ thống của bạn phải đọc từng điểm để biết điểm nào giao được.

Chọn tài xế khi Nhận đơn. Hộp thoại có 3 tab:

Tab	Dùng khi
Tài xế sandbox	Mặc định. Tài xế Ahamove cấp sẵn cho kiểm thử, có nhãn Có thể nhận đơn này
Nhập số điện thoại	Giao cho tài xế Staging của nhóm bạn. Tài xế phải được bật dịch vụ của đơn (hoặc của chuyến, với đơn giao gộp), không bị khoá và có thành phố hoạt động
Tài xế gần điểm lấy	Tài xế có dịch vụ này trong bán kính 20 km quanh điểm lấy, đã gửi vị trí trong 7 ngày gần nhất

Với tài xế thật, đơn hiện trên ứng dụng tài xế Staging của họ và tài xế có thể tiếp tục thao tác trên ứng dụng.

Đối chiếu callback

Khu vực Callback tới webhook của bạn: đối chiếu theo thao tác và danh sách callback đã gửi

Callback được gửi bất đồng bộ, có thể đến sau thao tác vài giây. Khu vực này tự cập nhật mỗi 5 giây.

Đối chiếu theo thao tác: mỗi thao tác bạn bấm là một dòng, gồm thời điểm, _id (mã đơn, hoặc MÃĐƠN-i với callback theo điểm), giá trị Mong đợi, mã HTTP và Kết quả:

Kết quả	Nghĩa là
Khớp	Webhook đã nhận callback đúng như mong đợi, trả 2xx
Đang chờ…	Callback chưa tới, đợi thêm vài giây
Webhook trả lỗi	Callback đã gửi nhưng endpoint của bạn trả mã khác 2xx (VD `429`, `503`) hoặc không phản hồi (`0`)
Không gửi	Thao tác này không sinh callback với cấu hình hiện tại (VD `ARRIVED` chưa bật)

Tất cả callback đã gửi: từng lần Ahamove gọi webhook, gồm thời gian, nội dung (VD ACCEPTED, Điểm 1: COMPLETED, COMPLETED · RETURNED), mã HTTP và số lần gửi. Mỗi endpoint đã đăng ký nhận callback riêng, nên khi có 2 webhook bạn sẽ thấy 2 dòng cho cùng một trạng thái.

Xem: mở Chi tiết callback với thời điểm, trạng thái gửi, số lần gửi, tab Yêu cầu (endpoint, header, payload) và Phản hồi (nguyên văn endpoint trả về). Giá trị nhạy cảm như Authorization hay api_key đã được che.
Gửi lại (hoặc Thử lại trong Chi tiết callback): gửi lại đúng nội dung cũ tới endpoint đó ngay bây giờ. Dùng sau khi sửa endpoint.
Mở trong Nhật ký callback: xem các callback của đơn ở Nhật ký callback.

Thử thao tác

Bấm vào ô đang nhấp nháy để làm thử một vòng giao ngay: nhận đơn, lấy hàng, giao thành công rồi xem callback. Ảnh chụp từ đơn mẫu trên Staging.

Chạy một kịch bản

Tạo đơn trên Staging (qua API hoặc Lên đơn)

Muốn thử giao từng điểm thì tạo đơn 2 điểm giao trở lên. Muốn thử hoàn hàng thì cho điểm giao có thu hộ COD.

Mở tab Giả lập đơn hàng, bấm Giả lập ở dòng của đơn

Bấm Nhận đơn, chọn Tài xế sandbox rồi bấm Giao cho tài xế này

Đơn chuyển Tài xế đã nhận; dòng Nhận đơn xuất hiện ở phần đối chiếu.

Bấm lần lượt thao tác ở BƯỚC TIẾP THEO

Ví dụ: Đến nơi → Đã lấy hàng → Giao thành công điểm 1 → Giao thất bại điểm 2. Với Giao thất bại, Tài xế hủy và Bạn hủy đơn, chọn một lý do rồi bấm Xác nhận; lý do này có trong callback.

Sau mỗi thao tác, xem cột Kết quả ở phần đối chiếu

Gặp Webhook trả lỗi thì bấm Xem để đọc phản hồi, sửa endpoint rồi bấm Gửi lại.

Lặp lại với đơn khác cho các hành động còn lại

Bảng Hành động đã kiểm chứng đạt 16/16 khi mọi hành động của Giao ngay và Giao gộp chuyến đều nhận callback 2xx.

Huỷ phải làm trước khi lấy hàng

Nút Tài xế hủy và Bạn hủy đơn chỉ hiện trước bước Đã lấy hàng. Muốn thử cả huỷ lẫn giao hàng, hãy dùng hai đơn khác nhau (Tài xế hủy thì đơn quay về tìm tài xế, nên có thể nhận lại và chạy tiếp trên cùng đơn).

Dữ liệu callback có thông tin bí mật

Payload chứa dữ liệu người nhận, và header có thể chứa thông tin xác thực. Không chụp màn hình hay gửi nguyên văn ra ngoài.

Ai được dùng trang này?

Tạo, thu hồi API key và đổi webhook endpoint cần quyền Thao tác ở trang Tích hợp. Xem Phân quyền.

Quy trình 4 bước tới go-live​

API key​

Tạo API key mới​

Chi tiết key: giới hạn IP và lịch sử sử dụng​

Thu hồi key​

Webhook​

Thêm webhook​

Nhật ký callback​

Kiểm thử​

Gửi yêu cầu go-live​

Danh sách test case​

Giả lập đơn hàng​

Màn hình giả lập một đơn​

Các thao tác tài xế​

Đối chiếu callback​

Thử thao tác​

Chạy một kịch bản​

Ai được dùng trang này?​