Ссылки на сущности

Типичная задача при использовании API — необходимость сослаться в одной сущности на другую. Например, для создания наряда по шаблону, необходимо указать сам шаблон. Допустим, в Планадо есть шаблон «Ремонт», и вам известен его идентификатор (поле uuid). Тогда создать наряд можно таким запросом:

$ curl -H "Authorization: Bearer api-key" \
       --data "{\"template\":{\"uuid\":\"5990757f-fb00-4822-8c76-f967bda14554\"},\"description\": \"Новый наряд на ремонт\"}" \
       https://api.planadoapp.com/v2/jobs
{"job_uuid":"8070f98d-b3f6-4cc8-b7c4-54b6709cd98b"}

Другой вариант — использовать название шаблона для ссылки, используя поле name:

$ curl -H "Authorization: Bearer api-key" \
       --data "{\"template\":{\"name\":\"Ремонт\"},\"description\": \"Новый наряд на ремонт\"}" \
       https://api.planadoapp.com/v2/jobs
{"job_uuid":"8070f98d-b3f6-4cc8-b7c4-54b6709cd98b"}

Использовать названия проще, потому что они несут больше смысла. С другой стороны, значения uuid уникальны и неизменяемы. Если кто-то изменит название шаблона с «Ремонт» на «Новый ремонт», то запрос выше перестанет работать. В этом смысле использование uuid более надежно.

Для большинства сущностей в Планадо можно равноценно использовать uuid или name. Для пользователей также можно использовать email. Наконец, для нарядов, клиентов и объектов есть поддержка external_id (см. внешние идентификаторы).