Tham khảo
Cấu trúc payload chính xác, mã phản hồi và ví dụ copy-paste của endpoint nhận dữ liệu.
Mọi lead vào Averosi đều qua một endpoint duy nhất: webhook có token riêng của workspace. Trang này mô tả chính xác URL cần dùng, các field payload mà Averosi hiểu được, và ý nghĩa từng mã phản hồi — để bạn gắn nó vào bất kỳ nền tảng form, landing page, hay cửa hàng nào đang dùng.
Webhook của workspace nằm ở POST /api/hooks/<token> — token được tạo riêng cho từng ingest endpoint và hiển thị ở trang Nguồn chuyển đổi. Dán URL này vào phần cài đặt webhook của nền tảng form/landing page/cửa hàng bạn đang dùng — hầu hết các nền tảng phổ biến ở VN (LadiPage, Pancake, Haravan, Sapo, Woo…) đều hỗ trợ. Handler chỉ nhận POST; GET trả về hướng dẫn thay vì payload.
Gửi body JSON với header Content-Type: application/json. Endpoint giữ nguyên toàn bộ body dưới dạng raw rồi dùng cấu hình attribution của endpoint để trích các field cụ thể theo đường dẫn — nên payload cố tình được thiết kế lỏng lẻo. Bảng dưới là cấu trúc mặc định (đúng với cấu hình attribution được seed sẵn và lead test có sẵn trong app); tên field từ form/cửa hàng của bạn vẫn dùng được miễn là extraction rules trỏ đúng vào chúng.
| Field | Mô tả |
|---|---|
| event_type | string, tùy chọn. Nhãn tự do cho nguồn sự kiện, ví dụ "form_submission". Không kiểm tra theo enum — chỉ lưu lại. |
| timestamp | string (ISO 8601 datetime), tùy chọn. Dùng làm occurred_at của event. Nếu bỏ trống, Averosi dùng thời điểm server nhận request. |
| query_params.gclid | string, tùy chọn nhưng là mấu chốt của attribution. Google Ads click ID lấy từ URL trang đích. |
| query_params.utm_source / utm_medium / utm_campaign / utm_term / utm_content | string, tùy chọn. Các tham số UTM chuẩn, được cấu hình attribution mặc định trích riêng từng field. |
| user.email | string, tùy chọn. Dùng làm định danh lead mặc định và cho việc dedupe/idempotency. |
| user.name / user.phone | string, tùy chọn. Được giữ nguyên trong raw payload; các đích đến (HubSpot, Sheets...) đọc field này nếu được cấu hình. |
| … field khác | Bất kỳ field bổ sung nào cũng được chấp nhận và lưu nguyên văn dưới raw — schema envelope dùng validator kiểu passthrough nên field thừa không làm fail validation. |
Thực ra không có gì bắt buộc
Quy tắc duy nhất được schema ép buộc là: JSON hợp lệ, và nếu gửi timestamp thì phải đúng định dạng ISO datetime. Mọi thứ khác — kể cả gclid và user.email — đều tùy chọn ở tầng HTTP. Chất lượng attribution phụ thuộc vào những gì bạn thực sự gửi, nhưng endpoint sẽ không từ chối lead vì thiếu field.
| Mã | Ý nghĩa |
|---|---|
| 200 | Thành công. Body: { ok: true, event_id, type, enqueued }. Gửi trùng (cùng dedupe key) cũng trả 200 với { ok: true, deduped: true }. |
| 400 | Body không phải JSON hợp lệ. |
| 404 | Token không khớp với ingest endpoint đang active. |
| 422 | Envelope không qua được validation schema (sai định dạng timestamp) — body kèm issues từ Zod — hoặc endpoint chưa có attribution config, hoặc config thiếu/không active. |
| 503 | Deployment chưa cấu hình Supabase (thiếu biến môi trường). |
Giữ gclid/UTM xuyên suốt trước khi submit
Nếu form không nằm ngay trên trang landing, hãy đảm bảo nền tảng của bạn lưu gclid và UTM vào cookie hoặc hidden field ngay khi khách vào trang, để chúng còn nguyên qua các lần điều hướng trước khi form được submit. Xem Nguồn chuyển đổi để biết Averosi biến các field thô này thành mô hình channel/source ra sao.
Để khép vòng lead → doanh thu, POST đơn tới <APP_URL>/api/orders/<token> (cùng token workspace). Averosi tự nối mỗi đơn về lead gốc theo gclid → email → phone, nên đơn thừa hưởng đúng quảng cáo tạo ra nó. Các field đọc linh hoạt:
value / amount / total / total_priceemail, phone (hoặc lồng customer.email/phone)gclid (top-level, query_params.gclid, hoặc note_attributes kiểu Shopify)order_id / id / order_number (chống trùng)Đơn khớp sẽ hiện thành doanh thu trên lead ở trang Leads.
lead_created chuẩn hóa.Vẫn chưa giải quyết được?
Nếu tài liệu chưa đề cập, hãy mở trang Hỗ trợ.