Meta Conversion API

• API này dùng để gửi sự kiện Conversion sang Meta, 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.

• 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.

Request

• Xem sample Postman tại đây.

Purchase

• Sự kiện mua hàng thành công.

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 --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 --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 --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

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.

Failed response

• Xem các mã lỗi chung tại đây.

{
    "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

{
    "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