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. Tym samym kluczem wpiszesz też SMS-y, telefony i maile na oś klienta.

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. 7county — powiat (np. „proszowicki”)
8. 8commune — gmina (np. „Proszowice”)
9. 9voivodeship — województwo (np. „śląskie”; pisownia bez polskich znaków też przejdzie)
10. 10notes — treść zgłoszenia, uwagi klienta
11. 11source — skąd przyszło zgłoszenie (np. „Facebook”); jeśli pominiesz, Teodo wpisze nazwę klucza
12. 12estimated_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. Jeśli e-mail, województwo albo kwota przyszły w złej postaci (np. kod pocztowy w polu województwa, e-mail bez domeny, kwota słownie), lead i tak powstaje: to pole zostaje puste, a oryginalna wartość trafia na początek notatki leada. Za długi tekst jest przycinany do limitu (końcówka przepada), a lista albo obiekt w polu tekstowym zapisuje się jako tekst. Każdą taką poprawkę odpowiedź wymienia w „warnings”.
2. 2200 — to samo żądanie już wcześniej się udało (rozpoznane po Idempotency-Key), nowy lead nie powstał.
3. 3400 — leada nie da się zapisać: brak nazwy, telefonu, e-maila i adresu (albo jedyny podany e-mail jest niepoprawny) lub przesłano pole tylko do odczytu, np. assigned_to. 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”.

Kontakty (SMS, telefon, mail) na osi klienta

Tym samym kluczem automatyzacja może wpisywać kontakty z klientem — np. SMS z bramki SMSAPI, notatkę z centrali telefonicznej albo mail. Wpis ląduje na osi aktywności klienta (albo leada), obok reszty historii.

1. 1Metoda: POST. Adres: https://teodo.pl/api/v1/activities. Nagłówki jak wyżej (Authorization, Content-Type, opcjonalnie Idempotency-Key).
2. 2channel — wymagane: phone, sms, email, meeting albo other.
3. 3phone albo email — wymagane przynajmniej jedno; po nim Teodo znajduje właściwą osobę.
4. 4direction — in (od klienta, domyślnie) albo out (do klienta).
5. 5occurred_at — zalecane: kiedy kontakt się odbył, data z godziną i strefą (np. 2026-09-30T14:05:00+02:00); nie może być z przyszłości. Bez niego wpis dostaje chwilę, w której żądanie dotarło do Teodo — gdy Make ponowi wysyłkę po kilku godzinach, kontakt stanie na osi z opóźnieniem. Mapuj tu datę wiadomości z bramki SMS.
6. 6body — treść SMS-a albo notatka; subject — temat (np. maila); contact_name — imię, użyte tylko przy zakładaniu nowego leada.

Teodo szuka właściciela kontaktu po kolei: telefon klienta, telefon osoby kontaktowej klienta, e-mail klienta, na końcu otwarty lead (po telefonie, a potem po e-mailu). Wpis trafia na pierwszego znalezionego.

Gdy nikogo nie znajdzie, Teodo zakłada nowego leada z tego kontaktu — nazwanego imieniem z contact_name albo numerem/e-mailem, ze źródłem zgodnym z kanałem (np. „SMS”) — i wpisuje kontakt na jego oś. Odpowiedź ma wtedy lead_created: true.

Przykład scenariusza Make: wyzwalacz „Webhooks → Custom webhook” podpięty pod odpowiedź SMSAPI o SMS-ie przychodzącym, potem moduł „HTTP → Make a request” na adres /api/v1/activities z takim ciałem (Idempotency-Key: identyfikator wiadomości z SMSAPI): Pola sms_from, sms_text i sms_date (znacznik czasu w sekundach) to nazwy z powiadomienia SMSAPI o SMS-ie przychodzącym — u innego dostawcy podstaw jego nazwy.

{
  "channel": "sms",
  "direction": "in",
  "phone": "{{1.sms_from}}",
  "occurred_at": "{{formatDate(parseDate(1.sms_date; X); YYYY-MM-DDTHH:mm:ssZ)}}",
  "body": "{{1.sms_text}}"
}

Odpowiedź pokazuje, gdzie wylądował wpis:

{
  "id": "…",
  "client_id": "…",
  "lead_id": null,
  "lead_created": false,
  "url": "https://teodo.pl/klienci/…"
}

1. 1201 — wpis zapisany (lead_created mówi, czy przy okazji powstał nowy lead).
2. 2200 — to samo żądanie już się udało (Idempotency-Key); zwrócono istniejący wpis, nagłówek „Idempotency-Replayed: true”. Przy powtórzeniu lead_created to zawsze false, nawet jeśli pierwsze żądanie założyło leada — sprawdź lead_id.
3. 3400 — błąd w danych, odpowiedź wskazuje pole.
4. 4422 — brak klienta i leada, a kontakt zgłosił sprzeciw, więc nowy lead nie powstał. Nie ponawiaj.
5. 5503 — chwilowy błąd zapisu; ponów żądanie z tym samym Idempotency-Key.
6. 6Pozostałe kody (401, 403, 413, 429) jak w sekcji powyżej.