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ó 5 tab: Tổng quan · API key · Webhook · Nhật ký callback · Kiểm thử.

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

1. 5 tab của trang Tích hợp
2. Bạn đang ở bước nào
3. Đến tab Kiểm thử
4. Mở tài liệu API
5. API domain: base URL cho mọi request

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.

1. Số key đang hoạt động
2. Tạo API key mới
3. Tên key, ngày hết hạn và cảnh báo IP mới
4. Key chỉ hiện dạng đã che, kèm 4 ký tự cuối
5. Lần cuối key được dùng để lấy token
6. Trạng thái key

Tab API key: danh sách key, ngày tạo, lần lấy token gần nhất và trạng thái

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

1. Tên key: ghi rõ key dùng ở đâu
2. Thời hạn: không hết hạn, 30 ngày, 90 ngày (mặc định) hoặc 1 năm
3. Danh sách IP cho phép: để trống = cho phép mọi IP
4. Tạo key

Hộp thoại Tạo API key mới: tên key, thời hạn và danh sách IP cho phép

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.

1. Quay lại danh sách
2. Thu hồi key
3. Cảnh báo số IP mới trong 30 ngày qua
4. Danh sách IP cho phép: thêm IP rồi bấm Lưu
5. Trạng thái, key đã che, Key ID, ngày tạo, ngày hết hạn
6. Từng IP đã dùng key; IP mới có nhãn Mới

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.

1. Thêm webhook
2. URL endpoint (đã che trong ảnh)
3. Phương thức · kiểu xác thực · thời gian chờ
4. Thời điểm tạo và người tạo
5. Sửa hoặc xoá endpoint

Tab Webhook: danh sách endpoint, phương thức, kiểu xác thực và timeout

• 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.

1. URL endpoint (bắt buộc)
2. Method
3. Timeout (giây)
4. Headers tuỳ chọn: thêm từng cặp Key / Value
5. Loại xác thực (bắt buộc)
6. Sao chép lệnh curl để thử endpoint
7. Preview: request mẫu Ahamove sẽ gửi
8. Lưu

Form Thêm webhook: URL, method, timeout, headers, loại xác thực và preview request

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.

1. Khoảng thời gian: 1 giờ, 24 giờ, 7 ngày, 30 ngày
2. 4 chỉ số tổng hợp
3. Lưu lượng và tỉ lệ lỗi
4. Độ trễ phản hồi so với ngưỡng timeout
5. Lọc theo kết quả, tìm theo mã đơn hoặc tracking

Tab Nhật ký callback: chỉ số, biểu đồ lưu lượng, độ trễ và bảng chi tiết

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.

1. Tổng: đạt · không đạt · chưa chạy
2. Chọn loại hình dịch vụ: Xe máy / Xe tải
3. Nhóm Tạo đơn
4. Nhóm Vòng đời đơn
5. Yêu cầu với đơn và dịch vụ chấp nhận
6. Nhập mã đơn đã tạo rồi bấm Kiểm tra

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.

1. Tổng: đạt · không đạt · chưa chạy
2. Tiến độ test case bắt buộc
3. Gửi yêu cầu Go-live
4. Tải biên bản kiểm thử
5. Nhập mã đơn khác và kiểm tra lại
6. Số tiêu chí khớp và lệch

Tab Kiểm thử khi đã đạt toàn bộ test case bắt buộc: thông báo sẵn sàng go-live và nút Gửi yêu cầu Go-live

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)

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ỷ

Xe tải (5 bắt buộc)

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

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.