Инструкция к API LawTask CRM

Artem

Инструкция о том, как передавать лиды напрямую в API LawTask CRM.

Инструкция предназначена для разных целевых аудиторий. Вы наверняка сможете разобраться без специальных знаний в предметной области. Если у вас есть техники, передайте её им вместе с идентификационным номером.

Искусственный интеллект GPT последней версии был дообучен на этой документации чтобы стать эффективным помощником в настройке. Вы можете использовать ассистента для помощи в настройке.

Для быстрой навигации по документации воспользуйтесь оглавлением.

Оглавление:

адрес приёма лидов
обязательные поля
необязательные поля
получение ответа
примеры кода и объяснение логики
Tilda, WordPress и другие конструкторы сайтов
Telegram
ручной ввод заявок
отправка заявок почтой
импорт лидов через таблицы
консольные утилиты, тестирование
контроль качества лидов

Адрес приёма лидов

Наш адрес для получения лидов:

https://lawtask.pro/API/api.php

Передавать данные необходимо POST методом. Желательно указывать заголовок Content-Type: application/x-www-form-urlencoded и использовать HTTPS протокол. Подробнее о заголовках.

В теле запроса необходимо передать объект с параметрами лида и технической информацией.

Обязательные поля

{
  integration_id: integer,
  city: string,
  phone: integer | string,
  situation: string
}

integration_id — ID этой интеграции. Этот ID мы создаём на своей стороне и передаём поставщику лидов. Если у вас нет этого ID - запросите его у нас. Это важный параметр, по нему мы определяем отправителя, конечного получателя и прочее. Максимум, 30 символов. Целочисленное. Например, 12345

city — город лида. В большинстве случаев, можно передать любую строку, потому что город мы определим исходя из ID интеграции. Но иногда это невозможно. Для надёжности, следует передать действительный город лида. И лучше его захардкодить, потому что «деревня такая-то» не поймём и сочтём за ошибку. Максимум, 70 символов. Строка. Например, 'Лондон'.

phone — номер телефона лида в любом формате. Максимум, 30 символов. Целочисленное или строка. Надёжнее использовать строки. Если телефонов несколько, то можно передать их через / или передать только один номер, а остальные передать в поле situation. Например, '1234567890'.

situation — текст заявки (что произошло, какая помощь нужна) в свободной форме. Поле является обязательным, потому как отсутствие описания проблемы лида является ошибкой для большинства случаев. Однако, если у вас нет этой информации, то можете передать в этом поле любую строку. Некоторые поставщики лидов также используют это поле для передачи своей отладочной информации, такой как ID своего собственного поставщика. Лучше не использовать RTF, HTML или MD разметку, потому как в итоге человеку это будет представлено в plan text. Максимум, 3500 символов. Строка. Например, 'Нет описания проблемы. Поток 123.'

Необязательные поля

{
  name: string,
  lead_id: integer | string
  test: string
  meeting_date: string
}

Необязательные поля можно вообще не указывать или указывать пустые строки.

name — имя лида в свободной форме. Если имени нет, лучше вообще не передавать этот параметр, но можете отправить что-то вроде ''Инкогнито''. Максимум, 250 символов. Например, 'John Doe'.

lead_id — идентификатор лида в вашей базе данных по вашей системе исчисления. Старайтесь передать его, если можете. Так станет проще ориентироваться: понимать какие лиды уже отправлены и предметно говорить, «лид 12345 - брак». Кроме того, так вы сможете получать обратную связь со статусами лидов автоматически. Если ничего не передать, то мы сгенерируем свой ID для лида и возвратим его в ответе. Если повторно передать лид с тем же ID что и раньше, то дубликат не будет принят. Строка или целочисленное. Максимум, 30 символов. Например, 123LD45.

test — цель запроса только тест. Идеально для тестов и отладки, когда достаточно убедиться что настройки верны не внося никакие изменения в базы данных. Тогда, полученный от вас лид пройдёт все проверки на валидность и вы получите полноценный ответ, но лид не будет сохранён. Можно использовать это и для автоматического тестирования. А в production режиме не передавать этот параметр вовсе. Например, false (boolean).

meeting_date — дата назначенной встречи по местному времени лида. Можно передать timestamp в формате Y-m-d H:i:s если вы предоставляете не просто заявку, а уже назначенную встречу. Например, 2025-12-29 17:00:00.

Получение ответа

В ответ на запрос с лидом мы отправляем JSON объект (Content-Type: application/json;charset=utf-8) с результатами его получения:

{
  result: boolean,
  code: integer,
  reason: string,
  data?: object | string
}

result — true в случае если лид успешно принят или тест завершился успешно. Во всех остальных случаях - false.

code — http код ответа. 201 = лид успешно принят и сохранён. 200 = тест завершился успешно. 4xx ошибки свидетельствуют о проблемах с вашей стороны (не задан обязательный параметр, например). 5xx ошибки свидетельствуют о проблемах на принимающей (нашей) стороне (например, тех. работы на сервере).

reason — человекочитаемое описание результата / ошибки.

data — объект с полученными от вас данными (показываем что получили на вход) или строка "false", если это не требуется.

Стремимся получить в ответ код 201 (лид успешно принят и сохранен) или 200 (с лидом всё в порядке, тест завершен успешно).

Если в процессе приема появятся ошибки, в ответе будет изложено что пошло не так. Например, если мы не укажем обязательный параметр integration_id, то получим следующий ответ:

Таким образом,

по result: false видим, что лид не был принят или сохранён.
code: 400 свидетельствует о том, что причина ошибка со стороны отправителя.
В reason: 'Error 002 .... человекочитаемое описание ошибки.
В data: {...} то что было получено от вас. И действительно, в графе integration_id ничего не передано.

Часто встречается такая ошибка:

Error 001: Nothing has been received. Try POST method and check request body

Эта ошибка, возникает по следующим причинам:

или используется неверный метод. Нужен именно POST;
или используется неверный заголовок. Нужен именно Content-Type: application/x-www-form-urlencoded;
или вообще не передаётся тело запроса.

В сухом остатке, рекомендуется проверять следующее:

если не пришёл ответ — вероятно есть какая-то сетевая проблема. Считаем, что лид не был принят.
если ответ пришёл, но result != true (boolean), то лид не был принят, а ошибку можно прочитать в поле reason.

Примеры кода и объяснение логики

Нам нужно отправить информацию переданную лидом вместе с технической информацией в наш API.

Это типичная задача для интернета: обычный сетевой запрос из А в Б с набором параметров. Не требуется специальная техника, проприетарное программное обеспечение, оплата посредникам и т.п. Весь интернет во всём его многообразии давно использует эту механику для обмена информацией.

HTML

Начнём с одного только каркаса формы. Пример формы на чистом HTML, которая содержит всё необходимое для отправки лида. GitHub.

Такой формы без всякого JS и серверной обработки минимально достаточно. Это обычная, валидная по W3C форма, в которой есть всё что требуется. Ключевыми атрибутами являются:

action="https://lawtask.pro/API/api.php"

(передать заполненную форму на обработку на этот адрес)

и method="post" (использовать POST метод для передачи)

В самих полях, атрибуты name соответствуют ожидаемым нами полям (phone, name, situation и т.п.). Соответственно, при отправке автоматически формируется массив с нужными парами ключ-значение.

Таким образом, при сабмите (отправке) формы, все необходимые данные передаются нам напрямую в API стандартными средствами браузера самого лида прямо с frontend без JS и северной обработки.

Но у такого метода есть ряд недостатков: в частности, пользователь попадет в итоге на техническую страницу CRM. Скорее всего, он подумает, что всё сломалось и пойдет искать в сети другой сайт или заново заполнять форму.

Поэтому, вместо того, чтобы передавать данные сразу при нажатии на кнопку "отправить", лучше сперва обработать их на своей стороне, показать пользователю ошибки, помочь заполнить форму и показать уведомление с результатами отправки. Сделать это можно, если мы добавим к форме ещё обработку на JavaScript.

Пример кода на чистом JS, который ищет на странице форму и навешивает на неё функцию отправки лидов напрямую в API. Он подменяет собой штатное поведение браузера: позволяет управлять процессом, не перенаправлять пользователя. Серверная обработка при этом не требуется. Для упрощения, в примере нет ничего про валидацию формы и визуальному отображению результатов отправки фирмы пользователю. Если адаптировать пример под вашу конкретную страницу сайта, то этого уже достаточно для полноценной отправки лида.

PHP

Совсем классно будет, если мы добавим серверную обработку перед отправкой. Пример кода на PHP8 для отправки лида в API. Данный скрипт собирает лид и нужные тех. данные, проверяет их валидность и консистентность, отправляет лида в API и проверяет результат. Серверная обработка открывает нам доступ к новым возможностям. Например, добавить базу данных для хранения лидов перед их отправкой или собирать статистику. Это проще всего делать на своём же сервере.

Пример кода страницы на HTML + CSS + JS + PHP. В данном примере уже добавлено базовое стилистическое оформление, валидация полей, анимация отправки формы и т.д.

Демонстрация формы. Только имя заполнено, поэтому форма не может быть отправлена.

При желании, в рамках этого же скрипта можно реализовать подсказку с маской номера телефона, автоматическое форматирование, валидацию по мере ввода текста, проверку на спам и т.п.

При написании своих скриптов, обратите внимание, что надёжнее всего указывать заголовок Content-Type: application/x-www-form-urlencoded (отправка формы). Подробнее о заголовках.

Tilda, WordPress и другие конструкторы сайтов

Не пугайтесь если у вас какой-то нестандартный сайт, форма или программа. Почти гарантировано, вашу систему можно настроить для отправки лидов напрямую в API без посредников, платного софта и т.п. Часто даже не требуется привлекать программиста для настройки. Самая большая сложность, обычно, в том чтобы понять логику процесса.

WordPress — в большинстве случаев, вам достаточно будет PHP или JS скрипта из раздела примеры кода и объяснение логики. Официальных плагинов не существует.
Tilda — для вас подготовлена отдельная инструкция по этой ссылке.
Другие конструкторы сайтов — во всех известных случаях, достаточно слегка адаптировать пример JS скрипта из раздела примеры кода и объяснение логики так чтобы навесить на форму дополнительную логику по отправке лида. Как правило, конструкторы предоставляют свою документацию по теме того как подключить свой скрипт на страницу. Чаще всего, идея заключается в том, что на странице добавляется ещё один пустой блок, который содержит только код. Он как будто бы никак не связан с формой приема заявок. Но сам код при запуске находит форму на странице.

Рассмотрите, также, возможность отправки лидов через Telegram и ручной ввод заявок.

Если у вас есть возможность не использовать конструкторы сайтов — лучше их не использовать.

Возможна пересылка лидов через телеграмм. Работает это следующим образом:

1. Создаём рабочую группу или канал для лидов. Обучаем наш бот понимать ваши лиды (требуются образцы). Процесс подстройки очень быстрый.

2. Вы (вручную или с помощью бота) отправляете в канал лиды.

3. Наш бот читает все сообщения в канале и пытается найти в них лидов. Если находит, пишет что именно нашел, отправляет лид нам в API и уведомляет о результатах.

Демонстрация работы бота по распознанию лидов

Такой вариант выглядит простым, но на самом деле мы усложняем систему добавлением нового звена (телеграмм). Кроме того, появляется риск того, что бот не сумеет распознать нестандартного лида в сообщении. Поэтому, этот способ интеграции хотя и возможен, не является предпочтительным.

Кроме того, согласно политике Telegram, взаимодействие между ботами возможно только в каналах. Внутренняя механика работы бота в группах и в каналах разная. Есть вероятность того, что ваш бот умеет работать в группах, но не умеет в каналах. Вы можете проверить это самостоятельно: попробуйте настроить бот так, чтобы он мог отправлять лид в канал. Если получилось, значит всё в порядке.

Ручной ввод заявок

Для поставщиков лидов существует специальный веб-интерфейс (сайт). В нём можно вручную вводить лиды в систему. Интерфейс простой, никаких настроек с вашей стороны не потребуется. Кроме того, вы получите доступ к статистике. Подробнее в разделе контроль качества лидов. Обратитесь к нам за получением данных для входа.

Отправка заявок почтой

Импорт лидов через электронную почту не предусмотрен. Это теоретически возможно, но практически нецелесообразно в связи сопутствующими накладными расходами. Рассмотрите другие варианты отправки лидов, если это возможно.

Импорт лидов через таблицы

Есть возможность импортировать лидов через обычные CSV или Excel таблицы. Однако, такой импорт требует ручной донастройки под формат конкретной таблицы, поэтому способ не является предпочтительным, если речь не идет о десятках и сотнях тысяч лидов.

Импорт лидов из таблиц Google (Google Sheets) возможен, но не является предпочтительным.

Консольные утилиты, тестирование

Для начала попробуем отправить какой-нибудь запрос с нашей машины в API. Если мы просто откроем адрес API в браузере, то увидим ошибку. Всё дело в том, что при открытии страницы в браузере используется метод GET. А нам нужен POST. Обычно, метод Get используется для получения информации, а Post для её отправки. Т.е. нам нужна какая-то другая программа, которая умеет отправлять информацию через сеть также как браузер нам помогает её читать.

Такие программы уже давно написаны и так распространены, что часто идут предустановленными в штатном комплекте программ в составе консольных утилит. Попробуем отправить лида из терминала и специальной утилиты.

Пример отправки лида с помощью консольной утилиты https://httpie.io/:

```shell
http --form --verbose POST https://lawtask.pro/API/api.php \
integration_id=1234 \
phone='+123456789' \
name='John Doe' \
situation='Need juridical help with...' \
city='London' \
lead_id:=1234567 \
test='true'
```

Демонстрация работы HTTPie.io. Терминал Warp. Тема Nord.

Пример отправки лида с помощью GUI утилит:

Как видим, это всё работает даже без сайта и сервера с нашего локального компьютера.

Контроль качества лидов

Существует специальный интерфейс для поставщиков лидов, предназначенный для контроля качества их лидов. В нем можно увидеть статистку по всем вашим потокам с указанием текущих статусов лидов. Обратитесь к нам за получением данных для входа в веб интерфейс.