Planado Webhooks

Planado использует вебхуки для отправки уведомлений об изменениях нарядов и клиентов через HTTP.

В разделе «Настройки» → «Интеграции» настраиваются подписки на события и URL, на который будет отправлен POST запрос с информацией.

Вебхуки не отправляются на события, созданные через API.

Мы перерабатываем вебхуки.

С момента их появления в Planado, многое изменилось. Мы добавляли новые возможности и перерабатывали старые, и текущая версия вебхуков устарела.

Наши планы на новую версию:

  • Улучшить доставку вебхуков
  • Добавим объекты
  • Обновим информацию о нарядах и клиентах

Типы событий

Наряды

Название Описание
job_created Наряд создан
job_removed Наряд удален
job_updated Наряд обновлен

Состояния нарядов

Название Описание
job_posted Наряд размещен
job_assigned Наряд назначен
job_scheduled Наряд запланирован
job_published Наряд опубликован
job_en_route Наряд в пути
job_started Наряд начат
job_suspended Наряд приостановлен
job_finished Наряд завершен

Клиенты

Название Описание
client_created Клиент создан
client_updated Клиент обновлен
client_removed Клиент удален

Тело вебхука (payload)

Информация о событии передается в формате JSON. Тело вебхука зависит от типа события. Всегда присутствуют два поля: author (источник события) и event_type (тип события).

Структура author:

{
    "author": {
        "application": "web",
        "name": "John Doe",
        "email": "johndoe@example.com",
        "device_id": "1302131000",
        "device_uid": "123e4567-e89b-12d3-a456-426655440000"
    },
    "event_type": "job_created",
    ...
}
Поле Описание
application Какой сервис сгенерировал событие. Возможные значения: web, mobile, api, background, internal
name Имя пользователя
email Email пользователя
device_id Идентификатор устройства в Planado
device_uid UID устройства
process Процесс, сгенерировавший событие. Присутствует только если applicationbackground

Поля name и email добавляются только для событий из web и mobile. Для событий для mobile доступны поля device_id и device_uid.

Наряды

{
    "status":"published",
    "address":{
        "floor":null,
        "apartment":null,
        "formatted":"Newroad near By Pepalbot",
        "description":"Go to the blue lamppost. Next turn is yours",
        "entrance_no":null
    },
    "type_id":17277820751,
    "client_id":17384664751,
    "serial_no":193,
    "cell_phone":"9860945156",
    "description":"New Connection Clear TV Only",
    "external_id":null,
    "scheduled_at":"2018-03-13T08:00:00+00:00",
    "custom_fields":[
        {
            "name":"Remarks",
            "value":"",
            "type_id":17312693751,
            "field_id":17339548751,
            "filled_at":null
        }
    ],
    "resolution_id":null,
    "external_order_id":null,
    "resolution_comment":null,
    "assignee_subject_id":17278721751,
    "available_on_device":true,
    "available_for_workers_ids":[
        17278721751
    ]
}
Поле Тип Описание
external_id string | null Внешний идентификатор наряда
external_order_id string | null Внешний идентификатор сделки
serial_no number Номер наряда
type_id number | null Идентификатор типа наряда
client_id number | null Идентификатор клиента
scheduled_at string | null Запланированное время наряда в формате ISO 8601
assignee_subject_id number | null Идентификатор сотрудника или бригады
cell_phone string | null Номер мобильного телефона
description string | null Описание наряда
status string | null Состояние наряда
address object Адрес наряда
custom_fields array Дополнительные поля
resolution_id number | null Идентификатор резолюции
resolution_comment string | null Примечание
available_on_device bool Отображается ли наряд в мобильном приложении
available_for_workers_ids array(number) Сотрудники, которым доступен наряд
previous object Предыдущее состояние наряда. Существует только для job_updated.

Адрес

{
    "floor":null,
    "apartment":null,
    "formatted":"Newroad near By Pepalbot",
    "description":"Go to the blue lamppost. Next turn is yours",
    "entrance_no":null
}
Поле Тип Описание
formatted string | null Строка адреса (г. Москва, ул. Тверская, 3)
apartment string | null Квартира или офис
floor string | null Этаж
entrance_no string | null Подъезд
description string | null Описание адреса

Дополнительные поля

[
  {
    name: "Price",
    value: "",
    type_id: 16255114051,
    field_id: 15700951051,
    filled_at: null
  },
  {
    name: "Circuit",
    value:
      "https://planado.s3.amazonaws.com/59051000/15700954051/8e9acf098f5e3bc1cf6509d68a2e6b0f9b8d0810/2.jpg",
    type_id: 16310155051,
    field_id: 15700953051,
    filled_at: null
  }
];
Поле Тип Описание
field_id number Идентификатор поля
type_id string Идентификатор типа поля
value string | null Значение поля
filled_at string | null Когда было заполнено поле (в формате ISO 8601)
name string Название дополнительного поля

Клиенты

{
    "name":"Инна Степанівна Старостишина",
    "company":false,
    "contacts":{
        "email":"example@example.ru",
        "cell_phone":"380005553535",
        "work_phone":""
    },
    "last_name":"Старостишина",
    "first_name":"Инна",
    "external_id":"243177",
    "middle_name":"Степанівна",
    "company_name":null,
    "organization":false,
    "site_address":{
        "floor":"",
        "apartment":"267",
        "formatted":"Кремль, Россия",
        "description":"",
        "entrance_no":"",
        "geolocation":{
            "latitude":50.4686663,
            "longitude":30.603064
        }
    },
    "organization_name":null
}
Поле Тип Описание
name string Полное имя клиента
organization bool Признак юридического лица
first_name string | null Имя клиента. Не заполняется у юридического лица.
middle_name string | null Отчество клиента. Не заполняется у юридического лица.
last_name string | null Фамилия клиента. Не заполняется у юридического лица.
organization_name string | null Название организации. Не заполняется у физического лица.
contacts object Контакты
site_address object Адрес
external_id string | null Внешний идентификатор

Адрес

{
    "floor":"",
    "apartment":"267",
    "formatted":"Кремль, Россия",
    "description":"",
    "entrance_no":"",
    "geolocation":{
        "latitude":50.4686663,
        "longitude":30.603064
    }
}
Поле Тип Описание
formatted string | null Строка адреса (г. Москва, ул. Тверская, 3)
apartment string | null Квартира или офис
floor string | null Этаж
entrance_no string | null Подъезд
description string | null Описание адреса
geolocation object | null Географическая точка адреса.
Состоит из двух полей:
  • longitude (долгота)
  • latitude (широта)

Контакты

{
    "email":"example@example.ru",
    "cell_phone":"380005553535",
    "work_phone":""
}
Поле Тип Описание
email string | null Электронная почта
cell_phone string | null Мобильный телефон
work_phone string | null Мобильный телефон

Generated by aglio on 27 Mar 2018