Integrations

The Quản lý tích hợp (Integration management) page is for businesses that want to create orders from their own system through the API. Orders created through the API also appear in Order management.

The page has 5 tabs: Tổng quan (Overview) · API key · Webhook · Nhật ký callback (Callback log) · Kiểm thử (Testing).

4 steps to go-live

1. Send a request→2. Receive a Staging account→3. Integrate and test→4. Go live on Production

1. The 5 tabs of the Integrations page
2. Which step you are on
3. Go to the Kiểm thử (Testing) tab
4. Open the API documentation
5. API domain: base URL for every request

Overview tab: the 4-step process and Staging environment details

Go-live requirement

After integrating on Staging, you must run and pass every required test case in the Kiểm thử (Testing) tab. Ahamove opens your Production account only when every test case is Đạt (Passed). Then click Gửi yêu cầu Go-live (Send go-live request) in the Testing tab.

Staging environment	Value
API domain	https://partner-apistg.ahamove.com
Portal	https://business-stg.ahamove.com
Cost	Sandbox, no charges

Full API documentation: developers.ahamove.com/docs/api-reference.

API key

Keys authenticate server-to-server calls to the Ahamove API.

1. Number of active keys
2. Create a new API key
3. Key name, expiry date and new-IP warning
4. The key is shown masked, with its last 4 characters
5. Last time the key was used to fetch a token
6. Key status

API key tab: list of keys, creation date, last token fetch and status

Column	Meaning
Tên (Name)	The name given to the key, with its expiry date. The IP mới (New IP) label means a new IP address used the key in the last 30 days; see key details
Key	Shown masked only, e.g. sk_test_••••••••Z7MK. You cannot view the full key again on the portal
Ngày tạo (Created)	The date the key was created
Lấy token gần nhất (Last token fetch)	The last time your system used this key. Revoke keys that have not been used for a long time
Trạng thái (Status)	For example Đang hoạt động (Active)

• Staging keys start with sk_test_.
• Keys have an expiry date. Create a new key and put it into your system before that date.

Keep your API keys secret

Regenerate a key as soon as you suspect it has leaked. Never expose a Production key in client-side code, mobile apps or public repositories. A key can create orders and spend money on behalf of your company.

Create a new API key

1. Key name: state clearly where the key is used
2. Validity: never expires, 30 days, 90 days (default) or 1 year
3. Allowed IP list: empty = any IP is allowed
4. Create the key

Create new API key dialog: key name, validity period and allowed IP list

Click + Tạo API key mới (Create new API key)

Enter the Tên key (Key name, required)

State clearly where the key is used, e.g. Order service (production), so you know later which key to revoke.

Choose the Thời hạn (Validity period)

Không hết hạn (Never expires), 30 ngày (30 days), 90 ngày (90 days, default) or 1 năm (1 year).

Restrict by IP (recommended)

Enter the IP address (e.g. 203.0.113.24) or IP range (e.g. 10.0.0.0/16) of the server that calls the API, then click + Thêm IP (Add IP). Leaving it empty means any IP is allowed.

Click Tạo key (Create key) and copy the key right away

The full key is shown only once, right after it is created. Store it somewhere safe immediately (e.g. an environment variable or your server's secret store). If you lose it, create a new key and revoke the old one.

The key appears in the list, masked.

Use a separate key for each system

Give each system (e.g. Order service, Warehouse) its own key with an IP restriction. If one system's key leaks, you only need to revoke that key.

Key details: IP restriction and usage history

Click a key row to open its details page.

1. Back to the list
2. Revoke the key
3. Warning: number of new IPs in the last 30 days
4. Allowed IP list: add IPs, then click Lưu (Save)
5. Status, masked key, Key ID, created date, expiry date
6. Each IP that used the key; new IPs have the Mới (New) label

API key details page: new-IP warning, IP restriction and usage history

IP restriction. Enter an IP or IP range in Danh sách IP cho phép (Allowed IP list), click + Thêm IP (Add IP), then Lưu (Save). Only IPs in the list can use the key. Leaving it empty means any IP is allowed.

Usage history. Lists every IP address that has used the key:

Column	Meaning
Địa chỉ IP (IP address)	The IP that made calls with this key. An IP seen for the first time in the last 30 days has the Mới (New) label
Client	The software calling the API, e.g. PostmanRuntime/2.6.0
Lần đầu / Gần nhất (First / Latest)	When this IP first and most recently used the key
Bị chặn (Blocked)	Number of times the key was rejected because the IP is not in the allowed list
Lần ghi nhận (Times recorded)	Each IP is recorded at most once per minute, so this is not the number of requests. It only helps you tell a one-off IP from a regularly used one

What to do when you see the "IP mới" (New IP) label?

Open the key details and check the IPs labeled Mới (New):

• An IP from your own system (new server, changed network provider…): add that IP to Danh sách IP cho phép (Allowed IP list) so the key can only be used from these IPs.
• An IP you do not recognize: revoke the key immediately and create a new one.

Revoke a key

On the key details page, click Thu hồi key (Revoke key; the red button, top right), then click Thu hồi (Revoke) in the confirmation dialog. Click Huỷ (Cancel) if you change your mind.

A revoked key can no longer be used. Create a new key and update your system to replace it.

Tokens fetched with this key also expire immediately

When you revoke a key, every token fetched with that key also expires immediately, even tokens that have not reached their expiry time. API requests using those tokens will be rejected. Update your system with the new key and fetch new tokens before revoking the old key, so order creation is not interrupted.

If the key has leaked, though, revoke it immediately. Every token fetched with it is invalidated as well.

Webhook

A webhook is an address (endpoint) on your system where Ahamove sends order update events.

1. Add a webhook
2. Endpoint URL (masked in the screenshot)
3. Method · authentication type · timeout
4. Created time and creator
5. Edit or delete the endpoint

Webhook tab: list of endpoints, method, authentication type and timeout

• Each endpoint shows its method (e.g. POST), authentication type (e.g. BASIC-AUTH, API-KEY) and timeout (e.g. 5 seconds).
• You can register multiple endpoints. Ahamove sends events in the order they were registered.
• Your endpoint must respond with a 2xx code before the timeout; otherwise the delivery counts as failed. See the Callback log.
• Click the pen icon to edit, or the trash icon to delete.

Add a webhook

Click + Thêm webhook (Add webhook) to open the form.

1. Endpoint URL (required)
2. Method
3. Timeout (seconds)
4. Optional headers: add Key / Value pairs one by one
5. Authentication type (required)
6. Copy the curl command to test the endpoint
7. Preview: sample request Ahamove will send
8. Lưu (Save)

Add webhook form: URL, method, timeout, headers, authentication type and request preview

Field	Value
URL *	Your endpoint address, e.g. https://partner.example.com/callback
Method	GET, POST (default), PUT, PATCH, DELETE
Timeout (giây) (Timeout, seconds)	Maximum time to wait for your endpoint to respond. Default 5
Headers tuỳ chọn (Optional headers)	Headers added to every request. Click + Thêm header (Add header) to add a row
Loại xác thực (Authentication type) *	How Ahamove authenticates with your endpoint; see the table below

Authentication type	Required fields
NONE	No extra authentication (default)
API-KEY	Header name *, Scheme (optional), Token *
BEARER-TOKEN	Token *
BASIC-AUTH	Username *, Password *

The Preview section shows the sample request that will be sent: the endpoint, headers (Content-Type: application/json) and the JSON body of an order event. Click Sao chép curl (Copy curl) to send this request to your endpoint yourself and check that it returns 2xx before saving.

Use authentication

Choose API-KEY, BEARER-TOKEN or BASIC-AUTH so your endpoint only accepts requests from Ahamove. Use NONE only for testing.

Callback log

Track each time Ahamove calls your webhook to troubleshoot your integration.

1. Time range: 1 hour, 24 hours, 7 days, 30 days
2. 4 summary metrics
3. Traffic and error rate
4. Response latency compared with the timeout threshold
5. Filter by result, search by order ID or tracking code

Callback log tab: metrics, traffic chart, latency and detail table

Section	Contains
Chỉ số (Metrics)	Total callbacks (with the number succeeded) · Delivery rate · p95 latency (with p50) · Failed callbacks
Lưu lượng và tỉ lệ lỗi (Traffic and error rate)	Callbacks over time, split into Đã nhận (Received) / Chưa tới nơi (Not delivered), with an error-rate line
Độ trễ phản hồi (Response latency)	p95 and p50 compared with the timeout threshold (e.g. 5.0 seconds)
Bảng chi tiết (Detail table)	Time · Order · Sent status · Result · Latency. Filter by Kết quả (Result), search by order ID or tracking code

Reading the detail table:

• Đơn hàng (Order): the Ahamove order ID, with your internal ID below it (if any).
• Trạng thái gửi (Sent status): the order status in the event, e.g. CANCELLED.
• Kết quả (Result): the HTTP code your endpoint returned. 200 means received successfully; any other code (e.g. 429) is a failure.
• Click the eye icon at the end of a row to see the details of that call.

Many failed callbacks?

Check that your endpoint returns 2xx fast enough. If the p95 latency is close to the timeout threshold, make your endpoint return 2xx immediately and process the event afterwards (asynchronously).

Testing

The set of required test cases you must pass before Production is opened.

Staging only

The Kiểm thử (Testing) tab only supports the Staging environment for trial runs of your integration. Orders created for testing are sandbox orders and incur no charges.

For each case, you create a real order on Staging that matches the requirements, then enter the order ID so the system can check it.

1. Totals: passed · failed · not run
2. Choose the service type: Xe máy (Motorbike) / Xe tải (Truck)
3. Tạo đơn (Create order) group
4. Vòng đời đơn (Order lifecycle) group
5. Order requirements and accepted services
6. Enter the created order ID, then click Kiểm tra (Check)

Testing tab: list of test cases for the motorbike (Xe máy) service type and details of one case

Choose the service type (Xe máy / Motorbike or Xe tải / Truck)

Choose a test case in the left column

Read Yêu cầu với đơn (Order requirements) and Dịch vụ chấp nhận (Accepted services) (e.g. SGN-BIKE, SGN-TRUCK-500).

Create an order on Staging through the API, matching the requirements

Enter the order ID in the box on the right and click Kiểm tra (Check)

The case changes to Đạt (Passed) or Không đạt (Failed); the system checks each criterion (4–5 criteria per case).

When all required test cases pass, click Gửi yêu cầu Go-live (Send go-live request)

See Send a go-live request below.

Send a go-live request

When every required test case for the selected service type is Đạt (Passed), a green message appears above the list: Đã đạt toàn bộ … test case bắt buộc — sẵn sàng go-live Production (All … required test cases passed — ready to go live on Production).

1. Totals: passed · failed · not run
2. Progress on required test cases
3. Gửi yêu cầu Go-live (Send go-live request)
4. Tải biên bản kiểm thử (Download test report)
5. Enter another order ID and check again
6. Number of matching and mismatching criteria

Testing tab with all required test cases passed: ready-to-go-live message and the Gửi yêu cầu Go-live (Send go-live request) button

Click Gửi yêu cầu Go-live (Send go-live request)

The request is sent immediately, with no confirmation step. The test report is attached to the email.

Wait for Ahamove to contact you

The message changes to Đã gửi yêu cầu lúc [time] (Request sent at [time]). The operations team will review your contract and COD limit, then activate your Production account.

• Click Tải biên bản kiểm thử (Download test report) to save a copy of the test results for your records.
• After sending, the button changes to Gửi lại yêu cầu (Resend request) in case you need to send it again.
• No green message? Some required case is still Không đạt (Failed) or Chưa chạy (Not run). Open that case, look at the lệch (mismatch) rows in the Đối chiếu tiêu chí (Criteria check) table, create a new order that matches the requirements, then click Kiểm tra lại (Check again).

Test case list

Xe máy / Motorbike (8 required)

Group	Code	Test case
Create order	TC-A1	1 drop-off point, deliver now, paid from the partner wallet (payment_method = BALANCE, order_time = 0)
Create order	TC-A2	2 drop-off points with COD, sender pays the fee
Create order	TC-A4	Motorbike order with add-on services (TIP, BULKY)
Create order	TC-A6	Scheduled order
Create order	TC-A7	Look up an order by the partner's internal ID
Order lifecycle	TC-B1-BIKE	Order delivered successfully, full status sequence
Order lifecycle	TC-B2-BIKE	Delivery fails at one point, goods returned to the sender
Order lifecycle	TC-B3-BIKE	Partner cancels the order before a driver accepts
Order lifecycle	TC-B4-BIKE	Driver search times out, the system cancels automatically

Xe tải / Truck (5 required)

Group	Code	Test case
Create order	TC-A3	Multi-point truck order, route optimization, with package dimensions (1 pickup point + 3 drop-off points)
Create order	TC-A5	Truck order with loading/unloading and waiting fee
Order lifecycle	TC-B1-TRUCK	Order delivered successfully, full status sequence
Order lifecycle	TC-B2-TRUCK	Delivery fails at one point, goods returned to the sender
Order lifecycle	TC-B3-TRUCK	Partner cancels the order before a driver accepts
Order lifecycle	TC-B4-TRUCK	Driver search times out, the system cancels automatically

Truck (Xe tải) test cases: TC-A3 multi-point order with route optimization

Who can use this page?

Creating or revoking API keys and changing webhook endpoints requires the Thao tác (Manage) permission on the Integrations page. See Roles & permissions.