Cài đặt

Webhooks giúp bạn đăng kí lắng nghe các sự kiện phát sinh từ hệ thống của Nhanh.vn, VD:
- Khi có đơn hàng mới, khi đơn gửi sang hãng vận chuyển, khi đơn hàng thay đổi trạng thái.
- Khi có sản phẩm mới, khi có cập nhật sản phẩm, khi xóa sản phẩm.
- Khi có hóa đơn bán hàng mới.
- Khi có phiếu bảo hành mới.

Bật webhooks

Vào danh sách ứng dụng, click vào tên ứng dụng để vào trang chi tiết.
Click sửa ứng dụng, kéo xuống mục webhooks:
- Tích chọn Bật webhooks.
- Chọn Webhooks version: 3.0
- Điền Webhooks callback URL (bắt buộc chạy https và response http code = 200 và hỗ trợ POST method).
- Điền Webhooks verify token (giá trị này do bạn tự điền, Nhanh API sẽ gửi kèm header webhooks-verify-token khi bắn webhooks để bạn có thể xác minh dữ liệu là từ Nhanh API bắn sang).
- Chọn các sự kiện muốn đăng kí nhận webhooks và nhấn Lưu.

Chú ý: Bạn chỉ nên bật webhooks và điền Webhooks callback URL khi bạn đã có link này, không để link liên tục ở tình trạng lỗi (301, 302, 403, 404, 500...) để tránh bị tắt webhooks hoặc khóa app.

Nhanh API sẽ gửi request webhooksEnabled tới Webhooks callback URL của bạn để kiểm tra xem URL này có hoạt động hay không.

curl --location --request POST 'https://webhook.site/a1f7177c-f622-4570-b420-ddf79f3b83e9' \
--header 'Content-Type: application/json' \
--header 'webhooks-verify-token: APP_WEBHOOKS_VERIFY_TOKEN' \
--data-raw '{
    "event": "webhooksEnabled"
}'

Nhận webhooks

Với mỗi sự kiện Nhanh API sẽ gửi sang 1 request:
- Method: POST
- Header 'Content type: application/json' và 'webhooks-verify-token: APP_WEBHOOKS_VERIFY_TOKEN'.
- Request body là json string.

Webhooks data

VD về sự kiện khi có đơn hàng mới

curl --location --request POST 'https://webhook.site/a1f7177c-f622-4570-b420-ddf79f3b83e9' \
--header 'Content-Type: application/json' \
--header 'webhooks-verify-token: APP_WEBHOOKS_VERIFY_TOKEN' \
--data-raw '{
    "event": "orderAdd",
    "businessId": 64692,
    "data": {
        "customer": {
			"id": 123,
			"name": "Customer name"
		},
        "products": [
        	{ },
			{ }
        ]
    }
}'

businessId: (bigint) ID doanh nghiệp trên nhanh.vn, dùng khi ứng dụng của bạn tích hợp cho nhiều doanh nghiệp, thì businessId giúp phân biệt dữ liệu của doanh nghiệp nào.
data: (json string) Dữ liệu của sự kiện này.
event: (string) Tên sự kiện. Xem thêm bảng bên dưới:

Event

Description

webhooksEnabled

Sự kiện khi bạn bật webhooks hoặc NhanhAPI kiểm tra webhooks của bạn có còn hoạt động hay không (thường dùng khi tỉ lệ phản hồi response webhooks của bạn có tỉ lệ thành công thấp)

productAdd

Thêm sản phẩm mới

productUpdate

Cập nhật sản phẩm

productDelete

Xóa sản phẩm

inventoryChange

Thay đổi tồn kho của sản phẩm

orderAdd

Thêm đơn hàng mới

orderUpdate

Cập nhật đơn hàng

orderDelete

Xóa đơn hàng

paymentReceived

Đơn hàng hoặc hóa đơn bán hàng (bán lẻ, bán sỉ) nhận được thanh toán từ MoMo hoặc chuyển khoản ngân hàng

Webhooks response

Hệ thống của bạn cần response http code 200 để NhanhAPI xác nhận bạn đã xử lý thành công.
Nếu hệ thống của bạn không phản hồi quá chậm, hoặc http code != 200, webhooks sẽ được bắn lại tối đa 3 lần.
- Khi app của bạn xử lý webhooks chậm hoặc hay lỗi, Nhanh.vn sẽ đẩy độ ưu tiên cho app của bạn xuống thấp, các request webhooks tiếp theo có thể sẽ bị delay.
- Khuyến cáo bạn nên lưu webhooks và response cho Nhanh.vn trước, rồi tạo cronjob xử lý webhooks sau.
Nếu hệ thống của bạn xử lý webhooks với tỉ lệ thành công thấp, tùy mức độ, NhanhAPI sẽ có thể:
- Gọi lại sự kiện webhooksEnabled để kiểm tra link webhooks của bạn có hoạt động hay không.
- Tắt webhooks của app: Bạn cần làm lại các bước bật webhooks như đã mô tả ở trên để mở lại webhooks.
- Khóa app: Bạn cần liên hệ email [email protected] để được hỗ trợ mở lại app.

Lỗi thường gặp

Khi nhận webhooks từ NhanhAPI bắn sang, bạn có thể gặp phải các tình huống lỗi, xem chi tiết lỗi và cách khắc phục bên dưới:

Chú ý: Webhooks sẽ chỉ bắn với các dữ liệu mới, các dữ liệu quá khứ (phát sinh trước thời điểm app được cấp quyền hoặc bật webhooks) sẽ không có sự kiện bắn lại.

App chưa được cấp quyền

Khi bạn bật được webhooks lên và nhận được sự kiện webhooksEnabled, đây chỉ là webhooks test của hệ thống.
Để nhận được webhooks của doanh nghiệp, thì app của bạn cần được 1 tài khoản thuộc doanh nghiệp đó đăng nhập cấp quyền cho ứng dụng của bạn và bạn cần lấy được accessToken. Xem các bước khởi tạo ứng dụng và đăng nhập cấp quyền tại đây.
Ở các trang như chi tiết đơn hàng, chi tiết sản phẩm... sẽ có 1 tab API lưu lại tất cả lịch sử nhận API request và gửi webhooks, xin vui lòng kiểm tra kĩ dữ liệu trước khi báo lỗi. VD bạn có thể tạo 1 đơn hàng mới, hoặc cập nhật trạng thái đơn hàng, sau đó xem trang chi tiết đơn hàng sẽ có 1 tab API, bạn có thể xem nội dung webhooks Nhanh bắn sang cho app của bạn.

Connection timed out

Lỗi này có thể do nhiều nguyên nhân:
- Tên miền không hoạt động.
- Server của bạn bị lỗi hoặc phản hồi quá chậm.
- Firewall của bạn chặn các request từ Nhanh API.

Redirects 301 302

Lỗi thường gặp khi Webhooks callback URL của bạn response 301, 302 điều hướng sang 1 URL khác. VD URL yêu cầu login, và có thể khi bạn test, bạn đã login vào URL này, nên không phát hiện ra lỗi.
Khi bạn test bằng Postman, mặc định Postman sẽ bật Automatically follow redirects, bạn cần tắt cài đặt này đi, nếu không khi tự test sẽ thấy http code trả về 200 nhưng thực tế đang trả về 301 / 302. Có 2 cách tắt:
Cách 1: Tắt cho toàn bộ request: Vào menu File > Settings > Tắt: Automatically follow redirects

Cách 2: Tắt từng tab request: chọn Settings và tắt Automatically follow redirects

Wordpress plugin Wordfence

Nếu bạn dùng Wordpress và có cài plugin Wordfence thì có thể bị lỗi trả về http code 503 và không bật được webhooks hoặc nhận webhooks từ Nhanh.vn bắn sang bị chập chờn.
Cách khắc phục: Gỡ plugin này khỏi Wordpress.

Lỗi mất webhooks

Tình huống: Trước đó bạn đã cài đặt và sử dụng webhooks bình thường, sau đó webhooks ngừng bắn hoàn toàn.
Nguyên nhân: Lỗi này thường là do app đã bị doanh nghiệp gỡ, hoặc accessToken đã hết hạn.
Cách kiểm tra: Doanh nghiệp có thể vào Nhanh.vn, mục Cài đặt > Cài đặt chung > Cài đặt Open API để kiểm tra xem có còn kết nối với appId không. Nếu không còn, bạn có thể hướng dẫn doanh nghiệp thực hiện lại việc đăng nhập cấp quyền.
Chú ý: accessToken chỉ có hạn sử dụng 1 năm, khi gần hết hạn, bạn nên báo doanh nghiệp cấp quyền để lấy accessToken mới.

PreviousMeta Conversion API NextApp

Last updated 19 days ago