Список нарядов

Наряды упорядочены от самых новых к самым старым.

$ curl -H "Authorization: Bearer api-key" https://api.planadoapp.com/v2/jobs | jq
{
  "jobs": [
    {
      "uuid": "137eafeb-15d1-6480-022b-0ec4617ba21a",
      "external_id": "job",
      "external_order_id": "crm-deal-678190454834217",
      "serial_no": 22469,
      "status": "scheduled",
      "scheduled_at": "2019-11-20T06:25:00",
      "scheduled_duration": {
        "minutes": 60
      },
      "template_uuid": "e6fb6e46-21a7-4d1e-abec-19e5e7dcdb43",
      "client_uuid": "298b4eca-757a-5296-9078-a9991942704f",
      "site_uuid": "eb5140ea-d635-45a3-ad77-6750a995c126",
      "type_uuid": "9898b1d8-a04b-4073-a08e-b470f029fdb2",
      "assignee": {
        "worker_uuid": "4132ed05-3b6d-456c-b3ef-ee1cc6af1e90"
      },
      "skill_uuids": ["a1620b1d-257d-49a9-9adf-6e958603c571"],
      "territory_uuid": "70f19e99-d3e3-4366-8bd9-2f1c8c8c784a",
      "initial_job_uuid": "89b5ab82-5637-4bde-91bc-7dd844ccbaef",
      "completion_of_uuid": null,
      "version": 5,
      "created_at": "2016-05-29T17:31:01.419601Z",
      "updated_at": "2016-06-07T10:57:19.529209Z"
    },
    ...
  ]
}

Table 1. Поля элементов `jobs`
Поле	Тип	JSON-тип	Может быть `null`	Описание
`uuid`	UUID	Строка	Нет	Уникальный идентификатор
`external_id`	Строка	Строка	Да	Внешний идентификатор
`external_order_id`	Строка	Строка	Да	Внешний идентификатор заказа
`serial_no`	Целое	Число	Нет	Номер наряда
`status`	Строка	Строка	Нет	Состояние наряда
`scheduled_at`	Дата и время	Строка	Да	Планируемое время начала наряда
`scheduled_duration`	Длительность	Строка	Да	Планируемая длительность наряда
`description`	Строка	Строка	Да	Описание наряда. Ограничено 15000 символов
`assignee`	UUID исполнителя	Объект	Да	Исполнитель — пользователь или бригада
`type_uuid`	UUID	Строка	Нет	Идентификатор типа наряда
`template_uuid`	UUID	Строка	Да	Идентификатор шаблона
`client_uuid`	UUID	Строка	Да	Идентификатор клиента
`site_uuid`	UUID	Строка	Да	Идентификатор объекта
`contacts`	[Контакт]	Массив	Нет	Список контактов
`territory_uuid`	UUID	Строка	Да	Идентификатор участка
`skill_uuids`	[UUID]	Массив	Нет	Список идентификаторов навыков
`initial_job_uuid`	UUID	Строка	Да	Ссылка на первый связанный наряд
`completion_of_uuid`	UUID	Строка	Да	Ссылка на первый наряд, который этот наряд завершает
`version`	Целое	Число	Нет	Version
`created_at`	Таймстемп	Строка	Нет	Время создания
`updated_at`	Таймстемп	Строка	Нет	Время последнего обновления

Фильтры

Планадо позволяет фильтровать наряды по значениям некоторых полей. Поддерживаемые поля и примеры приведены далее.

Table 2. Поля и типы данных
Field	Type	Description
`updated_at`	Таймстемп	Соответствующая метка времени. Используйте `before` и `after`, чтобы указать интервал
`scheduled_at`	Таймстемп
`assignee`	UUID исполнителя	Ссылка на исполнителя
`external_order_id`	String	Внешний идентификатор наряда
`client`	Клиент	Ссылка на клиента
`site_uuid`	UUID	UUID объекта
`initial_job_uuid`	UUID	UUID первого наряда среди связанных нарядов
`completion_of_uuid`	UUID	UUID первого наряда с тем же шаблоном среди связанных нарядов
`status`	[String]	Элементы могут принимать значения: `posted`, `scheduled`, `published`, `canceled`, `en_route`, `started`, `suspended` или `finished`
`resolution`	[UUID резолюции]	`finished` или `canceled` вместе с UUID

Эти фильтры могут быть скомбинированы для использования в более конкретных и сложных случаях. Далее следует несколько примеров.

В следующих примерах было добавлено несколько разрывов строки, чтобы повысить наглядность. В действительности URL должна быть написана в одну строку.

Отмененные наряды работника у определенного клиента

$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs
    ?assignee[worker_uuid]=138b2e36-2b6b-6c50-6f69-26c43ed9b2b0
    &client[uuid]=139b71ac-992a-6e20-d683-6a71902902ea
    &status[]=canceled" | jq
{
  "jobs": [...]
}

Наряды, запланированные на бригаду в определенный промежуток времени

$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs
    ?assignee[team_uuid]=13871a50-0c21-6db0-e26c-5ad29ae5a3b0
    &scheduled_at[after]=2022-01-01T00:00:00Z
    &scheduled_at[before]=2022-05-01T00:00:00Z" | jq
{
  "jobs": [...]
}

Промежуток времени не может быть больше 50 дней.

Наряды, завершенные в определенный промежуток времени

$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs
    ?finished_at[after]=2022-01-01T00:00:00Z
    &finished_at[before]=2022-02-01T00:00:00Z" | jq
{
  "jobs": [...]
}

Список связанных нарядов, которые выполняются в данный момент

$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs
    ?initial_job_uuid=139ed223-8001-6a90-b795-2cde48001122
    &status[]=started" | jq
{
  "jobs": [...]
}

Совместное использование статусов и резолюций

$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs
    ?status[]=en_route
    &resolution[finished][]=1395596e-d044-6ed0-5b26-7a1a1b701773
    &resolution[canceled][]=14b89ff7-992e-436f-aa74-3f4e2a0ffe08" | jq
{
  "jobs": [...]
}

По значениям updated_at или scheduled_at

$ curl -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?updated_at[before]=2019-10-01T10:30:10Z&updated_at[after]=2019-09-30T10:30:10Z" | jq
{
  "jobs": [...]
}

before и after используют строгое сравнение. Наличие обоих значений опционально.

По team_uuid исполнителя

$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?assignee[team_uuid]=1003e595-8d42-4150-af7c-65471ea6ca3f" | jq
{
  "jobs": [...]
}

По worker_uuid исполнителя

$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?assignee[worker_uuid]=2d3716c1-4a5f-4619-966c-bd31eb255880" | jq
{
  "jobs": [...]
}

По значению external_order_id

$ curl -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?external_order_id=order12345" | jq
{
  "jobs": [...]
}

По uuid клиента

$ curl -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?client[uuid]=139cd1f4-b6f4-6a50-d9f6-7a1c0ed35d03" | jq
{
  "jobs": [...]
}

Можно использовать как client[uuid], так и client_uuid.

По external_id клиента

$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?client[external_id]=company1" | jq
{
  "jobs": [...]
}

По значению site_uuid

$ curl -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?site_uuid=139446fc-38cf-6cf0-b199-12b7bdb9b0f2" | jq
{
  "jobs": [...]
}

По значению initial_job_uuid

$ curl -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?initial_job_uuid=1395f23e-8b10-6620-01dd-06a9499c9a2c" | jq
{
  "jobs": [...]
}

По значению completion_of_uuid

$ curl -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?completion_of_uuid=1395f23f-5cdb-6cc0-7bc1-66da105d8854" | jq
{
  "jobs": [...]
}

Различие между initial_job_uuid и completion_of_uuid заключается в том, что первое представляет собой самый ранний наряд среди всех связанных нарядов, в то время как последнее ссылается на самый ранний наряд по тому же шаблону.
На диаграмме ниже UUID Initial job является initial_job_uuid для всех представленных связанных нарядов. Что касается completion_of_uuid, то Linked job 1 ссылается на Initial job, в то время как Linked job 2 на Linked job with different data.

 --------------------                              --------------------
|    Initial job     |        New template        |  Linked job with   |
|                    | -------------------------> |   different data   |
|     Template 1     |                            |     Template 2     |
 --------------------                              --------------------
          |                                                 |
          |  Completion job                                 |  Completion job
          |                                                 |
          V                                                 V
 --------------------                              --------------------
|    Linked job 1    |                            |    Linked job 2    |
|                    |                            |                    |
|     Template 1     |                            |     Template 2     |
 --------------------                              --------------------

По статусам

$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?status[]=finished&status[]=en_route"
{
  "jobs": [...]
}

Статусы передаются в Планадо в виде массива строк.

По резолюциям

$ curl -g -H "Authorization: Bearer api-key" "https://api.planadoapp.com/v2/jobs?resolution[finished][]=1395596e-d044-6ed0-5b26-7a1a1b701773&resolution[finished][]=14b89ff7-992e-436f-aa74-3f4e2a0ffe08&resolution[canceled][]=14b89ff7-992e-436f-aa74-3f4e2a0ffe08" | jq
{
  "jobs": [...]
}

Фильтрация по статусам и резолюциям представляет собой более сложный случай. Значения передаются в виде объекта, форма которого приведена ниже.

Table 3. Поля `resolution`
Поле	Тип	Обязательно	Описание
`finished`	[UUID]	Нет	Если предоставлено, будет дополнительно ограничивать результаты поиска до тех нарядов, которые используют переданные резолюции
`canceled`	[UUID]	Нет

Дополнительно указывать фильтр status необязательно, если запрос уже содержит фильтр по резолюции соответствующего типа.

Только статусы finished и canceled поддерживают резолюции.

См. также

Пагинация