Planado REST API

Сервис предоставляет REST API, описание которого приведено ниже. Запросы к серверу должны быть аналогичны обычным HTTP-запросам браузера, за исключением необходимости передачи токена в заголовках запросов. Это означает, что для всех вызовов API необходимо установить заголовок запроса X-Planado-API-Token со значением вашего ключа API (ключ можно получить на странице настроек приложения).

Все запросы (POST/PATCH/DELETE) на изменение данных должны содержать заголовок Content-Type: application/json, а данные, соответственно, должны быть закодированы с помощью JSON.

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

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

HTTP-статусы успешных ответов сервера находятся в диапазоне от 200 до 299. Это можно использовать при обработке ответа.

Если для интеграции нужно получать уведомления об изменениях нарядов и клиентов, попробуйте вебхуки.

GET https://api.planadoapp.com/api/v1/jobs.json?page=4
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
    "jobs": [
        {
            "assignee_subject_id": 14001,
            "client_id": 427001,
            "site_id": null,
            "job_id": 5675001,
            "scheduled_at": "2015-03-15T20:15:00",
            "serial_no": 47,
            "status": "published",
            "template_id": 957001,
            "type_id": 6001
        },
        {
            "assignee_subject_id": 14001,
            "client_id": 427001,
            "site_id": 4976001,
            "job_id": 5665001,
            "scheduled_at": "2015-03-15T20:00:00",
            "serial_no": 46,
            "status": "started",
            "template_id": 1091001,
            "type_id": 35001
        },
        ...
    ],
    "view_url": "https://your-subdomain.planadoapp.com/jobs",
    "page": 1,
    "total_pages": 1
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "page": {
      "type": "number"
    },
    "total_pages": {
      "type": "number"
    },
    "view_url": {
      "type": "string"
    },
    "jobs": {
      "type": "array"
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Получение списка нарядов
GET/jobs.json{?page}

Список приходит частями, по 20 нарядов на странице. Ответ сервера содержит краткую информацию о нарядах. Сначала идут наряды без даты, затем начатые и запланированные. Наряды сортируются по дате.

Параметры URI
page
number

Размер страницы — 20 элементов.


POST https://api.planadoapp.com/api/v1/jobs.json
ЗапросС объектомДополнительные поляКонтактыЗагрузка файла
Заголовки
Content-Type: application/json
Тело сообщения
{
  "site_id": 11690603001,
  "external_id": "some_external_id"
}
Ответ201404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "job_id": 25302001,
  "status": "success"
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "job_id": {
      "type": "number"
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "template_id": 957001,
  "client_id": 427001,
  "assignee_subject_id": 14001,
  "custom_fields": [
    {
      "name": "Your Field Name",
      "value": "Field value"
    }
  ]
}
Ответ201404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "job_id": 25302001,
  "status": "success"
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "job_id": {
      "type": "number"
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "contacts": [
    {
      "type": "phone",
      "name": "Виталий",
      "value": "+7-458-543-54-56"
    },
    {
      "type": "phone",
      "name": "Ольга",
      "value": "655-432"
    }
  ]
}
Ответ201404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "job_id": 25302001,
  "status": "success"
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "job_id": {
      "type": "number"
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "template_id": 123456,
  "custom_fields": [
    {
      "name": "Название поля",
      "value": {
        "name": "file.txt",
        "base64_content": "SGVsbG8gd29ybGQhCg=="
      }
    }
  ]
}
Ответ201404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "job_id": 25302001,
  "status": "success"
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "job_id": {
      "type": "number"
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Создание наряда
POST/jobs.json

Для создания наряда по шаблону укажите его идентификатор template_id, тогда поля шаблона будут скопированы в наряд. Если идентификатор не указан, создается наряд без шаблона. Для создания наряда на объект передайте в теле JSON запроса ключ site_id. Ответ содержит результат запроса status и идентификатор наряда job_id.

При создании наряда можно заполнить дополнительные поля. Для поля типа «файл» используйте JSON-объект со следующими параметрами:

  • name — строка с именем файла

  • base64_content — строка с содержимым файла, закодированным в base64


GET https://api.planadoapp.com/api/v1/jobs/job_id.json
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
    "job": {
      "job_id": 121001,
      "external_id": '303dj3',
      "serial_no": 3,
      "template_id": null,
      "type_id": 56001,
      "status": "scheduled",
      "description": "Описание наряда",
      "client_id": null,
      "address": {
        "formatted": "г Москва, ул Тверская, д 13",
        "entrance_no": null,
        "apartment": null,
        "floor": null,
        "description": null,
        "geolocation": {
          "longitude": 37.216025,
          "latitude": 55.999757
        }
      },
      "scheduled_at": "2015-08-24T13:00:00",
      "scheduled_duration_min": 60,
      "assignee_subject_id": null,
      "possible_resolutions": [
        {
          "resolution_id": 58001,
          "name": "Выполнен",
          "successful": true,
          "comment_required": false
        },
        {
          "resolution_id": 59001,
          "name": "Не выполнен",
          "successful": false,
          "comment_required": false
        }
      ],
      "first_activity_at": null,
      "en_route_at": null,
      "started_at": null,
      "suspended_at": null,
      "finished_at": null,
      "en_route_min": null,
      "suspension_time_min": null,
      "actual_time_min": null,
      "custom_fields": [],
      "cell_phone": null
    },
    "url": "https://your-subdomain.planadoapp.com/jobs/121001"
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "job": {
      "type": "object",
      "properties": {
        "job_id": {
          "type": "number"
        },
        "serial_no": {
          "type": "number"
        },
        "template_id": {
          "type": [
            "number",
            "null"
          ]
        },
        "type_id": {
          "type": [
            "number",
            "null"
          ]
        },
        "assignee_subject_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "type": "string"
        },
        "client_id": {
          "type": [
            "number",
            "null"
          ]
        },
        "site_id": {
          "type": [
            "number",
            "null"
          ]
        },
        "external_id: `my_external_id`": {
          "type": [
            "string",
            "null"
          ]
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "address": {
          "type": "object",
          "properties": {
            "description": {
              "type": [
                "string",
                "null"
              ]
            },
            "apartment": {
              "type": [
                "string",
                "null"
              ]
            },
            "entrance_no": {
              "type": [
                "string",
                "null"
              ]
            },
            "floor": {
              "type": "string"
            },
            "formatted": {
              "type": [
                "string",
                "null"
              ]
            },
            "geolocation": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "latitude": {
                  "type": "number"
                },
                "longitude": {
                  "type": "number"
                }
              },
              "required": [
                "latitude",
                "longitude"
              ]
            }
          }
        },
        "scheduled_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "scheduled_duration_min": {
          "type": "number"
        },
        "possible_resolutions": {
          "type": "array"
        },
        "first_activity_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "en_route_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "started_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "suspended_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "finished_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "en_route_min": {
          "type": "number"
        },
        "suspension_time_min": {
          "type": "number"
        },
        "actual_time_min": {
          "type": "number"
        },
        "cell_phone": {
          "type": "string"
        },
        "started_location": {
          "type": "object",
          "properties": {
            "latitude": {
              "type": "number"
            },
            "longitude": {
              "type": "number"
            }
          },
          "required": [
            "latitude",
            "longitude"
          ]
        },
        "en_route_location": {
          "type": "object",
          "properties": {
            "latitude": {
              "type": "number"
            },
            "longitude": {
              "type": "number"
            }
          },
          "required": [
            "latitude",
            "longitude"
          ]
        },
        "suspended_location": {
          "type": "object",
          "properties": {
            "latitude": {
              "type": "number"
            },
            "longitude": {
              "type": "number"
            }
          },
          "required": [
            "latitude",
            "longitude"
          ]
        },
        "finished_location": {
          "type": "object",
          "properties": {
            "latitude": {
              "type": "number"
            },
            "longitude": {
              "type": "number"
            }
          },
          "required": [
            "latitude",
            "longitude"
          ]
        },
        "custom_fields": {
          "type": "array"
        }
      }
    },
    "url": {
      "type": "string"
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Информация о наряде
GET/jobs/{job_id}.json

Получите наряд по идентификатору job_id или по идентификатору во внешней системе external_id. Ответ сервера содержит полную информацию о наряде.

Параметры URI
job_id
string

Идентификатор или внешний идентификатор наряда


PATCH https://api.planadoapp.com/api/v1/jobs/job_id.json
Запрос
Заголовки
Content-Type: application/json
Тело сообщения
{
  "custom_fields": [
    {
      "name": "Your Field Name",
      "value": "New Value"
    }
  ]
}
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "success"
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Редактирование наряда
PATCH/jobs/{job_id}.json

Обновляются только дополнительные поля наряда. Для редактирования используйте JSON-объект custom_fields со следующими параметрами:

  • name — имя дополнительного поля

  • value — новое значение

Параметры URI
job_id
string

Идентификатор или внешний идентификатор наряда


DELETE https://api.planadoapp.com/api/v1/jobs/job_id.json
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "success"
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Удаление наряда
DELETE/jobs/{job_id}.json

Удалите наряд, указав идентификатор job_id или идентификатор во внешней системе external_id.

Параметры URI
job_id
string

Идентификатор или внешний идентификатор наряда


GET https://api.planadoapp.com/api/v1/clients.json?page=4
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
    "clients": [
        {
            "client_id": 13668001,
            "organization": false,
            "email": null,
            "external_id": null,
            "first_name": "Albert",
            "last_name": "Einstein",
            "middle_name": null,
            "name": "Albert Einstein",
            "site_address": {
                "description": null,
                "entrance_no": null,
                "apartment": null,
                "floor": null,
                "formatted": "112, Mercer Street, Princeton, Mercer County, New Jersey",
                "geolocation": {
                  "longitude": -74.666268,
                  "latitude": 40.343109
                }
            },
            "cell_phone": "79113456465",
            "work_phone": null
        },
        ...
    ],
    "view_url": "https://your-subdomain.planadoapp.com/clients",
    "page": 1,
    "total_pages": 2
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "page": {
      "type": "number"
    },
    "total_pages": {
      "type": "number"
    },
    "view_url": {
      "type": "string"
    },
    "clients": {
      "type": "array"
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Получение списка клиентов
GET/clients.json{?page}

Список клиентов приходит частями, по 20 объектов на странице. Результат содержит номер текущей страницы и полную информацию о клиенте.

Параметры URI
page
number

Размер страницы — 100 элементов.


POST https://api.planadoapp.com/api/v1/clients.json
ЗапросСоздание юрлицаСоздание физлица
Заголовки
Content-Type: application/json
Тело сообщения
{
  "external_id": "0dcc5ca36e1e580f",
  "organization": true,
  "organization_name": "Reichert-Rau",
  "contact_name": "Stephen Padberg",
  "contacts": [
    {
      "type": "phone",
      "name": "Estell Morissette Sr.",
      "value": "+79443146459",
      "value_normalized": "+79443146459"
    },
    {
      "type": "phone",
      "name": "Franco O'Reilly",
      "value": "+79294136091",
      "value_normalized": "+79294136091"
    }
  ]
  "email": "mariah@romaguerafunk.name"
}
Ответ201404422
Заголовки
Content-Type: application/json
Тело сообщения
{
  "client_id": 23351001,
  "status": "success"
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "unprocessable_entity",
  "errors": {
    "individual_name": [
      "provide first_name"
    ]
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "contacts": [
    {
      "type": "phone",
      "name": "Estell Morissette Sr.",
      "value": "+79443146459",
      "value_normalized": "+79443146459"
    },
    {
      "type": "phone",
      "name": "Franco O'Reilly",
      "value": "+79294136091",
      "value_normalized": "+79294136091"
    },
    {
      "type": "phone",
      "name": "Carroll Corwin",
      "value": "+79257311098",
      "value_normalized": "+79257311098"
    }
  ],
  "external_id": "f19ee7145a020479",
  "organization": false,
  "first_name": "Grayson",
  "last_name": "Wuckert",
  "email": "everardo_smitham@emmerichberge.org",
  "site_address": {
    "formatted": "Москва, Зеленоград, ул. Юности, д. 7",
    "description": "синяя левая дверь",
    "entrance_no": "2",
    "apartment": "17",
    "floor": "7"
  }
}
Ответ201404422
Заголовки
Content-Type: application/json
Тело сообщения
{
  "client_id": 23351001,
  "status": "success"
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "unprocessable_entity",
  "errors": {
    "individual_name": [
      "provide first_name"
    ]
  }
}

Создание клиента
POST/clients.json

Для создания юрлица, передайте в теле запроса параметр organization со значением true. Для физлица используйте значение false.


GET https://api.planadoapp.com/api/v1/clients/client_id.json
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "client": {
    "client_id": 23351001,
    "organization": false,
    "email": "albert_einstein@gmail.com",
    "external_id": "f370396",
    "first_name": "Albert",
    "last_name": "Einstein",
    "middle_name": null,
    "name": "Albert Einstein",
    "site_address": {
      "description": null,
      "entrance_no": null,
      "apartment": null,
      "floor": null,
      "formatted": "112, Mercer Street, Princeton, Mercer County, New Jersey",
      "geolocation": {
        "longitude": -74.666268,
        "latitude": 40.343109
      }
    },
    "work_phone": null,
    "cell_phone": null
  }
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "client": {
      "type": "object",
      "properties": {
        "client_id": {
          "type": "number"
        },
        "external_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "organization": {
          "type": "boolean"
        },
        "name": {
          "type": "string"
        },
        "first_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "last_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "middle_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "email": {
          "type": [
            "string",
            "null"
          ]
        },
        "site_address": {
          "type": "object",
          "properties": {
            "description": {
              "type": [
                "string",
                "null"
              ]
            },
            "apartment": {
              "type": [
                "string",
                "null"
              ]
            },
            "entrance_no": {
              "type": [
                "string",
                "null"
              ]
            },
            "floor": {
              "type": "string"
            },
            "formatted": {
              "type": [
                "string",
                "null"
              ]
            },
            "geolocation": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "latitude": {
                  "type": "number"
                },
                "longitude": {
                  "type": "number"
                }
              },
              "required": [
                "latitude",
                "longitude"
              ]
            }
          }
        },
        "cell_phone": {
          "type": [
            "string",
            "null"
          ]
        },
        "contacts": {
          "type": "array"
        }
      }
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Информация о клиенте
GET/clients/{client_id}.json

Получить информацию о клиенте можно по его идентификатору client_id или по идентификатору во внешней системе external_id.

Параметры URI
client_id
string

Идентификатор или внешний идентификатор клиента


PATCH https://api.planadoapp.com/api/v1/clients/client_id.json
Запрос
Заголовки
Content-Type: application/json
Тело сообщения
{
  "contacts": [
    {
      "type": "phone",
      "name": "Amara Gibson Sr.",
      "value": "+79410804477",
      "value_normalized": "+79410804477"
    },
    {
      "type": "phone",
      "name": "Daisha Cummerata",
      "value": "+79182228179",
      "value_normalized": "+79182228179"
    },
    {
      "type": "phone",
      "name": "Ms. Oleta Stamm",
      "value": "+79300610821",
      "value_normalized": "+79300610821"
    }
  ],
  "email": "samara.heel@schowaltertorphy.biz"
}
Ответ200404422
Заголовки
Content-Type: application/json
Тело сообщения
{
  "client_id": 23351001,
  "status": "success"
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "unprocessable_entity",
  "errors": {
    "email": [
      "size cannot be greater than 200"
    ],
    "contact_name": [
      "size cannot be greater than 200"
    ],
    "site_address": {
      "formatted": [
        "size cannot be greater than 5000"
      ],
      "entrance_no": [
        "size cannot be greater than 50"
      ],
      "apartment": [
        "size cannot be greater than 50"
      ],
      "floor": [
        "size cannot be greater than 50"
      ],
      "description": [
        "size cannot be greater than 500"
      ]
    }
  }
}

Редактирование клиента
PATCH/clients/{client_id}.json

Укажите название и новое значение поля. Ответ содержит результат запроса status и идентификатор клиента client_id.

Параметры URI
client_id
string

Идентификатор или внешний идентификатор клиента


DELETE https://api.planadoapp.com/api/v1/clients/client_id.json
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "success"
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Удаления клиента
DELETE/clients/{client_id}.json

Удалите клиента, указав идентификатор client_id или идентификатор во внешней системе external_id.

Параметры URI
client_id
string

Идентификатор или внешний идентификатор клиента


GET https://api.planadoapp.com/api/v1/sites.json?page=4
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "page": 4,
  "sites": [
    {
      "address": {
        "apartment": null,
        "description": null,
        "entrance_no": null,
        "floor": null,
        "formatted": null,
        "geolocation": null
      },
      "client_id": null,
      "contacts": [
        {
          "name": "1",
          "type": "phone",
          "value": ""
        },
        {
          "name": "1",
          "type": "phone",
          "value": ""
        }
      ],
      "description": null,
      "external_id": null,
      "site_id": 11690603001,
      "uuid": "1c0a74c0-a64c-4028-b43f-5543e5b50d24",
      "name": "Шест в поле"
    },
    {
      "address": {
        "apartment": null,
        "description": null,
        "entrance_no": null,
        "floor": null,
        "formatted": "мой адрес",
        "geolocation": null
      },
      "client_id": null,
      "contacts": [
        {
          "name": "2",
          "type": "phone",
          "value": ""
        },
        {
          "name": "4",
          "type": "phone",
          "value": ""
        }
      ],
      "description": null,
      "external_id": null,
      "site_id": 11690634001,
      "uuid": "b7290dd4-5d3f-46f4-998b-4f482e1d8ed8",
      "name": "Офис Ангстрем-Т №3"
    }
  ]
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "page": {
      "type": "number"
    },
    "sites": {
      "type": "array"
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Получение списка объектов
GET/sites.json{?page}

Список объектов приходит частями, по 20 объектов на странице. Результат содержит номер текущей страницы и полную информацию об объекте.

Параметры URI
page
number

Размер страницы — 20 объектов.


POST https://api.planadoapp.com/api/v1/sites.json
ЗапросПередача контактовНаряд с клиентом
Заголовки
Content-Type: application/json
Тело сообщения
{
  "name": "Столб вдали",
  "contacts": [
    {
      "type": "phone",
      "name": "Вася",
      "value": "8-80-05-553-535"
    },
    {
      "type": "phone",
      "name": "Ваня",
      "value": "+7(909)943-43-43"
    }
  ],
  "address": {
    "formatted": "Где-то в поле",
    "geolocation": {
      "latitude": 12.3,
      "longitude": 13.4
    }
  },
  "external_id": "my_external_id"
}
Ответ201404422
Заголовки
Content-Type: application/json
Location: /sites/2151231231
Тело сообщения
{
  "site_id": 2151231231,
  "status": "success"
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "unprocessable_entity",
  "errors": {
    "external_id": [
      "is used by another entity"
    ]
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "name": "Столб вдали у клиента",
  "client_id": 11512312001
}
Ответ201404422
Заголовки
Content-Type: application/json
Location: /sites/2151231231
Тело сообщения
{
  "site_id": 2151231231,
  "status": "success"
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "unprocessable_entity",
  "errors": {
    "external_id": [
      "is used by another entity"
    ]
  }
}

Создание объекта
POST/sites.json

Для создания объекта организации, передайте в поле client_id идентификатор или внешний идентификатор организации.

Если в теле запроса отсутствуют контакты и адрес, то они копируются из клиента.


GET https://api.planadoapp.com/api/v1/sites/site_id.json
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "site": {
    "site_id": 12695554433,
    "external_id": "4482d68cdf",
    "uuid": "d70399c6-5059-4bd4-a7c0-8f5fda260d7e",
    "name": "Internal Identity Analyst",
    "client_id": 12695553433,
    "description": "Ut tempore aut quas earum et omnis nobis. Quaerat perferendis id id culpa omnis et ut. Numquam accusamus aliquam.",
    "contacts": [
      {
        "name": "Mr. Sigrid Jast",
        "value": "+79229558424",
        "type": "phone"
      },
      {
        "name": "Ms. Federico Goldner",
        "value": "+79299687539",
        "type": "phone"
      },
      {
        "name": "Myrtle Zboncak",
        "value": "+79176339173",
        "type": "phone"
      }
    ],
    "address": {
      "formatted": "Sit cum dolorem omnis rerum.",
      "entrance_no": "6",
      "apartment": "35",
      "floor": "4",
      "description": "Rusted door",
      "geolocation": {
        "longitude": 68.6096071,
        "latitude": 39.2106464
      }
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Информация об объекте
GET/sites/{site_id}.json

Получите объект по идентификатору site_id или по идентификатору во внешней системе external_id. Ответ сервера содержит полную информацию об объекте.

Параметры URI
site_id
string

Идентификатор или внешний идентификатор объекта


PATCH https://api.planadoapp.com/api/v1/sites/site_id.json
ЗапросОбновление полей объектаПривязка клиента по внешнему идентификатору
Заголовки
Content-Type: application/json
Тело сообщения
{
  "name": "Dynamic Interactions Producer",
  "description": "Eum earum qui. Assumenda commodi tempore qui qui molestias. Quis laudantium nesciunt veniam tempore voluptates sunt vel.",
  "address_description": "Ullam adipisci iusto. Libero beatae similique id dolor soluta. Rerum omnis distinctio dolorem. Voluptas non voluptate officiis dolor et ipsum veniam. Sed assumenda nam nihil enim quia ea tempore.",
  "address": {
    "formatted": "Eum qui sint vero illo cumque.",
    "geolocation": {
      "latitude": 77.2106464,
      "longitude": 2.6096071
    }
  },
  "floor": "7",
  "apartment": "16",
  "entrance_no": "7",
  "contacts": [
    {
      "type": "phone",
      "value": "377.775.5529 x2035",
      "name": "Monserrat Pagac"
    }
  ]
}
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "success",
  "site_id": 12695444433
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "client_id": "a0327b8057a4d5c7"
}
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "success",
  "site_id": 12695444433
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Редактирование объекта
PATCH/sites/{site_id}.json

Укажите название и новое значение поля. Ответ содержит результат запроса status и идентификатор объекта site_id.

Параметры URI
site_id
string

Идентификатор или внешний идентификатор объекта


DELETE https://api.planadoapp.com/api/v1/sites/site_id.json
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "success"
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Удаление объекта
DELETE/sites/{site_id}.json

Удалите объект, указав идентификатор site_id или идентификатор во внешней системе external_id.

Параметры URI
site_id
string

Идентификатор или внешний идентификатор объекта


GET https://api.planadoapp.com/api/v1/templates.json?page=4
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "page": 1,
  "templates": [
    {
      "assignee_subject_id": null,
      "cell_phone": null,
      "client_id": null,
      "description": "Описание наряда",
      "name": "Ю.Название шаблона",
      "scheduled_at": null,
      "scheduled_duration_min": 60,
      "template_id": 435001,
      "type_id": 39001
    },
    {
      "assignee_subject_id": 26001,
      "cell_phone": null,
      "client_id": null,
      "description": "Съездить если хочется ништяков или дома нечего есть и неохота готовить",
      "name": "Ю. Купить еды в азбуке вкуса",
      "scheduled_at": null,
      "scheduled_duration_min": 30,
      "template_id": 495001,
      "type_id": 35001
    }
  ]
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "page": {
      "type": "number"
    },
    "templates": {
      "type": "array"
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Получение списка шаблонов
GET/templates.json{?page}

Список шаблонов приходит частями, по 20 элементов на странице.

Параметры URI
page
number

Размер страницы — 100 элементов


GET https://api.planadoapp.com/api/v1/templates/template_id.json
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "template": {
    "address": null,
    "assignee_subject_id": null,
    "custom_fields": [
      {
        "data_type": "attachment",
        "field_id": 8622099001,
        "field_type": "image",
        "name": "1 фото",
        "read_only": false,
        "required": true,
        "value": null
      },
      {
        "data_type": "string",
        "field_id": 8502589001,
        "field_type": "input",
        "name": "123",
        "read_only": true,
        "required": false,
        "value": null
      },
      {
        "data_type": "dictionary",
        "dictionary_values": [
          {
            "name": "6,35 мм (1/4 дюйма) - 60-90°",
            "value_id": 2070783001
          },
          {
            "name": "9,52 мм (3/8 дюйма) - 60-90°",
            "value_id": 2070784001
          },
          {
            "name": "12,7 мм (1/2 дюйма) - 30-60°",
            "value_id": 2070785001
          },
          {
            "name": "15,87 мм (5/8 дюйма) - 30-60°",
            "value_id": 2070786001
          }
        ],
        "field_id": 14429822001,
        "field_type": "dictionary",
        "name": "Тестовое",
        "read_only": true,
        "required": false,
        "value": null
      },
      {
        "data_type": "attachment",
        "field_id": 9257345001,
        "field_type": "image",
        "name": "4 фото",
        "read_only": false,
        "required": false,
        "value": null
      },
      {
        "data_type": "attachment",
        "field_id": 9257347001,
        "field_type": "image",
        "name": "5 фото",
        "read_only": false,
        "required": false,
        "value": null
      },
      {
        "data_type": "attachment",
        "field_id": 9257349001,
        "field_type": "image",
        "name": "6 фото",
        "read_only": false,
        "required": false,
        "value": null
      },
      {
        "data_type": "attachment",
        "field_id": 11521060001,
        "field_type": "image",
        "name": "7 фото",
        "read_only": false,
        "required": false,
        "value": null
      },
      {
        "data_type": "attachment",
        "field_id": 11521062001,
        "field_type": "image",
        "name": "8 фото",
        "read_only": false,
        "required": false,
        "value": null
      },
      {
        "data_type": "attachment",
        "field_id": 11521064001,
        "field_type": "image",
        "name": "9 фото",
        "read_only": false,
        "required": false,
        "value": null
      },
      {
        "data_type": "attachment",
        "field_id": 11521066001,
        "field_type": "image",
        "name": "10 фото",
        "read_only": false,
        "required": false,
        "value": null
      },
      {
        "data_type": "attachment",
        "field_id": 11521068001,
        "field_type": "image",
        "name": "11 фото",
        "read_only": false,
        "required": false,
        "value": null
      },
      {
        "data_type": "attachment",
        "field_id": 11521070001,
        "field_type": "image",
        "name": "12 фото",
        "read_only": false,
        "required": false,
        "value": null
      },
      {
        "data_type": "attachment",
        "field_id": 11521072001,
        "field_type": "image",
        "name": "13 фото",
        "read_only": false,
        "required": false,
        "value": null
      },
      {
        "data_type": "attachment",
        "field_id": 11521074001,
        "field_type": "image",
        "name": "14 фото",
        "read_only": false,
        "required": false,
        "value": null
      },
      {
        "data_type": "attachment",
        "field_id": 11521076001,
        "field_type": "image",
        "name": "15 фото",
        "read_only": false,
        "required": false,
        "value": null
      },
      {
        "data_type": "string",
        "field_id": 13927500001,
        "field_type": "input",
        "name": "Что-то",
        "read_only": false,
        "required": false,
        "value": null
      },
      {
        "data_type": "boolean",
        "field_id": 13927551001,
        "field_type": "checkbox",
        "name": "3 - Данетка",
        "read_only": false,
        "required": false,
        "value": null
      }
    ],
    "description": "sf",
    "name": "15 много фото",
    "possible_resolutions": [
      {
        "comment_required": false,
        "name": "Выполнено",
        "resolution_id": 8001,
        "successful": true
      },
      {
        "comment_required": false,
        "name": "Не выполнен",
        "resolution_id": 40001,
        "successful": false
      },
      {
        "comment_required": true,
        "name": "Не выполнен с примечанием",
        "resolution_id": 41001,
        "successful": false
      },
      {
        "comment_required": true,
        "name": "Клиент перенес",
        "resolution_id": 1261602001,
        "successful": false
      }
    ],
    "scheduled_at": null,
    "scheduled_duration_min": 60,
    "template_id": 8502396001,
    "type_id": 36001
  }
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "template": {
      "type": "object",
      "properties": {
        "template_id": {
          "type": "number"
        },
        "name": {
          "type": "string"
        },
        "type_id": {
          "type": "number"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "scheduled_duration_min": {
          "type": "number"
        },
        "assignee_subject_id": {
          "type": [
            "number",
            "null"
          ]
        },
        "possible_resolutions": {
          "type": "array"
        },
        "custom_fields": {
          "type": "array"
        }
      }
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Информация о шаблоне
GET/templates/{template_id}.json

Получите шаблон по идентификатору template_id. Ответ сервера содержит полную информацию о шаблоне.

Параметры URI
template_id
string

Идентификатор шаблона


GET https://api.planadoapp.com/api/v1/job_types.json?page=4
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "job_types": [
    {
      "type_id": 56001,
      "code": "default"
    },
    {
      "type_id": 124001,
      "code": "Delivery"
    }
  ],
  "page": 1,
  "total_pages": 1
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "job_types": {
      "type": "array"
    },
    "page": {
      "type": "number"
    },
    "total_pages": {
      "type": "number"
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Получение списка типов нарядов
GET/job_types.json{?page}

Список типов нарядов приходит частями, по 100 элементов на странице.

Параметры URI
page
number

Размер страницы — 100 элементов.


GET https://api.planadoapp.com/api/v1/resolutions.json?page=4
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
    "resolutions": [
        {
            "resolution_id": 58011,
            "name": "Finished",
            "successful": true,
            "comment_required": false
        },
        ...],
    "page": 1,
    "total_pages": 1
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "resolutions": {
      "type": "array"
    },
    "page": {
      "type": "number"
    },
    "total_pages": {
      "type": "number"
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Получение списка резолюций
GET/resolutions.json{?page}

Список резолюций приходит частями, по 100 элементов на странице.

Параметры URI
page
number

Размер страницы — 100 элементов.


GET https://api.planadoapp.com/api/v1/locations.json?page=4
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
    "locations": [
        {
            "location_id": 12532101,
            "worker_id": 427001,
            "worker_email": "foo@example.com",
            "geolocation": {
              "longitude": 37.16078166666667,
              "latitude": 55.981625
            },
            "source": "gps",
            "battery_level": 90.0,
            "actual_at": "2014-10-22T20:02:12"
        },
        ...
    ]
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "locations": {
      "type": "object",
      "properties": {
        "location_id": {
          "type": "number"
        },
        "worker_id": {
          "type": "number"
        },
        "worker_email": {
          "type": "string"
        },
        "geolocation": {
          "type": "object",
          "properties": {
            "latitude": {
              "type": "number"
            },
            "longitude": {
              "type": "number"
            }
          },
          "required": [
            "latitude",
            "longitude"
          ]
        },
        "source": {
          "type": "string",
          "enum": [
            "gps",
            "network",
            "fused"
          ]
        },
        "battery_level": {
          "type": "number"
        },
        "actual_at": {
          "type": "string"
        }
      }
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Получение списка геопозиций
GET/locations.json{?page}

Список геопозиций приходит частями, по 100 элементов на странице.

Параметры URI
page
number

Размер страницы — 100 элементов.


GET https://api.planadoapp.com/api/v1/users.json?page=4
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "success",
  "users": [
    {
      "email": "andrey+20@example.com",
      "first_name": "Андрей",
      "last_name": "Козлов",
      "mobile_phone": "+78002224657",
      "owner": true,
      "permissions": {
        "mobile_complete_jobs": true,
        "mobile_login": true,
        "web_admin": true,
        "web_login": true
      },
      "user_id": 1001,
      "uses_license": true
    },
    {
      "email": "foo@example.ru",
      "first_name": "Эрнест",
      "last_name": "Хемингуэй",
      "mobile_phone": "+79043217895",
      "owner": false,
      "permissions": {
        "mobile_complete_jobs": true,
        "mobile_login": true,
        "web_admin": true,
        "web_login": true
      },
      "user_id": 10001,
      "uses_license": true
    }
  ]
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "users": {
      "type": "array"
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Получение списка сотрудников
GET/users.json{?page}

Список сотрудников приходит частями, по 100 элементов на странице.

Параметры URI
page
number

Размер страницы — 100 элементов.


POST https://api.planadoapp.com/api/v1/users.json
Запрос
Заголовки
Content-Type: application/json
Тело сообщения
{
  "first_name": "Nat",
  "last_name": "Labadie",
  "email": "guillermo@deckow.biz",
  "mobile_phone": "(115) 374-5355 x66843",
  "password": "c19a7c9b3733e21f",
  "permissions": {
    "web": {
      "jobs": [
        "write"
      ],
      "schedule": [
        "read"
      ],
      "clients": [
        "write",
        "read"
      ],
      "map": [
        "read"
      ]
    },
    "mobile": [
      "complete_jobs"
    ]
  }
}
Ответ201404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "success",
  "user_id": 10001
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "user_id": {
      "type": "number"
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Создание сотрудника
POST/users.json

Ограничьте доступ сотрудника к Planado, передав объект permissions с правами на веб-приложение (web) и мобильное приложение (mobile)

Права на веб-приложение — JSON-объект со следующими полями:

  • jobs — доступ к нарядам

  • schedule — доступ к расписаню

  • clients — доступ к клиентам и объектам

  • map — доступ к карте

  • teams — доступ к бригадам

Если ключ не указан, то доступа к этому разделу не будет.

Для каждого раздела можно указать доступ на чтение (read) или запись (write).

Что вы отправляете Что получается
"jobs": [] Сотрудник может просматривать наряды
"jobs": ["read"] Сотрудник может просматривать наряды
"jobs": ["read", "write"] Сотрудник может просматривать и редактировать наряды
"jobs": ["write"] Сотрудник может просматривать и редактировать наряды

Права на мобильное приложение

Что вы отправляете Что получается
"mobile": [] Сотрудник может просматривать наряды в мобильном приложении
"mobile": ["complete_jobs"] Сотрудник может выполнять наряды в мобильном приложении

Учтите, что права на редактирование и выполнение нарядов — платная возможность и требует лицензии.


GET https://api.planadoapp.com/api/v1/users/user_id.json
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
  "email": "foo@example.ru",
  "first_name": "Эрнест",
  "last_name": "Хемингуэй",
  "mobile_phone": "+79043217895",
  "owner": false,
  "permissions": {
    "mobile_complete_jobs": true,
    "mobile_login": true,
    "web_admin": true,
    "web_login": true
  },
  "user_id": 10001,
  "uses_license": true
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "user_id": {
      "type": "number"
    },
    "first_name": {
      "type": "string"
    },
    "last_name": {
      "type": "string"
    },
    "permissions": {
      "type": "object",
      "properties": {
        "web_login": {
          "type": "boolean"
        },
        "web_admin": {
          "type": "boolean"
        },
        "mobile_login": {
          "type": "boolean"
        },
        "mobile_complete_jobs": {
          "type": "boolean"
        }
      }
    },
    "email": {
      "type": "string"
    },
    "uses_license": {
      "type": "boolean"
    },
    "owner": {
      "type": "boolean"
    },
    "mobile_phone": {
      "type": "string"
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Информация о сотруднике
GET/users/{user_id}.json

Информацию о сотруднике можно получить двумя способами:

  • по идентификатору user_id

  • по электронной почте

Параметры URI
user_id
string

Идентификатор или email сотрудника


GET https://api.planadoapp.com/api/v1/teams.json?page=4
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
    teams: [
            "foreman": {
              "email": "john@beatles.com",
              "name": "John Lennon",
              "worker_id": 51001
            },
            "name": "The Beatles",
            "team_id": 79001,
            "workers": [
              {
                "email": "ringo@beatles.com",
                "name": "Ringo Starr",
                "worker_id": 63001
              }
              ...
            ]
        },
        {
            "foreman": null,
            "name": "Quarrymen",
            "team_id": 81001,
            "workers": []
        }
    ]
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "teams": {
      "type": "array"
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Получение списка бригад
GET/teams.json{?page}

Список бригад приходит частями, по 20 элементов на странице.

Параметры URI
page
number

Размер страницы — 20 элементов.


GET https://api.planadoapp.com/api/v1/teams/team_id.json
Ответ200404
Заголовки
Content-Type: application/json
Тело сообщения
{
    "foreman": {
        "email": "john@beatles.com",
        "name": "John Lennon",
        "worker_id": 51001
    },
    "name": "The Beatles",
    "team_id": 79001,
    "workers": [
        {
            "email": "ringo@beatles.com",
            "name": "Ringo Starr",
            "worker_id": 63001
        }
        ...
    ]
}
Схема
ПоказатьСкрыть
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "team_id": {
      "type": "number"
    },
    "name": {
      "type": "string"
    },
    "foreman": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "worker_id": {
          "type": "number"
        },
        "name": {
          "type": "string"
        },
        "email": {
          "type": "string"
        }
      }
    },
    "workers": {
      "type": "array"
    }
  }
}
Заголовки
Content-Type: application/json
Тело сообщения
{
  "status": "not found"
}

Информация о бригаде
GET/teams/{team_id}.json

Получите бригаду по идентификатору team_id. Ответ сервера содержит полную информацию о бригаде.

Параметры URI
team_id
string

Идентификатор бригады


Generated by aglio on 27 Mar 2018