API приёма заявок

Как сайт или агрегатор отправляет заявки в PravoCRM — адрес, токен, поля, ответы и ограничения.

Сайт фирмы, агрегатор или рекламная площадка отправляет заявки в PravoCRM запросом к API. Страница — для разработчика, который подключает сайт: передайте ему ссылку на неё вместе с токеном.

Что нужно

Источник заявок типа «API» — Источники заявок.
Токен этого источника — «Выпустить токен» на вкладке «API-токены» страницы источника. Токен показывается один раз, скопируйте его сразу.

Нужно право: «Выпускать API-токены источников»

Заявка попадает в тот источник, которому принадлежит токен.

Токен — ключ к приёму заявок от имени вашей фирмы. Передавайте его только в заголовке запроса с сервера сайта и не публикуйте в коде страниц: его увидит любой посетитель. Если токен попал в чужие руки — отзовите его и выпустите новый.

Запрос

Метод: POST
Адрес: https://api.undefined/v1/provider/order
Заголовок Authorization: Bearer <токен>
Тело — JSON с заголовком Content-Type: application/json; ответ в JSON приходит при Accept: application/json

curl -X POST 'https://api.undefined/v1/provider/order' \
  -H 'Authorization: Bearer <токен>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone": "+7 900 000-00-01",
    "name": "Иван Петров",
    "location": "Москва",
    "text": "Нужна консультация по договору",
    "utm_source": "yandex",
    "utm_medium": "cpc",
    "utm_campaign": "bankrotstvo_msk"
  }'

Поля заявки

Поле	Обязательное	Что передать
`phone`	Да	Телефон клиента в любом формате, до 255 символов. Номер приводится к единому виду после приёма
`location`	Да	Город или регион клиента текстом, до 255 символов. Регион определяется после приёма по настройке источника
`name`	Нет	Имя клиента, до 255 символов
`text`	Нет	Текст заявки, вопрос клиента, до 5000 символов
`utm_source`	Нет	Метка источника трафика, до 255 символов
`utm_medium`	Нет	Метка типа трафика
`utm_campaign`	Нет	Метка рекламной кампании
`utm_content`	Нет	Метка объявления
`utm_term`	Нет	Метка ключевого слова

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

Ответы

Код	Что значит
201	Заявка принята. В ответе — её идентификатор
401	Токен не передан, неверный, просрочен или отозван, либо источник выключен или удалён
403	Аккаунт заблокирован — заявки не принимаются
422	Ошибка в полях: в `errors` — поля и причины
429	Превышен лимит запросов — повторите позже

Заявка принята:

{
  "id": "9b1d6f2e-0000-0000-0000-000000000000"
}

Ошибка в полях:

{
  "message": "Поле обязательно.",
  "errors": {
    "phone": ["Поле обязательно."]
  }
}

Ответ 201 значит, что заявка сохранена. Телефон и регион разбираются уже после ответа: если номер не распознан, заявка всё равно появится в кабинете с пометкой об ошибке обработки — Автоматическая обработка.

Лимиты

120 заявок в минуту на источник;
с неверным токеном — 10 запросов в минуту с одного адреса.

При превышении приходит 429: подождите минуту и повторите.