Kết nối hệ thống bằng API và webhook
7 bước7 phút đọc
Dành cho lập trình viên kết nối cửa hàng, ERP hoặc WMS. Bạn cần chủ tài khoản, hoặc thành viên có quyền Nhà phát triển, tạo key, và một địa chỉ HTTPS công khai để nhận webhook.
Trong hướng dẫn này
Bước 1: Tạo API key
Trong Cài đặt → API key, đặt tên cho key (nơi sẽ dùng nó) và bấm Tạo key. Sao chép ngay: key chỉ hiện một lần. Gửi kèm key trong mọi request dưới dạng Authorization: Bearer <key>.
Bước 2: Thử trước khi viết code
Bấm Thử key này và gửi một request có sẵn (kiểm tra key, đơn hôm nay, tạo một đơn thử rồi đọc lại) hoặc request của riêng bạn. Bạn thấy câu trả lời, mã trạng thái và thời gian, kèm lệnh curl để sao chép. Tải bộ Postman làm riêng cho công ty bạn và mở nhật ký request API để xem mọi lần gọi trong 3 ngày qua.
Mẹo: Đặt mã đơn thử bắt đầu bằng API-TEST-: các đơn này không bao giờ được lập tuyến hay nhắn tin, không tính vào đâu cả và bị xóa sau 3 ngày.
Bước 3: Đọc tài liệu tham chiếu
API nằm ở địa chỉ Afi Planner của bạn, dưới /api/v1. Bản mô tả đầy đủ ở /api/v1/openapi.json (OpenAPI 3.1), hầu hết công cụ đều nhập được để sinh client.
Bước 4: Gửi đơn
POST /api/v1/orders với mã đơn của bạn trong ref, ngày giao, địa chỉ (hoặc vĩ độ và kinh độ), khung giờ, số kiện và trọng lượng. Một ref chỉ một đơn đang mở trên mọi ngày: gửi lại ref sẽ cập nhật đơn đó và giữ nguyên ngày của đơn (ref có đơn giao thất bại trong 14 ngày qua sẽ thành lần giao tiếp theo, cùng link theo dõi), cho đến khi tài xế đã làm đơn: lúc đó phản hồi là 409 order_worked kèm id của đơn, và PATCH /api/v1/orders/{id} dùng để sửa các trường của đơn. Dùng /api/v1/orders/batch để gửi tới 1.000 đơn một lần; kế hoạch của một ngày vẫn chứa tối đa số điểm giao mỗi kế hoạch của gói (500 với bản dùng thử miễn phí), và lô có nhiều đơn mới hơn chỗ còn lại bị từ chối toàn bộ.
Mẹo: Thêm header Idempotency-Key vào các request POST: nếu một request được gửi lại sau lỗi mạng, bạn nhận lại phản hồi đầu tiên thay vì hệ thống thực hiện thêm một lần nữa.
Bước 5: Lập tuyến và điều phối
Chọn tài xế trong ngày bằng PUT /api/v1/days/{day}/drivers, bắt đầu lập tuyến bằng POST /api/v1/days/{day}/optimize, theo dõi job bằng GET /api/v1/jobs/{id}, rồi gửi tuyến bằng POST /api/v1/days/{day}/dispatch. Điều phối viên vẫn có thể chỉnh tuyến trong ứng dụng. Dữ liệu đọc ra luôn là tuyến đúng như đã gửi cho tài xế, giống điều khách của bạn thấy; khi bảng tuyến của điều phối viên khác với bản đã gửi, đơn có thêm draftRoute và kế hoạch của ngày có thêm draft. Nếu điều phối viên chia một ngày thành nhiều kế hoạch trong ứng dụng, đơn mới và các endpoint theo ngày này dùng kế hoạch đầu tiên của ngày.
Bước 6: Thêm webhook
Trong Cài đặt → API key, thêm endpoint HTTPS của bạn và chọn các sự kiện. Sao chép signing secret, rồi bấm Gửi thử: kết quả và mọi lần gửi sau đó đều hiện trong nhật ký, kèm payload, header và câu trả lời của máy chủ bạn, cùng nút Gửi lại.
Bước 7: Xác thực từng sự kiện
Mỗi request mang header Afi-Signature: t=<time>,v1=<signature>. Tính HMAC-SHA256 của “t.body” bằng secret của bạn, so sánh với v1, và từ chối sự kiện cũ hơn năm phút. Trả về mã 2xx trong vòng 10 giây rồi mới xử lý; lần gửi không thành công được thử lại trong khoảng một ngày. Sự kiện phát sinh khi endpoint đang tắt không được giữ lại cho nó: sau khi bật lại, hãy đọc lại đơn bằng GET /api/v1/orders?day=.
Nhà phát triển
Hướng dẫn tích hợp API: từng bước kèm ví dụ curl →
Tính năng liên quan
Kết nối hệ thống theo hai chiều →