Vòng lặp Ads ↔ CRM

Quảng cáo thường chỉ tối ưu theo click. Phê Nâu đóng vòng lặp: khi khách thực sự đặt lịch / chốt, hệ thống bắn tín hiệu chuyển đổi (đã hash) về receiver của đối tác chạy ads để họ relay lên Meta/Google và tối ưu theo chốt thật— đồng thời pull chi tiêu chiến dịch về để chủ nhà thấy ROAS ngay trong dashboard vận hành.

Vòng lặp kín

Điểm mấu chốt: tín hiệu chốt thật quay ngược về ad platform để nó tối ưu targeting — khép vòng, thay vì ad chỉ tối ưu theo click. Doanh thu ghép chi phí → ROAS từng chiến dịch.

Hai chiều dữ liệu

Luồng hoạt động

• Khách click ad → nhắn tin / điền form

  Phê Nâu ghi first-touch attribution: chat lấy ad_id từ Messenger (Facebook không gửi campaign_id — campaign đến từ API quảng cáo khi ghép chi phí); landing page lấy UTM + click id (fbclid/gclid).

• Khách đặt lịch / chốt

  Tại đúng thời điểm chuyển đổi, hệ thống dựng một ConversionEvent chuẩn (định danh, giá trị, contact đã hash).

• Phê Nâu bắn webhook về bạn

  POST kèm chữ ký HMAC + event_id idempotency. Bạn verify → dedup → relay lên Meta/Google.

• Bạn cấp spend → Phê Nâu dựng ROAS

  Phê Nâu pull chi phí chiến dịch, ghép doanh thu chốt → hiệu quả từng chiến dịch hiện trong dashboard.

Chiều 1 — Webhook Phê Nâu gửi về bạn

Bạn implement một endpoint nhận POST, verify chữ ký, dedup theo event_id, rồi relay. Cấu hình URL + secret trong Phê Nâu là xong (giống webhook Stripe/Shopify).

Payload

POST <your_webhook_url>
Content-Type: application/json
X-Phenau-Signature: sha256=<hex>     # HMAC-SHA256(secret, raw_body)
X-Phenau-Event-Id: <event_id>        # idempotency key

{
  "event_id": "evt_appt_8f21_Appointment_Booked",  // DEDUP theo cái này
  "event_name": "Appointment_Booked",   // Runtime hiện wire chắc: Appointment_Booked | Purchase
  "ad_id": "120210...",                  // ID ads (null nếu lead không từ ad)
  "campaign_id": "120210...",            // ID SỐ thật (không phải tên)
  "click_id": "fb.1.1720000000.abc",     // fbclid/gclid — match khi thiếu ad_id
  "value": 500000,                       // giá trị ước tính, có thể null
  "currency": "VND",
  "hashed_email": "e3b0c442...",         // SHA-256(lowercase-trim) — KHÔNG raw
  "hashed_phone": "a3f5b1c9...",         // SHA-256(E.164) — KHÔNG raw
  "occurred_at": "2026-07-03T10:00:00Z"
}

Receiver mẫu (~20 dòng, FastAPI)

import hmac, hashlib
from fastapi import FastAPI, Request, HTTPException

SECRET = b"<secret_ban_cau_hinh_trong_phenau>"
seen: set[str] = set()  # thực tế: DB/Redis

app = FastAPI()

@app.post("/phenau/conversions")
async def receive(request: Request):
    body = await request.body()
    sig = (request.headers.get("X-Phenau-Signature") or "").removeprefix("sha256=")
    expected = hmac.new(SECRET, body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sig, expected):
        raise HTTPException(401, "bad signature")
    event_id = request.headers.get("X-Phenau-Event-Id", "")
    if event_id in seen:
        return {"ok": True, "dedup": True}   # idempotent
    seen.add(event_id)
    # TODO: relay event lên Meta/Google Conversions API
    return {"ok": True}

Bạn phải làm gì

1. Verify HMAC-SHA256(secret, raw_body) với header chữ ký; sai → 401.
2. Idempotent: nếu đã xử lý event_id này → bỏ qua (tránh double-count).
3. Relay lên Meta/Google Conversions API bằng hashed contact + ad_id/click_id.
4. Trả 2xx để ack.

Chiều 2 — Phân giải chi phí quảng cáo (Spend Pulling)

Để dựng được Dashboard hiệu quả quảng cáo (ROAS), Phê Nâu hỗ trợ cả 2 con đường linh hoạt tùy thuộc vào thỏa thuận bảo mật và khả năng tích hợp kỹ thuật giữa Doanh nghiệp và Đối tác chạy Ads:

Phương án A (Ưu tiên): Phê Nâu tự động kéo chi phí trực tiếp từ Meta Ads

Doanh nghiệp tự kết nối tài khoản Facebook cá nhân (có quyền xem tài khoản quảng cáo) và nhập Ad Account ID trong phần Cài đặt Workspace. Phê Nâu sẽ trực tiếp kết nối với Meta Marketing API để tự động kéo chi phí theo thời gian thực mà đối tác không cần viết bất kỳ dòng code API nào.

Phương án B: Đối tác cấp GET API chi phí cho Phê Nâu

Trong trường hợp Đối tác chạy Ads (Agency) sở hữu tài khoản quảng cáo riêng biệt và không muốn/không thể chia sẻ quyền Analyst trực tiếp cho doanh nghiệp, bạn có thể expose một GET API trả về chi phí quảng cáo theo chiến dịch. Phê Nâu sẽ pull dữ liệu này định kỳ. campaign_id phải KHỚP với trường trong conversion webhook để Phê Nâu ghép chi phí ↔ doanh thu.

GET <your_api>/ads/metrics?since=2026-06-01&until=2026-06-30
Authorization: Bearer <token_ban_cap_cho_phenau>

{
  "campaigns": [
    {
      "campaign_id": "120210...",   // KHỚP campaign_id trong conversion webhook
      "name": "BĐS Q7 — Lead Form",
      "spend": 12500000,            // VND
      "clicks": 3200,
      "leads": 85,
      "currency": "VND"
    }
  ]
}