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

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

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

Автоматизації (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. 7county — повіт (наприклад, «proszowicki»)
8. 8commune — гміна (наприклад, «Proszowice»)
9. 9voivodeship — воєводство (наприклад, «śląskie»; написання без польських літер теж підійде)
10. 10notes — зміст звернення, зауваження клієнта
11. 11source — звідки прийшло звернення (наприклад, «Facebook»); якщо пропустиш, Teodo впише назву ключа
12. 12estimated_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 — лід збережено. Якщо e-mail, воєводство або сума прийшли в неправильному вигляді (наприклад, поштовий індекс у полі воєводства, e-mail без домену, сума словами), лід усе одно створюється: це поле лишається порожнім, а початкове значення потрапляє на початок нотатки ліда. Задовгий текст обрізається до ліміту (кінцівка втрачається), а список чи об’єкт у текстовому полі зберігається як текст. Кожне таке виправлення відповідь перелічує в «warnings».
2. 2200 — цей самий запит уже раніше вдався (розпізнано за Idempotency-Key), новий лід не створено.
3. 3400 — ліда не вдається зберегти: немає ні назви, ні телефону, ні e-mail, ні адреси (або єдиний наданий e-mail неправильний) чи надіслано поле лише для читання, наприклад assigned_to. Відповідь вказує, яке поле.
4. 4401 — ключ неправильний або анульований. Створи новий у Налаштування → Інтеграції.
5. 5403 — модуль лідів вимкнено в Teodo або ліцензія фірми закінчилась.
6. 6413 — дані, які надсилаєш, завеликі (ліміт 16 КБ). Трапляється при довгій нотатці разом із кількома іншими полями — скороти текст у полі notes.
7. 7422 — цей контакт (телефон або пошта) заявив заперечення проти контакту. НЕ повторюй цей запит — це не збій, а відмова в записі.
8. 8429 — автоматизація надсилає більше запитів, ніж дозволяє ліміт на годину. Зачекай час, вказаний у заголовку «Retry-After».

Контакти (SMS, дзвінок, пошта) на осі клієнта

Тим самим ключем автоматизація може вписувати контакти з клієнтом — наприклад, SMS зі шлюзу SMSAPI, нотатку з телефонної централі або лист. Запис потрапляє на вісь активності клієнта (або ліда), поруч з рештою історії.

1. 1Метод: POST. Адреса: https://teodo.pl/api/v1/activities. Заголовки як вище (Authorization, Content-Type, за бажанням Idempotency-Key).
2. 2channel — обов'язково: phone, sms, email, meeting або other.
3. 3phone або email — потрібне принаймні одне; за ним Teodo знаходить потрібну особу.
4. 4direction — in (від клієнта, за замовчуванням) або out (до клієнта).
5. 5occurred_at — рекомендовано: коли відбувся контакт, дата з годиною і часовим поясом (наприклад, 2026-09-30T14:05:00+02:00); не може бути з майбутнього. Без нього запис отримує момент, коли запит дійшов до Teodo — якщо Make повторить надсилання через кілька годин, контакт стане на осі із запізненням. Зіставляй тут дату повідомлення зі шлюзу SMS.
6. 6body — текст SMS або нотатка; subject — тема (наприклад, листа); contact_name — ім'я, використовується лише при створенні нового ліда.

Teodo шукає власника контакту по черзі: телефон клієнта, телефон контактної особи клієнта, пошта клієнта, наприкінці відкритий лід (за телефоном, потім за поштою). Запис потрапляє до першого знайденого.

Якщо нікого не знайде, Teodo створює нового ліда з цього контакту — з іменем з contact_name або номером/поштою, з джерелом відповідно до каналу (наприклад, «SMS») — і вписує контакт на його вісь. Відповідь тоді має lead_created: true.

Приклад сценарію Make: тригер «Webhooks → Custom webhook», підключений до сповіщення SMSAPI про вхідний SMS, потім модуль «HTTP → Make a request» на адресу /api/v1/activities з таким тілом (Idempotency-Key: ідентифікатор повідомлення з SMSAPI): Поля sms_from, sms_text і sms_date (мітка часу в секундах) — це назви з повідомлення SMSAPI про вхідний SMS; в іншого постачальника підстав його назви.

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

Відповідь показує, куди потрапив запис:

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

1. 1201 — запис збережено (lead_created показує, чи заодно створився новий лід).
2. 2200 — цей самий запит уже вдався (Idempotency-Key); повернено наявний запис, заголовок «Idempotency-Replayed: true». У повторі lead_created завжди false, навіть якщо перший запит створив ліда — дивись lead_id.
3. 3400 — помилка в даних, відповідь вказує поле.
4. 4422 — немає ні клієнта, ні ліда, а контакт заявив заперечення, тож новий лід не створено. Не повторюй.
5. 5503 — тимчасова помилка запису; повтори запит з тим самим Idempotency-Key.
6. 6Інші коди (401, 403, 413, 429) — як у розділі вище.