Cách thiết lập API Chuyển đổi cho Meta, Google, TikTok bằng Orova

Bạn đã chạy quảng cáo Meta, Google hay TikTok một thời gian và nhận ra một sự thật khó chịu: dữ liệu chuyển đổi mà nền tảng quảng cáo nhìn thấy không giống với những gì thực sự xảy ra trong CRM của bạn. Một khách điền form trên web, nhưng họ chỉ thực sự trở thành đơn hàng sau ba cuộc gọi của sale và hai ngày suy nghĩ. Pixel đặt trên website không bao giờ biết điều đó. Hệ quả là thuật toán đấu thầu tối ưu sai mục tiêu, ngân sách chảy về nhóm khách điền form cho vui thay vì nhóm khách thật sự xuống tiền.

API Chuyển đổi (Conversion API) sinh ra để vá đúng khoảng trống này. Thay vì dựa vào pixel trình duyệt vốn dễ bị chặn bởi trình duyệt, tiện ích chặn quảng cáo và giới hạn cookie, bạn gửi sự kiện chuyển đổi trực tiếp từ máy chủ — từ chính CRM nơi cất giữ sự thật về đơn hàng. Bài viết này hướng dẫn bạn thiết lập API Chuyển đổi cho cả ba nền tảng Meta, Google và TikTok bằng Orova, từ con số không cho tới lúc nhật ký báo "sent" và quảng cáo của bạn bắt đầu học đúng đối tượng.

Nếu bạn chưa nắm rõ khái niệm và lý do nên dùng, hãy đọc bài trụ API Chuyển đổi là gì và vì sao quảng cáo 2026 không thể thiếu trước. Bài này tập trung 100% vào phần thực hành: bấm ở đâu, gửi gì, đọc nhật ký ra sao.

Hiểu mô hình trước khi bấm nút

Orova không thay thế pixel hay tài khoản quảng cáo của bạn. Nó đứng ở giữa như một bưu cục: nhận sự kiện từ CRM, làm sạch và băm dữ liệu nhạy cảm, rồi chuyển đúng định dạng tới đích bạn chỉ định. Có ba điều cốt lõi bạn cần khắc trong đầu trước khi đi tiếp.

Thứ nhất, mỗi dự án có một webhook riêng. Đây là một URL bí mật dạng orova.vn/hooks/ads/{slug}/{token}. CRM hoặc website của bạn gửi một yêu cầu POST tới URL này mỗi khi phát sinh lead hay đơn hàng. Phần {slug} là định danh dự án, {token} là chuỗi ngẫu nhiên — ai có URL này coi như có chìa khoá gửi dữ liệu, nên hãy giữ kín như mật khẩu.

Thứ hai, Orova không tạo pixel hay tệp đối tượng cho bạn. Bạn phải có sẵn các thứ đó trong tài khoản quảng cáo. Orova chỉ làm một việc: gửi dữ liệu vào cái bạn đã chọn. Với Meta là Pixel, với Google là một Conversion Action, với TikTok là Pixel; ngoài ra có thể chọn thêm Custom Audience hoặc Customer Match nếu bạn muốn đồng bộ danh sách khách.

Thứ ba, mỗi nền tảng có hai công tắc độc lập. Một là Gửi chuyển đổi — đẩy sự kiện về pixel để thuật toán tối ưu thầu. Hai là Đồng bộ đối tượng — đẩy email/số điện thoại (đã băm) vào một tệp khách hàng, để bạn loại trừ người đã mua khỏi quảng cáo, hoặc dùng làm nền tạo Lookalike. Hai công tắc này bật tắt riêng cho từng nền tảng, không ràng buộc nhau.

Bước 1 — Chuẩn bị: pixel và đối tượng phải có sẵn

Vì Orova chỉ gửi vào đích có sẵn, việc chuẩn bị là điều kiện bắt buộc. Đừng bỏ qua bước này, nếu không bạn sẽ tới phần chọn đích và thấy danh sách trống rỗng.

• Meta: Bạn cần một Pixel (Dataset) đã tạo trong Business Manager. Nếu muốn đồng bộ đối tượng, hãy tạo sẵn một Custom Audience kiểu danh sách khách hàng để Orova đẩy email/SĐT vào.
• Google: Bạn cần một Conversion Action trong Google Ads, loại nhập thủ công (offline conversion import), để Orova đẩy chuyển đổi kèm gclid. Nếu muốn đồng bộ danh sách, chuẩn bị một Customer List cho Customer Match.
• TikTok: Bạn cần một Pixel trong TikTok Ads Manager. pixel_code chính là event_source_id mà Orova dùng khi gọi Events API.

Ngoài pixel, hãy kiểm tra quyền truy cập. Với Google, tài khoản dùng để nối phải có quyền trên Google Ads account; nếu không, sự kiện sẽ bị từ chối ở khâu gửi dù body JSON hoàn toàn đúng. Đây là lỗi rất hay gặp và rất dễ bỏ sót, vì nó không nằm ở phía bạn cấu hình mà nằm ở phân quyền tài khoản quảng cáo.

Cuối cùng, đảm bảo bạn đã nối các tài khoản quảng cáo này vào Orova. Toàn bộ thao tác nối nền tảng và quản lý chiến dịch nằm trong khu vực Ads của ứng dụng — tham khảo tài liệu Orova Ads nếu bạn chưa nối tài khoản nào.

Bước 2 — Tạo dự án và lấy webhook

Mỗi dự án trong Orova tương ứng với một luồng dữ liệu chuyển đổi riêng. Thông thường bạn tạo một dự án cho mỗi website hoặc mỗi hệ CRM. Sau khi tạo, mở phần cấu hình API Chuyển đổi của dự án, bạn sẽ thấy webhook bí mật đã được sinh tự động.

Webhook có dạng:

https://orova.vn/hooks/ads/acme-store/9f2c7b1e8a4d6055

Hãy sao chép nguyên văn URL này. Đây là địa chỉ duy nhất mà CRM của bạn sẽ gọi tới. Một vài lưu ý vận hành:

• Không nhúng webhook vào mã nguồn phía trình duyệt (front-end JavaScript công khai). Nó phải được gọi từ máy chủ CRM hoặc một back-end của bạn.
• Nếu bạn nghi URL bị lộ, bạn có thể tạo lại token để vô hiệu hoá URL cũ — giống như đổi mật khẩu.
• Một dự án, một webhook, phục vụ cả ba nền tảng. Bạn không cần ba URL khác nhau cho Meta, Google, TikTok. Việc gửi đi nền tảng nào do trường platform trong body và các công tắc quyết định.

Bước 3 — Chọn đích cho từng nền tảng

Trong cấu hình dự án, mỗi nền tảng có một ô chọn đích. Đây là nơi bạn nối Orova với cái pixel/conversion action đã chuẩn bị ở Bước 1.

Meta

Chọn Pixel (Dataset) mà bạn muốn nhận chuyển đổi. Nếu bật đồng bộ đối tượng, chọn thêm Custom Audience đích. Meta dùng Conversions API với action_source mặc định là website — phù hợp khi nguồn gốc lead là form trên web. Khoá khớp đặc thù của Meta là fbc và fbp (lấy từ cookie trình duyệt lúc khách tương tác với quảng cáo); kèm thêm email và số điện thoại sẽ tăng tỉ lệ khớp.

Google

Chọn Conversion Action đích. Google dùng Data Manager API, và điểm mấu chốt là chuyển đổi cần gclid — mã click Google gắn vào URL khi khách bấm quảng cáo. Không có gclid, Google khó quy chuyển đổi về đúng click, và nhiều trường hợp sẽ không nhận. Vì vậy CRM của bạn phải lưu lại gclid từ lúc khách đáp landing page và gửi kèm khi báo chuyển đổi. Nếu bật Customer Match, chọn Customer List đích.

TikTok

Chọn Pixel đích. TikTok dùng Events API với event_source=web và event_source_id chính là pixel_code của bạn. Khoá khớp đặc thù là ttclid. Tương tự Meta, gửi kèm email và SĐT giúp tăng tỉ lệ khớp khi thiếu click ID.

Bước 4 — Bật công tắc Gửi chuyển đổi và Đồng bộ đối tượng

Sau khi chọn đích, bật công tắc tương ứng cho từng nền tảng. Hãy suy nghĩ kỹ bạn cần gì.

• Chỉ Gửi chuyển đổi: Đây là cấu hình phổ biến nhất khi mục tiêu chính là cho thuật toán đấu thầu học đúng. Mỗi lead/đơn về sẽ được đẩy lên pixel như một sự kiện chuyển đổi.
• Chỉ Đồng bộ đối tượng: Dùng khi bạn muốn loại trừ người đã mua khỏi chiến dịch acquisition, hoặc gom một tệp khách chất lượng để tạo Lookalike, mà chưa cần đẩy chuyển đổi.
• Bật cả hai: Vừa tối ưu thầu vừa nuôi tệp đối tượng. Đây là cấu hình mạnh nhất nếu hạ tầng dữ liệu của bạn đủ sạch.

Trong body của webhook, bạn điều khiển hành vi này qua trường target với ba giá trị: pixel (chỉ gửi chuyển đổi), audience (chỉ đồng bộ tệp), hoặc both. Trường target ở cấp sự kiện sẽ làm việc cùng các công tắc ở cấp cấu hình; nếu công tắc đã tắt thì dù body yêu cầu, sự kiện vẫn bị bỏ qua (skipped) ở hướng đó.

Bước 5 — Gửi một sự kiện mẫu

Trước khi đấu nối CRM thật, hãy tự gửi một sự kiện thử bằng cURL để chắc chắn webhook nhận đúng. Dưới đây là một ví dụ đầy đủ cho Meta:

curl -X POST "https://orova.vn/hooks/ads/acme-store/9f2c7b1e8a4d6055" \
  -H "Content-Type: application/json" \
  -H "X-Orova-Secret: your-secret-key" \
  -d '{
    "event_name": "Purchase",
    "platform": "facebook",
    "target": "both",
    "email": "khachhang@gmail.com",
    "phone": "0394556897",
    "value": 1990000,
    "currency": "VND",
    "order_id": "DH-2026-000812",
    "event_time": 1750300000,
    "fbc": "fb.1.1750200000.IwAR0abc",
    "fbp": "fb.1.1750200000.1234567890",
    "client_ip": "203.0.113.45",
    "client_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)"
  }'

Với Google, đổi platform thành google và thay click ID bằng gclid:

curl -X POST "https://orova.vn/hooks/ads/acme-store/9f2c7b1e8a4d6055" \
  -H "Content-Type: application/json" \
  -H "X-Orova-Secret: your-secret-key" \
  -d '{
    "event_name": "Purchase",
    "platform": "google",
    "target": "pixel",
    "email": "khachhang@gmail.com",
    "phone": "0394556897",
    "value": 1990000,
    "currency": "VND",
    "order_id": "DH-2026-000812",
    "gclid": "Cj0KCQjw-EXAMPLE-gclid-string",
    "client_ip": "203.0.113.45",
    "client_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)"
  }'

Với TikTok, dùng ttclid và platform: tiktok:

curl -X POST "https://orova.vn/hooks/ads/acme-store/9f2c7b1e8a4d6055" \
  -H "Content-Type: application/json" \
  -H "X-Orova-Secret: your-secret-key" \
  -d '{
    "event_name": "CompletePayment",
    "platform": "tiktok",
    "target": "pixel",
    "email": "khachhang@gmail.com",
    "phone": "0394556897",
    "value": 1990000,
    "currency": "VND",
    "order_id": "DH-2026-000812",
    "ttclid": "E.C.P.ExampleTtclidString",
    "client_ip": "203.0.113.45",
    "client_user_agent": "Mozilla/5.0 (Android 13)"
  }'

Một lưu ý quan trọng khi test: hãy dùng một số điện thoại riêng để thử, đừng dùng số khách thật. Nếu bạn bắn sự kiện test bằng số của một khách đang được sale chăm sóc, dữ liệu phân bổ có thể bị nhiễu và gây loạn việc chia lead. Một số nội bộ chuyên dùng cho test sẽ giúp bạn yên tâm thử bao nhiêu lần cũng được.

Khớp khách chính xác: gửi đúng khoá là một nửa thành công

Chất lượng API Chuyển đổi đứng và sống nhờ khoá khớp (matching keys). Nền tảng quảng cáo cần đủ tín hiệu để nối sự kiện server-side của bạn về đúng người dùng và đúng click. Orova gửi kèm những khoá sau:

• Email và số điện thoại: Orova tự động băm SHA-256 trước khi gửi, nên dữ liệu thô không bao giờ rời hệ thống dưới dạng đọc được. Bạn cứ gửi email/SĐT bình thường trong body; việc băm là tự động.
• Click ID: fbc/fbp cho Meta, gclid cho Google, ttclid cho TikTok. Đây là khoá khớp mạnh nhất vì nó nối thẳng về click quảng cáo cụ thể.
• client_ip và client_user_agent: Hai trường này nên do CRM gửi kèm, vì nếu để mặc định thì IP của request lại là IP máy chủ CRM chứ không phải của khách. Hãy lưu IP và User-Agent của khách lúc họ tương tác trên web, rồi gửi lại khi báo chuyển đổi.

Nguyên tắc thực chiến: gửi càng nhiều khoá khớp càng tốt. Nếu chỉ có email thì khớp được, nhưng có thêm SĐT và click ID thì tỉ lệ khớp cao hơn hẳn, và thuật toán học nhanh hơn. Đặc biệt với Google, thiếu gclid là điểm chí mạng cho chuyển đổi — hãy ưu tiên lưu giữ và truyền lại nó.

Đặt khoá bí mật để chặn lời gọi giả

Webhook là một URL công khai về mặt kỹ thuật — bất kỳ ai biết nó đều có thể gửi POST. Để chặn người lạ bơm dữ liệu rác hoặc giả mạo chuyển đổi, hãy bật tuỳ chọn Khoá bí mật trong cấu hình dự án.

Khi đã đặt khoá, mọi lời gọi webhook phải kèm header X-Orova-Secret có giá trị khớp với khoá bạn đặt; nếu sai hoặc thiếu, Orova từ chối nhận. Bạn thấy header này trong các ví dụ cURL phía trên:

X-Orova-Secret: your-secret-key

Hãy cấu hình giá trị này ở phía CRM/back-end của bạn, tuyệt đối không để lộ trong mã front-end. Đây là lớp bảo vệ đơn giản nhưng hiệu quả: kể cả khi URL webhook bị lộ, người không có khoá bí mật vẫn không gửi được dữ liệu vào.

Đọc nhật ký gửi để xác nhận và chẩn lỗi

Sau khi bắn sự kiện, mở phần Nhật ký gửi của dự án. Mỗi sự kiện hiện một trạng thái, và đây là công cụ chẩn lỗi quan trọng nhất của bạn:

• received: Orova đã nhận được lời gọi webhook. Nếu thấy trạng thái này, nghĩa là CRM bắn đúng URL và qua được lớp khoá bí mật.
• sent: Sự kiện đã được gửi thành công tới nền tảng đích. Đây là trạng thái bạn mong muốn.
• skipped: Sự kiện được nhận nhưng bị bỏ qua — thường vì công tắc tương ứng đang tắt, hoặc trùng lặp với một sự kiện đã xử lý.
• failed: Có lỗi khi gửi tới nền tảng — thiếu khoá khớp bắt buộc, sai quyền tài khoản, hoặc đích không hợp lệ.

Nhật ký hiển thị khoá khớp ở dạng đã che để bảo mật, ví dụ a***@gmail.com và ****6897. Nhờ vậy bạn vẫn xác nhận được CRM gửi đúng số/đúng email mà không phơi bày dữ liệu cá nhân ra giao diện. Mỗi khi CRM báo "đã gửi" mà nhật ký Orova không có dòng received nào, bạn biết ngay vấn đề nằm ở phía CRM chứ không phải Orova.

Chống trùng: đừng để một đơn đếm hai lần

Một rủi ro kinh điển của chuyển đổi server-side là đếm trùng. CRM của bạn có thể gửi lại cùng một đơn hàng hai lần do retry mạng, hoặc pixel trình duyệt và webhook cùng báo về một giao dịch. Nếu không xử lý, thuật toán sẽ nghĩ bạn có gấp đôi doanh số và tối ưu lệch.

Orova dùng order_id (hoặc event_id) làm chìa khoá khử trùng. Khi hai sự kiện mang cùng order_id tới, sự kiện sau bị nhận diện trùng và đánh dấu skipped thay vì gửi lại. Vì vậy nguyên tắc là:

• Luôn gửi order_id ổn định và duy nhất cho mỗi giao dịch. Nếu là lead, hãy dùng một mã lead duy nhất.
• Khi cấu hình cả pixel trình duyệt lẫn webhook cho cùng một sự kiện, dùng cùng giá trị event_id/order_id ở cả hai phía để nền tảng tự khử trùng.
• Không tự sinh order_id ngẫu nhiên ở mỗi lần retry — như vậy mỗi retry sẽ thành một đơn mới.

Các lỗi thường gặp và cách sửa

Nhật ký không có dòng received nào

CRM đang không gọi đúng webhook. Kiểm tra lại URL có đúng {slug}/{token} không, có dùng https không, và phương thức có phải POST không. Nếu bạn vừa bật khoá bí mật, kiểm tra header X-Orova-Secret đã được CRM gửi kèm chưa.

Trạng thái failed với nền tảng Google

Hai nguyên nhân hàng đầu. Một là thiếu gclid — chuyển đổi Google gần như bắt buộc cần nó. Hai là tài khoản nối thiếu quyền trên Google Ads account; hãy kiểm tra người nối có quyền trên đúng tài khoản quảng cáo chứa Conversion Action.

Sự kiện luôn bị skipped

Thường do công tắc đang tắt cho hướng bạn yêu cầu. Nếu body đặt target: pixel mà công tắc Gửi chuyển đổi đang tắt, sự kiện sẽ bị bỏ qua. Mở cấu hình, bật đúng công tắc cho nền tảng tương ứng. Nguyên nhân thứ hai là trùng order_id — đây là hành vi đúng, không phải lỗi.

Tỉ lệ khớp thấp dù sự kiện sent

"Sent" chỉ nghĩa là Orova gửi thành công; nền tảng vẫn cần khoá khớp để nối về người dùng. Nếu tỉ lệ khớp thấp, bạn đang gửi thiếu khoá. Bổ sung click ID (fbc/fbp/gclid/ttclid), thêm cả email lẫn SĐT, và đảm bảo client_ip/client_user_agent là của khách chứ không phải máy chủ CRM.

Giá trị value hoặc currency bị sai

Gửi value dưới dạng số (không kèm dấu phẩy ngăn cách hàng nghìn) và currency đúng mã ISO như VND. Sai định dạng khiến nền tảng tính sai ROAS hoặc bỏ qua giá trị.

Checklist trước khi go-live

1. Pixel/Conversion Action/Pixel TikTok đã tồn tại trong tài khoản quảng cáo.
2. Tài khoản nối có đủ quyền — đặc biệt Google Ads.
3. Webhook đã sao chép đúng và chỉ dùng ở phía máy chủ.
4. Đích đã chọn đúng cho từng nền tảng bạn muốn dùng.
5. Công tắc Gửi chuyển đổi và/hoặc Đồng bộ đối tượng đã bật đúng nhu cầu.
6. Khoá bí mật đã đặt và CRM gửi kèm header X-Orova-Secret.
7. Đã bắn sự kiện test bằng số điện thoại riêng và thấy received rồi sent trong nhật ký.
8. CRM gửi kèm khoá khớp đầy đủ: email, SĐT, click ID phù hợp, client_ip, client_user_agent.
9. Mỗi giao dịch có order_id duy nhất và ổn định để chống trùng.
10. Đã theo dõi nhật ký vài ngày đầu để bắt sớm các trạng thái failed.

Câu hỏi thường gặp

Tôi có cần ba webhook cho ba nền tảng không?

Không. Một dự án có một webhook duy nhất phục vụ cả Meta, Google và TikTok. Trường platform trong body và các công tắc quyết định sự kiện đi đâu.

Orova có lưu email và số điện thoại thô của khách không?

Khoá nhạy cảm như email và SĐT được băm SHA-256 trước khi gửi tới nền tảng, và nhật ký chỉ hiển thị bản đã che. Bạn gửi dữ liệu vào và nhận lại sự an tâm rằng nó không rời hệ thống dưới dạng đọc được.

Tôi vừa dùng pixel trình duyệt vừa dùng API Chuyển đổi có bị đếm trùng không?

Không nếu bạn dùng cùng event_id/order_id ở cả hai phía. Nền tảng sẽ tự khử trùng. Đây thậm chí là cấu hình được khuyến nghị: pixel bắt sự kiện trên web, webhook bù lại những gì pixel bị chặn.

Vì sao sự kiện của tôi "sent" mà quảng cáo chưa thấy tối ưu lên?

Thuật toán cần thời gian và lượng dữ liệu đủ để học. "Sent" chỉ là bước gửi thành công; hiệu quả tối ưu thầu cần tích luỹ. Hãy đảm bảo tỉ lệ khớp tốt (gửi đủ khoá) và để hệ thống chạy ổn định trước khi đánh giá.

Tôi nên bắt đầu từ đâu nếu chỉ muốn thử một nền tảng?

Bắt đầu với nền tảng bạn chi nhiều ngân sách nhất, thường là Meta. Bật riêng Gửi chuyển đổi, bắn vài sự kiện test, xác nhận nhật ký sạch, rồi mới mở rộng sang Google và TikTok. Cách làm từng nền tảng giúp bạn cô lập lỗi dễ hơn nhiều so với bật tất cả cùng lúc.

Kết luận

Thiết lập API Chuyển đổi không phải là một dự án kỹ thuật khổng lồ — với Orova, nó là năm bước rõ ràng: chuẩn bị pixel, lấy webhook, chọn đích, bật công tắc, đọc nhật ký. Phần khó nhất không nằm ở việc bấm nút mà ở kỷ luật dữ liệu: gửi đủ khoá khớp, giữ order_id duy nhất, và truyền đúng gclid/fbc/ttclid từ CRM. Làm tốt những điều đó, bạn cho thuật toán đấu thầu nhìn thấy sự thật về doanh thu thay vì cái bóng mờ của pixel trình duyệt.

Hãy bắt đầu với một nền tảng, một sự kiện test bằng số riêng, và quan sát nhật ký chuyển từ received sang sent. Khi bạn đã quen vòng lặp đó, mở rộng ra cả ba nền tảng chỉ là lặp lại cùng một quy trình. Tìm hiểu thêm về toàn bộ hệ sinh thái quảng cáo AI tại Orova và tài liệu Orova Ads.