Dokumentacja dla deweloperów

Palyri Leads API

Wysyłaj leady do Palyri z dowolnego źródła: własnego lejka, Make.com, n8n, Zapiera albo backendu. Odsyłaj z powrotem informację, który lead się skonwertował i ile zostawił. Wszystkie dane liczą się w statystykach Palyri dokładnie tak samo, jak leady z naszych własnych lejków.

Zacznij tutaj

Potrzebujesz jednego tokenu. Wygeneruj go w panelu: Ustawienia → Integracje → Tokeny API. Token jest pokazywany raz. W bazie trzymamy tylko jego skrót.

curl -X POST 'https://app.palyri.com/api/leads/make-ingest' \
  -H 'X-Palyri-Token: pal_xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "Quiz",
    "external_id": "zgloszenie-8842",
    "ads_consent": true,
    "data": {
      "imię": "Anna",
      "telefon": "500600700",
      "email": "anna@example.com",
      "Jaki masz problem?": "Zmarszczki"
    },
    "campaign_attribution": {
      "utm_campaign": "Botoks Q3",
      "utm_content": "Kreacja A",
      "ad_id": "120210000000000000"
    }
  }'

Uwierzytelnianie

Każde żądanie niesie nagłówek X-Palyri-Token. Token jest przypisany do jednej kliniki i ma zakres uprawnień: leads:write (dodawanie leadów) oraz opcjonalnie conversions:write (raportowanie przychodu).

Dla integracji o podwyższonych wymaganiach włącz przy tworzeniu tokenu podpis HMAC. Wtedy sam token przestaje wystarczać: żądanie musi nieść jeszcze X-Palyri-Timestamp (czas uniksowy w sekundach) i X-Palyri-Signature. Podpis wiąże żądanie z jego treścią i czasem, więc przechwycony request nie da się odtworzyć po upływie 5 minut.

// Node.js
const crypto = require("crypto")

const body = JSON.stringify(payload)
const timestamp = Math.floor(Date.now() / 1000)
const signature = crypto
  .createHmac("sha256", SIGNING_SECRET)
  .update(`${timestamp}.${body}`)
  .digest("hex")

await fetch("https://app.palyri.com/api/leads/make-ingest", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Palyri-Token": TOKEN,
    "X-Palyri-Timestamp": String(timestamp),
    "X-Palyri-Signature": `sha256=${signature}`,
  },
  body,
})

Dodawanie leadów

Przyjmujemy trzy kształty payloadu i sami je normalizujemy: natywny format Meta Lead Ads (field_data), format modułu Facebook Lead Ads z Make.com (mappable_field_data) oraz najprostszy, czyli obiekt data z parami pole/wartość. Nazwy pól rozpoznajemy po polsku i po angielsku.

Odpowiedź:

HTTP 200
{ "ok": true, "accepted": true }

Duplikaty odrzucamy na trzy sposoby: po leadgen_id z Meta, po Twoim external_id oraz, jako siatka bezpieczeństwa dla zgłoszeń bez żadnego identyfikatora, po tym samym numerze telefonu w oknie 10 minut.

Atrybucja reklam

To jest część, która decyduje o tym, czy Palyri policzy koszt pozyskania leada. Potrzebujemy identyfikatora reklamy, a nie samej nazwy: nazwę można w Meta zmienić w locie, identyfikator nigdy się nie zmienia.

W Menedżerze reklam ustaw parametry adresu URL dla reklamy prowadzącej na Twój lejek:

utm_source=facebook
utm_medium=paid
utm_campaign={{campaign.name}}
utm_term={{adset.name}}
utm_content={{ad.name}}
ad_id={{ad.id}}
adset_id={{adset.id}}
campaign_id={{campaign.id}}

Twój lejek odczytuje te parametry z adresu i przesyła je nam razem z leadem, w obiekcie campaign_attribution albo jako pola najwyższego poziomu. Obie formy działają.

Zgoda i powrót konwersji do Meta

Palyri odsyła do Meta zdarzenia z Conversions API, żeby kampania optymalizowała się na tym, co realnie się wydarzyło, a nie tylko na kliknięciach. Wysyłamy trzy zdarzenia:

Jakość dopasowania podnosisz, przesyłając fbp, fbc i fbclid. Depozyt wpada do CRM kilka dni po zgłoszeniu, gdy nie ma już żadnej przeglądarki ani ciasteczek, zapisujemy je więc przy zgłoszeniu i odtwarzamy przy każdym późniejszym zdarzeniu.

Jeśli Twój lejek strzela własnym pikselem, prześlij nam ten sam event_id. Meta zdeduplikuje parę i policzy jedną konwersję zamiast dwóch.

Raportowanie przychodu

Depozyty i przychody wpisane w Palyri lecą do Meta automatycznie. Ten endpoint jest dla sprzedaży, która domyka się poza Palyri: w Twoim systemie, Twojej kasie. Wymaga tokenu z uprawnieniem conversions:write.

curl -X POST 'https://app.palyri.com/api/leads/conversion' \
  -H 'X-Palyri-Token: pal_xxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "external_id": "zgloszenie-8842",
    "event_name": "Purchase",
    "value": 2400,
    "currency": "PLN",
    "update_lead": true
  }'

HTTP 202
{ "ok": true, "lead_id": "…", "event_name": "Purchase", "event_id": "purchase-…", "queued": true }

Webhooki wychodzące

Druga strona integracji: Palyri wysyła żądanie do Ciebie, gdy coś dzieje się z leadem. Endpoint rejestrujesz w panelu (Ustawienia → Integracje → Webhooki wychodzące) i dostajesz sekret do weryfikacji podpisu.

Przykładowe żądanie, które wyślemy:

POST https://your-server.example/palyri
Content-Type: application/json
X-Palyri-Event: lead.status_changed
X-Palyri-Delivery: 3f2b…            // delivery id, stable across retries
X-Palyri-Timestamp: 1787327270
X-Palyri-Signature: sha256=…

{
  "event": "lead.status_changed",
  "delivery_id": "3f2b…",
  "sent_at": "2026-08-21T15:44:15.155Z",
  "clinic_id": "…",
  "data": {
    "lead": {
      "id": "…",
      "name": "Anna Kowalska",
      "phone": "+48500600700",
      "email": "anna@example.com",
      "status": "deposit_paid",
      "source": "Meta Ads",
      "ad_name": "Kreacja A",
      "external_id": "zgloszenie-8842",
      "treatment_value": null,
      "campaign_attribution": { "utm_campaign": "Botoks Q3" }
    },
    "status": "deposit_paid",
    "previous_status": "contacted"
  }
}

Weryfikacja podpisu po Twojej stronie:

// Node.js: the comparison MUST be constant-time
const crypto = require("crypto")

function verify(req, rawBody, SECRET) {
  const ts = Number(req.headers["x-palyri-timestamp"])
  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false

  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(`${ts}.${rawBody}`)
    .digest("hex")

  const got = String(req.headers["x-palyri-signature"]).replace(/^sha256=/, "")
  const a = Buffer.from(expected), b = Buffer.from(got)
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

Nieudaną dostawę ponawiamy sześć razy z narastającą przerwą (1 min, 5 min, 25 min, ~2 h, ~10 h). X-Palyri-Delivery jest stałe między ponowieniami, więc użyj go jako klucza idempotencji, bo to samo zdarzenie może przyjść u Ciebie dwa razy.

Limity i błędy

Po rotacji tokenu w panelu stary działa jeszcze przez 48 godzin, żeby dało się go podmienić w scenariuszach bez przerwy w napływie leadów. W odpowiedzi dostajesz wtedy pole warning. Jeśli token wyciekł, unieważnij stary natychmiast. Przycisk jest obok ostrzeżenia w panelu.