Przewodnik integracji

Formularz na Twojej stronie trafia do CRM w sekundę

Jak podłączyć formularz kontaktowy, Zapier albo Make do FluxCRM: adres, nagłówki, pola, odpowiedzi i test.

Jedno żądanie POST z sekretem w nagłówku tworzy szansę, zapisuje atrybucję kampanii i zgody RODO.

Jak to działa

Formularz na stronie (albo scenariusz Zapier lub Make) wysyła do CRM żądanie POST /api/zgloszenie z danymi kontaktu. CRM:

1. sprawdza sekret i poprawność pól,
2. tworzy szansę ze źródłem Strona www albo dopisuje wiadomość do istniejącej (ta sama osoba rozpoznawana jest po e-mailu),
3. zapisuje, z jakiej kampanii przyszedł klient (pola utm_*, landing_page, referrer),
4. zapisuje udzielone zgody RODO razem z dowodem,
5. jeśli podano telefon i włączone są dzwonki, dzwoni do doradcy w aplikacji Dzwonek.

Co jest potrzebne

Uwaga o sekrecie. Sekret jest hasłem do wpisywania leadów. Nie wklejaj go w kod JavaScript działający w przeglądarce odwiedzających, bo każdy go zobaczy. Wyślij formularz z własnego serwera strony (route handler Next.js, skrypt PHP, funkcja serverless) albo ze scenariusza Zapier lub Make.

Żądanie

POST https://crm.twojafirma.pl/api/zgloszenie
Content-Type: application/json
x-fluxcrm-sekret: <sekret>

{
  "email": "ewa.kowalska@example.com",
  "firma": "Sklep Ewy Sp. z o.o.",
  "telefon": "+48 600 100 200",
  "wiadomosc": "Dzień dobry, proszę o wycenę.",
  "landing_page": "https://twojafirma.pl/kontakt",
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "wiosna",
  "zgody": { "przetwarzanie": true, "marketing": false }
}

Pola

Całe żądanie nie może przekroczyć 64 KB. Znaki sterujące są usuwane, treść jest zawsze traktowana jako tekst (nie jako HTML).

Zgody RODO z dowodem

Obiekt zgody przyjmuje rodzaje przetwarzanie, marketing i bik. Zamiast true możesz podać obiekt z treścią zgody, którą klient zaakceptował: {"bik": {"zgoda": true, "tresc": "Wyrażam zgodę na zapytanie do BIK..."}}. CRM zapisuje rodzaj, chwilę, źródło (formularz), treść i adres strony jako dowód.

Przy formularzu zbierającym dane umieść obok przycisku klauzulę informacyjną. Gotowy wzór: klauzula informacyjna dla formularzy.

Odpowiedzi

Przykłady

curl

curl -sS -X POST https://crm.twojafirma.pl/api/zgloszenie \
  -H 'Content-Type: application/json' \
  -H "x-fluxcrm-sekret: $SEKRET" \
  -d '{"email":"test@example.com","wiadomosc":"Test integracji"}'

Next.js (route handler, sekret zostaje na serwerze)

export async function POST(req: Request) {
  const dane = await req.json();
  const odp = await fetch(`${process.env.CRM_URL}/api/zgloszenie`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-fluxcrm-sekret": process.env.CRM_SEKRET!,
    },
    body: JSON.stringify({ email: dane.email, wiadomosc: dane.wiadomosc }),
  });
  return new Response(null, { status: odp.ok ? 204 : 502 });
}

Zapier i Make

Moduł Webhooks, Custom request (Zapier) albo HTTP, Make a request (Make): metoda POST, adres jak wyżej, nagłówek x-fluxcrm-sekret, treść JSON z polami z formularza. Powiadomienia w drugą stronę (z CRM do Zapiera) opisuje osobna instrukcja webhooków wychodzących w repozytorium (deploy/webhook.md).

Wywołanie z przeglądarki (CORS)

Jeśli mimo ostrzeżenia musisz wysłać zgłoszenie bezpośrednio z przeglądarki, administrator wpisuje adres Twojej strony w [formularz] dozwolone_originy. Bez wpisu przeglądarka zablokuje odpowiedź.

Test

1. Wyślij zgłoszenie z curl.
2. W panelu w kolumnie Nowe i w pasku Do odpowiedzi pojawi się nowa szansa ze źródłem Strona www.
3. Otwórz kartę: treść, kampania i zgody powinny być widoczne. Szansę testową można oznaczyć jako przegraną z powodem "test".

Ogłoszenia z portali

Ten sam adres przyjmuje ogłoszenia z portali spoza Useme i Freelancehunt. Wystarczy dodać "typ": "oferta_portalu" i pola portal, numer, tytul, link, budzet, klient, opis. Ponowne zgłoszenie tego samego numeru niczego nie dubluje.

Landing i osadzany formularz (marketing)

Gdy nie masz własnej strony z formularzem, CRM sam ją wystawi. Administrator włącza [marketing] wlaczony = true i adres_publiczny, a w oknie Marketing (zakładka Landingi) właściciel dodaje stronę: adres, tytuł, opis, pola (telefon, wiadomość, firma), domyślną kampanię UTM, opcjonalnie kalkulator raty albo zdolności i chatbota kwalifikującego. Strona działa pod /m/lp/<adres>; zgłoszenie przechodzi tę samą drogę co webhook (atrybucja UTM, zgody RODO, dzwonek, auto-odpowiedź), a licznik odsłon i zgłoszeń widać na liście landingów.

Ten sam formularz można osadzić na stronie klienta: w oknie Marketing kopiujesz kod (znacznik div z atrybutem data-fluxcrm-lp i skrypt embed.js z adresu CRM, z atrybutami data-slug i data-token). Skrypt nie zawiera sekretu webhooka. Token to klucz publiczny strony, a CRM przyjmuje zgłoszenia tylko z domen wpisanych w dozwolone domeny osadzenia landingu (CORS) i ogranicza liczbę zgłoszeń z jednego adresu IP. Strona z własnym CSP musi dopuścić adres CRM w script-src, style-src i connect-src (dokładne dyrektywy podaje okno Marketing). Podejrzany token wymienisz przyciskiem Wymień token.

Kalkulator raty i zdolności kredytowej jest magnesem na leady: wynik klient widzi od razu, a po wysłaniu formularza trafia on do wiadomości szansy. Chatbot zadaje pytania z [marketing] chatbot (albo wbudowane), ocenia punktami opcji lub modelem, gdy jest włączony, i zakłada szansę z tagiem chatbot-goracy, chatbot-cieply albo chatbot-zimny.

W karcie szansy sekcja Marketing pokazuje źródło (UTM), koszt kampanii i koszt leada, preferencje klienta (kanał, godziny, język), wykluczenie "nie kontaktować", ankiety NPS oraz kod polecający z nagrodą. Zakładka Koszty i ROI liczy koszt leada i ROI per kampania z kosztów wpisanych ręcznie. Kampanie i newsletter trafiają do wybranego segmentu przez kolejkę poczty CRM: szkice maili czekają na zatwierdzenie właściciela, a po zatwierdzeniu wychodzą wg limitu dziennego i w godzinach wysyłki. Maile dostają link wypisu, a adresy bez zgody marketingowej, wykluczone albo z odbiciem są pomijane.