Planado API

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

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

Эта документация — перевод английской версии. Версия на английском может содержать дополнительные сведения.

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

REST API доступен через протокол HTTPS по адресу api.planadoapp.com. Все запросы к 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.planadoapp.com/v2/jobs
{"job_uuid":"8070f98d-b3f6-4cc8-b7c4-54b6709cd98b"}

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

$ curl -H "Authorization: Bearer api-key" https://api.planadoapp.com/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 имеет ограничение на количество запросов — не более 60 в минуту. Запросы, превышающие этот лимит, получат ошибку 429 в ответ.

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

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

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

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

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

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

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