Postback API

Postback là request từ máy chủ của nhà quảng cáo gửi tới Postbackly để báo “click này đã ra đơn”. Không pixel, không cookie, không gì chạy trên trình duyệt của khách.

Tổng quan

Khách vào landing page qua một link Postbackly, URL có pbclid=… (xem tài liệu redirect).
Website của bạn lưu giá trị đó cùng phiên hoặc đơn hàng của khách, trên chính domain của bạn.
Khi đơn được xác nhận, máy chủ của bạn gọi URL postback với pbclid làm click_id.
Postbackly ghi một conversion cho offer, publisher và sub-id của click đó, trạng thái chờ duyệt.

Endpoint

https://go.postbackly.click/postback?click_id={pbclid}&txid={order_id}&payout={amount}&key=YOUR_OFFER_KEY

GET với tham số trên query, hoặc POST với body application/x-www-form-urlencoded. Chỉ HTTPS. Thay YOUR_OFFER_KEY bằng khoá postback hiện ở offer trong bảng điều khiển, và các biến {…} bằng biến của nền tảng bạn dùng.

Tham số

Tên	Bắt buộc	Mô tả
`click_id`	có*	Giá trị `pbclid` mà landing page nhận được.
`gclid`	*	Chỉ dùng khi landing page không có `pbclid` (parallel tracking của Google Ads, xem bên dưới): giá trị `gclid` Google Ads gắn vào URL landing. Nó được ghép với click mang cùng `gclid` trên link tracking, nên hãy giữ `gclid={gclid}` trong tracking template. *Gửi `click_id` hoặc `gclid`; gửi cả hai thì dùng `click_id`.
`key`	có	Khoá postback bí mật của offer mà click thuộc về.
`txid`	không	Mã đơn hàng hoặc mã giao dịch của bạn. Duy nhất trong mỗi offer: cùng một `txid` chỉ được ghi một lần. Không gửi thì mỗi click chỉ có một conversion.
`payout`	không	Hoa hồng cho conversion này, dạng số (ví dụ `45000` hoặc `12.5`). Không gửi thì dùng payout mặc định của offer.
`currency`	không	Mã tiền tệ 3 chữ cái như `VND`, `USD`. Mỗi tài khoản báo cáo bằng một loại tiền, chọn trong bảng điều khiển. Nếu gửi thì phải trùng loại tiền đó, nếu không postback bị từ chối với `400`; chúng tôi không bao giờ quy đổi.

Đừng thêm tham số tên url: trên domain tracking, url dành riêng cho redirect, request có nó sẽ bị coi là click chứ không phải postback.

Ví dụ

GET

curl "https://go.postbackly.click/postback?click_id=Rk7pW2xQa9Lm_3Tc&txid=A1043&payout=45000&key=YOUR_OFFER_KEY"

POST form

curl -X POST "https://go.postbackly.click/postback" \
  -d click_id=Rk7pW2xQa9Lm_3Tc -d txid=A1043 -d payout=45000 -d currency=VND -d key=YOUR_OFFER_KEY

Phản hồi

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"ok","conversion_id":1287}

Phản hồi

Mọi phản hồi đều là JSON.

Mã	Ý nghĩa	Nên làm gì
200	Đã ghi conversion. Body có `conversion_id`.	Xong.
400	Thiếu tham số bắt buộc hoặc giá trị sai định dạng (ví dụ payout không phải số).	Sửa request; đừng gửi lại nguyên như cũ.
403	Khoá không khớp với offer của click, hoặc offer hay tài khoản đang bị khoá.	Kiểm tra lại khoá trong bảng điều khiển.
404	Không có click nào với `click_id` (hoặc `gclid`) này, hoặc click đã quá 90 ngày.	Kiểm tra bạn gửi pbclid nguyên vẹn; đừng gửi lại.
409	`txid` này đã được ghi cho offer này (hoặc, khi không có `txid`, click này đã có conversion).	Đã được tính. Ngừng gửi lại.

Trùng lặp và gửi lại

Postback có tính idempotent theo txid. Nếu máy chủ của bạn bị timeout hoặc không chắc postback đã tới chưa, cứ gửi lại với cùng txid: lần đầu nhận 200, các lần sau nhận 409, không bao giờ thành conversion thứ hai. Chỉ gửi lại khi lỗi mạng hoặc nhận mã 5xx, giãn dần thời gian chờ; đừng gửi lại khi nhận 400, 403 hay 404.

Nếu một click ra nhiều conversion, ví dụ khách mua lần hai, hãy gửi mỗi conversion với một txid riêng.

Giữ an toàn khoá

Mỗi offer có khoá riêng, nên lộ một khoá không thể tạo conversion cho các offer khác của bạn.
Chỉ gửi postback từ máy chủ. Không bao giờ đặt khoá trong pixel trên trình duyệt, JavaScript, ứng dụng di động hay trang mà khách xem được.
Nên dùng POST: chuỗi query dễ bị ghi vào log trên đường truyền hơn.
Chúng tôi so sánh khoá theo thời gian hằng định (constant-time) và chỉ ghi postback khi khoá khớp với offer của click.
Nếu nghi khoá bị lộ, gửi email tới contact@postbackly.click và tạm dừng offer cho tới khi khoá được thay; bạn vẫn có thể từ chối mọi conversion bất thường.

Bản thân pbclid không phải bí mật: nó nằm trên URL landing page. Khoá mới là thứ chứng minh postback đến từ bạn.

Duyệt và đối soát

chờ duyệt→đã duyệthoặcbị từ chối

Mọi conversion bắt đầu ở trạng thái chờ duyệt. Trong mỗi kỳ thanh toán, nhà quảng cáo hoặc network duyệt hay từ chối conversion từng cái hoặc hàng loạt, ví dụ từ chối đơn bị huỷ. Màn hình đối soát hiện tổng chờ duyệt, đã duyệt, bị từ chối của từng publisher, và xuất CSV để thanh toán.

Postbackly chỉ giữ số liệu. Chúng tôi không giữ, không thu hộ và không chuyển tiền hoa hồng; việc thanh toán là giữa bạn và publisher.

Danh sách kiểm tra

Tự mở link của một publisher, kiểm tra URL landing page có pbclid=… ở cuối.
Gửi postback với giá trị đó và một txid thử: phải nhận 200.
Gửi lại đúng request đó: phải nhận 409.
Tìm conversion trong báo cáo ở trạng thái chờ duyệt, rồi từ chối nó để không bị tính.