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

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

$ 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" | 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 поддерживают резолюции.

См. также