# Meta Conversion API * API này dùng để gửi sự kiện Conversion sang Meta (hỗ trợ Facebook và Instagram), giúp Meta có dữ liệu tối ưu quảng cáo tốt hơn. * Xem báo cáo và lịch sử gửi Meta conversion API trên Vpage [tại đây](https://vpage.nhanh.vn/app/report/facebook/metacapi). * **Chú ý**: * Nếu bạn tạo đơn hàng ở Vpage, thì Vpage đã tự động bắn Conversion API lên Facebook rồi, chú ý không gọi API này nữa tránh trùng doanh thu CAPI. * Nếu bạn không dùng Nhanh POS, bạn có thể nhúng khung tạo đơn hàng ở bên phải Vpage bằng 1 iframe riêng để nhận các param cần thiết cho việc tạo đơn hàng. Đọc tài liệu [cài đặt Order Iframe](https://github.com/nvndocs/docs-pos-openapi/blob/v3/docs/vpage/conversation/order_iframe.md). ## Request * Xem sample Postman [tại đây](https://www.postman.com/nhanh-vn/vpage-open-nhanh-vn/request/rodpu1s/meta-send-conversions-api?tab=body). ### Purchase * Sự kiện mua hàng thành công. ```curl curl --location 'https://vpage.open.nhanh.vn/v3.0/marketing/metasendcapi?appId={{appId}}&businessId={{businessId}}' \ --header 'Authorization: {{accessToken}}' \ --header 'Content-Type: application/json' \ --data '{ "eventName": "Purchase", "conversationId": "101286204573840_6289022961168486", "orderInfo": { "orderId": "14889002", "eventId": "14889002", "orderValue": 5650000, "shippingFee": 5000, "customerPhone": "0329927799", "products": [ { "id": "1231268761", "quantity": 1, "price": 4600000, "itemGroupId": "group_1231268761", "title": "polo nam Nhanh", "description": "Material: Bird'\''s eyeComposition: 49% Cotton + 47% Polyester + 4% SpandexSolid Dyed technology creates eye-catching effects.\n", "additionalImageLink": [] }, { "id": "1231269211", "quantity": 1, "price": 350000, "itemGroupId": "group_1231269191", "title": "Mũ vải", "description": "Đây là mô tả mũ chất lượng cao, kháng tia UV an toàn tuyệt đối - description\n", "additionalImageLink": { "images": [ "https://poscdn.nvndev.net/a7df54-35102/ps/20240809_7WLD5ZDLDR.jpeg", "https://poscdn.nvndev.net/a7df54-35102/ps/20250224_HBgCCl0bZr.jpeg", "https://poscdn.nvndev.net/a7df54-35102/ps/20250224_yV0nDjeK8Z.jpeg", "https://poscdn.nvndev.net/a7df54-35102/ps/20250224_Dh5PEg0hav.jpeg" ] } } ] } } ' ``` ### Lead Submitted * Sự kiện báo khách hàng tiềm năng. ```curl curl --location 'https://vpage.open.nhanh.vn/v3.0/marketing/metasendcapi?appId={{appId}}&businessId={{businessId}}' \ --header 'Authorization: {{accessToken}}' \ --header 'Content-Type: application/json' \ --data '{ "eventName": "LeadSubmitted", "conversationId": "101286204573840_6289022961168486", "orderInfo": {} } ' ``` ### Order Canceled * Sự kiện hủy đơn hàng. ```curl curl --location 'https://vpage.open.nhanh.vn/v3.0/marketing/metasendcapi?appId={{appId}}&businessId={{businessId}}' \ --header 'Authorization: {{accessToken}}' \ --header 'Content-Type: application/json' \ --data '{ "eventName": "OrderCanceled", "conversationId": "101286204573840_6289022961168486", "orderInfo": { "orderId": "14889002", "eventId": "14889002", "orderValue": 5650000, "shippingFee": 5000, "customerPhone": "0329927799" } } ' ``` ### Order Returned * Sự kiện đơn hàng bị trả lại. ```curl curl --location 'https://vpage.open.nhanh.vn/v3.0/marketing/metasendcapi?appId={{appId}}&businessId={{businessId}}' \ --header 'Authorization: {{accessToken}}' \ --header 'Content-Type: application/json' \ --data '{ "eventName": "OrderReturned", "conversationId": "101286204573840_6289022961168486", "orderInfo": { "orderId": "14889002", "eventId": "14889002", "orderValue": 5650000, "shippingFee": 5000, "customerPhone": "0329927799", "products": [] } } ' ``` ### data | Key | Type | Description | | -------------- | ------ | ----------------------------------------------------------------- | | eventName | string | eventName (Purchase, LeadSubmitted, OrderCanceled, OrderReturned) | | conversationId | string | ID hội thoại | | orderInfo | array | Data cần để bắn sang Meta và thống kê báo cáo của Vpage | #### order\_info | Trường (`order_info`) | `Purchase` | `OrderCanceled` | `OrderReturned` | `LeadSubmitted` | | --------------------- | ----------- | --------------- | --------------- | --------------- | | `orderId` | ✅ require | ✅ require | ✅ require | ❌ — | | `eventId` | ❌ — | ❌ — | ❌ — | ⚠️ optional | | `currency` | ⚠️ optional | ⚠️ optional | ⚠️ optional | ❌ — | | `orderValue` | ✅ require | ✅ require | ✅ require | ❌ — | | `shippingFee` | ✅ require | ✅ require | ✅ require | ❌ — | | `products` | ✅ require | ⚠️ optional | ⚠️ optional | ❌ — | | `customerPhone` | ⚠️ optional | ❌ — | ❌ — | ❌ — | * Chú ý: * `eventId` : Id duy nhất của sự kiện. Đối vợi sự kiện Purchase, id có thể giống nhau. Nhưng Meta sẽ sử dụng id này để loại bỏ trùng lặp giữa các sự kiện. Hãy cố gắng chỉ gửi 1 lần cho mỗi id * đối với các sự kiện Purchase, OrderCanceled, OrderReturned: `eventId` chính bằng `orderId`. * đối với sự kiện `LeadSubmitted` bạn không cần truyền `eventId` nếu chỉ muốn gửi sự kiện này tối đa 1 lần 1 ngày, chúng tôi sẽ tạo tự động. * `currency`: đơn vị tiền tệ. không truyền mặc định là `VND` . Tham khảo đơn vị tiền tệ [tại đây](https://developers.facebook.com/docs/marketing-api/currencies?locale=vi_VN) **`products`** | Key | Type | Description | | -------------------------- | ------ | -------------------------------- | | id | string | ID sản phẩm | | quantity | int | Số lượng | | price | int | Giá sản phẩm | | itemGroupId | string | groupId của sản phẩm | | title | string | Tên sản phẩm | | description | string | Mô tả sản phẩm | | additionalImageLink | array | | | additionalImageLink.images | array | URL hình ảnh hợp lệ của sản phẩm | ## Response * Xem cấu trúc chung [tại đây](https://apidocs.nhanh.vn/v3/readme#response). ### Failed response * Xem các mã lỗi chung [tại đây](https://apidocs.nhanh.vn/v3/readme#failed-response). ```json { "code": 0, "messages": { "conversationId": "Invalid conversationId." }, "errorCode": "ERR_INVALID_FORM_FIELDS" } ``` * Các mã lỗi thường gặp của API này: | errorCode | Description | | --------------------- | ---------------------------------------------------------------------------------------- | | ERR\_CAPI\_DISABLED | Facebook page chưa bật kết nối Conversion API, bạn cần truy cập Vpage để bật cài đặt này | | ERR\_MISSING\_DATASET | Facebook page chưa kết nối dataset, bạn cần truy cập vào Vpage để kết nối lại dataset | ### Successful response ```json { "logId": "RpdCeJgBIf1HgkjzBjxb", "events_received": 1, "messages": [], "fbtrace_id": "A97S_q39IG7_aeq1SE6SnOS" } ``` * Giải thích: * `logId`: log của Vpage. Bạn có thể gửi để Vpage hỗ trợ debug trong tình huống bị lỗi * các dữ liệu còn lại là data Meta response