Planado API

Почти ко всем сущностям, присутствующим в системе, Планадо предоставляет доступ через REST API. В дополнение к этому, Планадо может отправлять уведомления при обновлении данных в нарядах, клиентах или объектах через механизм вебхуков. Например, в момент начала наряда отправляется HTTP-запрос на ваш сервер. Механизм вебхуков гарантирует доставку, если сервер был недоступен или ответил ошибкой.

API также описано в соответствии со стандартом OpenAPI. Интерактивный сайт позволяет авторизовываться в системе, посылать реальные API-запросы, а также предоставляет клиенты для различных языков программирования и фреймворков.

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

Отправка запросов

REST API доступен через протокол HTTPS по адресу api.planado.ru. Все запросы к API должны содержать API-ключ в HTTP-заголовке Authorization. Ключ доступен на странице Настройки → Интеграции → API. Нажмите на кнопку 🔄, если поле с ключом пустое.

Заголовок Authorization должен включать тип аутентификации. API Planado использует тип "Bearer". Например, ключ 817cc478 должен передаваться в формате Bearer 817cc478.

Тела запросов и ответов передаются в JSON-формате.

Добавление наряда с помощью утилиты cURL. В примере api-key это значение API-ключа

$ curl -H "Authorization: Bearer api-key" \
       --data "{\"description\": \"Создано через API\"}" \
       https://api.planado.ru/v2/jobs
{"job_uuid":"8070f98d-b3f6-4cc8-b7c4-54b6709cd98b"}

Получение информации о наряде и форматирование ответа с помощью утилиты jq

$ curl -H "Authorization: Bearer api-key" https://api.planado.ru/v2/jobs/8070f98d-b3f6-4cc8-b7c4-54b6709cd98b | jq
{
  "job": {
    "uuid": "137ea8b4-a616-6c80-40fa-6600ec2e536c",
    "external_id": null,
    "serial_no": 22468,
    "status": "posted",
    "scheduled_at": null,
    "scheduled_duration_min": null,
    ...
  }
}

Коды ответов

Ответы API соответствуют HTTP стандарту. Коды в диапазоне от 200 до 299 включительно означают успешную обработку.

Коды 4xx соответствуют ошибкам клиента (неправильные параметры запроса, неверный API-ключ, превышение лимита запросов и т.п.). В этих случаях тело ответа содержит подробную информацию об ошибке.

5xx это внутренние ошибки сервиса. Если вы получили такую ошибку в ответе, вы можете попробовать повторить запрос позже или написать в поддержку Планадо, если проблема сохраняется. Мы автоматически отслеживаем все такие ошибки и оперативно их устраняем.

Ограничение на количество запросов

Чтобы обеспечить стабильную работу сервиса, API имеет ограничение на количество запросов — не более 120 в минуту. Запросы, превышающие этот лимит, получат ошибку 429 в ответ.

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

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

Мобильные уведомления

При обновлении нарядов Планадо отправляет уведомления на устройства выездных сотрудников. Чтобы уведомления не отправлялись, например в случае частых обновлений, вы можете добавить к запросу заголовок X-Planado-Notify-Assignees: false.

Опциональные ключи и `null`-значения

API различает отсутствующие ключи в запросе и null-значения. Например, если в запросе на обновление какое-то поле не передано в запросе, то оно не будет обновлено. Если же поле передано и его значение — null, то значение в Планадо будет обновлено на null.

Все схемы запросов, описанные в документации, включают информацию о допустимости null-значений в полях.

Нашли опечатку?

Пожалуйста, напишите нам, если вы заметили опечатку или у вас есть вопросы. Спасибо!