API dla automatyzacji leadów

Zapytania od klientów wpadają dziś z kilku miejsc naraz: formularza na stronie, reklamy z Facebooka, arkusza, do którego wpisuje je recepcja. Przepisywanie ich ręcznie do systemu jest tym etapem pracy, który najłatwiej odpuścić przy pierwszym zajętym dniu — a wtedy zapytanie po prostu ginie.

Publiczne API pozwala automatyzacji (Make, Zapier, n8n albo własnemu skryptowi) wpisać takie zapytanie do Teodo samodzielnie, bez logowania. Poniżej opisujemy, jak wygenerować klucz, jak zmapować pola w scenariuszu i co znaczą kody odpowiedzi, gdy coś nie zadziała.

Automatyzacje (Make, Zapier, n8n albo własny skrypt) mogą same wpisywać leady do Teodo, bez Twojego logowania — przez publiczne API. Formularz na stronie, formularz FB Lead Ads albo arkusz z leadami z ogłoszenia wpadają do Teodo same, bez przepisywania ręcznie.

Klucz API

1. 1Ustawienia → Integracje → „Klucze API” → „Nowy klucz”.
2. 2Nazwij klucz tak, żeby za pół roku wiedzieć, który scenariusz go używa (np. „Formularz FB”).
3. 3Sekret pokazuje się TYLKO RAZ, tuż po utworzeniu. Skopiuj go i wklej do scenariusza — jeśli go zgubisz, generujesz nowy klucz, starego nie da się odzyskać.

Co ustawić w automatyzacji

1. 1Dodaj krok wysyłający żądanie HTTP — w Make to moduł „HTTP → Make a request”, w Zapier „Webhooks → POST”, w n8n węzeł „HTTP Request”.
2. 2Metoda: POST. Adres: https://teodo.pl/api/v1/leads.
3. 3Dodaj dwa nagłówki. Pierwszy: nazwa „Authorization”, wartość „Bearer ” i zaraz za spacją wklejony klucz. Drugi: nazwa „Content-Type”, wartość „application/json”.
4. 4Format treści: JSON. Wskaż, które pole ze źródła ma trafić do którego pola w Teodo. Nazwy pól Teodo wpisz dokładnie tak, jak niżej — małymi literami, z podkreślnikami.

Tak wyglądają te dwa nagłówki wpisane obok siebie (Twój klucz będzie inny):

Authorization: Bearer tdo_live_9fK2mQ7xR4tL8vB1nC6yH3jS5dW0gZpA
Content-Type: application/json

1. 1name — imię i nazwisko albo nazwa firmy
2. 2phone — telefon
3. 3email — e-mail
4. 4address — ulica i numer
5. 5postal_code — kod pocztowy
6. 6city — miasto
7. 7notes — treść zgłoszenia, uwagi klienta
8. 8source — skąd przyszło zgłoszenie (np. „Facebook”); jeśli pominiesz, Teodo wpisze nazwę klucza
9. 9estimated_value_gross — szacowana wartość brutto, sama liczba (np. 12000)

Wypełniasz tylko te pola, które masz.

Tak wygląda mapowanie pól w scenariuszu Make — po lewej nazwa pola Teodo, po prawej pole ze źródła w podwójnych nawiasach klamrowych. W Zapier, n8n albo innym narzędziu składnia będzie inna, ale zasada ta sama: pole Teodo po jednej stronie, pole ze źródła po drugiej.

{
  "name": "{{1.imie_i_nazwisko}}",
  "phone": "{{1.telefon}}",
  "email": "{{1.email}}",
  "notes": "{{1.tresc_zgloszenia}}",
  "source": "Facebook"
}

A tak wygląda to, co realnie dostaje Teodo, gdy scenariusz się wykona:

{
  "name": "Jan Kowalski",
  "phone": "600100200",
  "email": "jan.kowalski@example.com",
  "notes": "Wymiana instalacji w mieszkaniu 60 m². Prosi o kontakt po 16:00.",
  "source": "Facebook"
}

W tym przykładzie źródło nie miało adresu, kodu pocztowego, miasta ani szacowanej wartości — pola po prostu pominięto, i to jest w porządku.

Żeby ten sam lead nie wpadł dwa razy

To pole możesz pominąć — wtedy przy zerwanym połączeniu zdarzy się, że ten sam lead wpadnie dwa razy i drugi skasujesz ręcznie. Jeśli chcesz mieć spokój, dodaj nagłówek „Idempotency-Key” i wskaż w nim pole, które jednoznacznie oznacza to konkretne zgłoszenie.

1. 1Arkusz Google → pole „Row number” albo własna kolumna z numerem zgłoszenia.
2. 2Facebook Lead Ads → pole „Lead ID”.
3. 3Formularz na stronie → pole z identyfikatorem zgłoszenia, jeśli formularz je nadaje.

Chodzi o wartość, która jest inna dla każdego zgłoszenia i nie zmienia się, gdy automatyzacja ponawia wysyłkę. Jeśli takiego pola nie masz — zostaw nagłówek pusty.

Kto zobaczy leada z automatyzacji

Lead z API nie ma przypisanego opiekuna. Widzą go osoby z uprawnieniem zarządzania leadami — to one przypisują go dalej do konkretnego sprzedawcy. Pracownik bez tego uprawnienia zobaczy leada dopiero PO przypisaniu, więc jeśli firma „nie widzi leadów z automatyzacji”, sprawdź listę u osoby zarządzającej leadami, nie u sprzedawcy.

Kody odpowiedzi

1. 1201 — lead zapisany.
2. 2200 — to samo żądanie już wcześniej się udało (rozpoznane po Idempotency-Key), nowy lead nie powstał.
3. 3400 — błąd w danych: coś nie przechodzi walidacji albo przesłano pole, którego Teodo nie obsługuje. Odpowiedź wskazuje, które pole.
4. 4401 — klucz jest nieprawidłowy albo unieważniony. Wygeneruj nowy w Ustawieniach → Integracje.
5. 5403 — moduł leadów jest wyłączony w Teodo albo licencja firmy wygasła.
6. 6413 — dane, które wysyłasz, są za duże (limit 16 KB). Zdarza się przy długiej notatce razem z kilkoma innymi polami — skróć treść w polu notes.
7. 7422 — ten kontakt (telefon albo e-mail) zgłosił sprzeciw wobec kontaktu. NIE ponawiaj tego żądania — to nie awaria, a odmowa zapisu.
8. 8429 — automatyzacja wysyła więcej żądań niż limit na godzinę. Odczekaj czas wskazany w nagłówku „Retry-After”.