API для автоматизації лідів

Запити від клієнтів надходять сьогодні з кількох місць одразу: форми на сайті, реклами з Facebook, таблиці, куди їх вписує рецепція. Ручне перенесення їх у систему — той етап роботи, який найлегше відкласти в перший завантажений день, а тоді запит просто зникає.

Публічне API дозволяє автоматизації (Make, Zapier, n8n або власному скрипту) самостійно вписати такий запит у Teodo, без входу в систему. Нижче — як створити ключ, як зматчити поля в сценарії і що означають коди відповідей, коли щось не спрацює.

Автоматизації (Make, Zapier, n8n або власний скрипт) можуть самі додавати ліди в Teodo, без твого входу в систему — через публічне API. Форма на сайті, форма FB Lead Ads або таблиця з лідами з оголошення потрапляють у Teodo самі, без ручного перенесення.

Ключ API

1. 1Налаштування → Інтеграції → «Ключі API» → «Новий ключ».
2. 2Назви ключ так, щоб за півроку знати, який сценарій його використовує (наприклад, «Форма FB»).
3. 3Секрет показується ТІЛЬКИ РАЗ, одразу після створення. Скопіюй його і встав у сценарій — якщо загубиш, створюєш новий ключ, старий відновити неможливо.

Що налаштувати в автоматизації

1. 1Додай крок, який надсилає HTTP-запит — у Make це модуль «HTTP → Make a request», у Zapier «Webhooks → POST», у n8n вузол «HTTP Request».
2. 2Метод: POST. Адреса: https://teodo.pl/api/v1/leads.
3. 3Додай два заголовки. Перший: назва «Authorization», значення «Bearer » і одразу за пробілом вставлений ключ. Другий: назва «Content-Type», значення «application/json».
4. 4Формат тіла: JSON. Вкажи, яке поле з джерела має потрапити в яке поле Teodo. Назви полів Teodo пиши точно так, як нижче — малими літерами, з підкресленнями.

Так виглядають ці два заголовки, записані поруч (твій ключ буде інший):

Authorization: Bearer tdo_live_9fK2mQ7xR4tL8vB1nC6yH3jS5dW0gZpA
Content-Type: application/json

1. 1name — ім'я та прізвище або назва фірми
2. 2phone — телефон
3. 3email — пошта
4. 4address — вулиця і номер
5. 5postal_code — поштовий індекс
6. 6city — місто
7. 7notes — зміст звернення, зауваження клієнта
8. 8source — звідки прийшло звернення (наприклад, «Facebook»); якщо пропустиш, Teodo впише назву ключа
9. 9estimated_value_gross — орієнтовна вартість брутто, просто число (наприклад, 12000)

Заповнюєш лише ті поля, які маєш.

Так виглядає мапування полів у сценарії Make — зліва назва поля Teodo, справа поле з джерела в подвійних фігурних дужках. У Zapier, n8n чи іншому інструменті синтаксис буде інший, але принцип той самий: поле Teodo з одного боку, поле з джерела — з іншого.

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

А так виглядає те, що насправді отримує Teodo, коли сценарій виконається:

{
  "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"
}

У цьому прикладі джерело не мало адреси, поштового індексу, міста і орієнтовної вартості — ці поля просто пропущено, і це нормально.

Щоб той самий лід не потрапив двічі

Це поле можеш пропустити — тоді при розірваному з'єднанні трапиться, що той самий лід потрапить двічі, і другий доведеться видалити вручну. Якщо хочеш мати спокій, додай заголовок «Idempotency-Key» і вкажи в ньому поле, яке однозначно позначає це конкретне звернення.

1. 1Google Таблиця → поле «Row number» або власна колонка з номером звернення.
2. 2Facebook Lead Ads → поле «Lead ID».
3. 3Форма на сайті → поле з ідентифікатором звернення, якщо форма його надає.

Йдеться про значення, яке відрізняється для кожного звернення і не змінюється, коли автоматизація повторює надсилання. Якщо такого поля не маєш — залиш заголовок порожнім.

Хто побачить лід з автоматизації

Лід з API не має призначеного відповідального. Його бачать особи з правом керування лідами — саме вони призначають його далі конкретному продавцю. Працівник без цього права побачить лід лише ПІСЛЯ призначення, тож якщо фірма «не бачить лідів з автоматизації», перевір список в особи, що керує лідами, а не в продавця.

Коди відповідей

1. 1201 — лід збережено.
2. 2200 — цей самий запит уже раніше вдався (розпізнано за Idempotency-Key), новий лід не створено.
3. 3400 — помилка в даних: щось не проходить перевірку або Teodo отримало поле, якого не обробляє. Відповідь вказує, яке поле.
4. 4401 — ключ неправильний або анульований. Створи новий у Налаштування → Інтеграції.
5. 5403 — модуль лідів вимкнено в Teodo або ліцензія фірми закінчилась.
6. 6413 — дані, які надсилаєш, завеликі (ліміт 16 КБ). Трапляється при довгій нотатці разом із кількома іншими полями — скороти текст у полі notes.
7. 7422 — цей контакт (телефон або пошта) заявив заперечення проти контакту. НЕ повторюй цей запит — це не збій, а відмова в записі.
8. 8429 — автоматизація надсилає більше запитів, ніж дозволяє ліміт на годину. Зачекай час, вказаний у заголовку «Retry-After».