Внешние идентификаторы

Некоторые сущности в Планадо могут иметь внешние идентификаторы. Внешний идентификатор — это обычно идентификатор сущности во внешней системе, например, CRM. API Планадо позволяет использовать внешние идентификаторы почти во всех запросах, упрощая синхронизацию данных. Вам не нужно хранить идентификаторы Планадо в вашей системе или реализовывать сложную логику подбора.

Допустим, в вашей системе есть таблица customers со списком клиентов:

Table 1. `customers`
Поле	Тип	Null?	Описание
`id`	`integer`	`not null`	Первичный ключ
`first_name`	`varchar(50)`	`not null`
`second_name`	`varchar(50)`	`not null`
`address`	`varchar(500)`
`phone`	`varchar(100)`

Чтобы синхронизировать строки customers и клиентов в Планадо, вы можете использовать первичный ключ customers.id как внешний идентификатор.

Предположим, в customers есть такая запись:

{
  "id": 42,
  "first_name": "Иван",
  "last_name": "Смирнов",
  "address": "123123 Москва, ул. Волкова, д. 7, кв. 12",
  "phone": "+7 976 241-42-09"
}

Для того, чтобы добавить или обновить эту запись в Планадо, вы можете использовать 42 как внешний идентификатор. Просто передайте его в URL запроса на обновление. В примере ниже, если клиент с внешним идентификатором 42 не будет найден, Планадо создаст нового клиента (подробнее об обновлении клиентов).

$ curl -H "Authorization: Bearer api-key" \
       -X PATCH \
       https://api.planadoapp.com/v2/clients/42 \
       --data @- << EOF | jq
{
  "organization": false,
  "first_name": "Иван",
  "last_name": "Смирнов",
  "address": {
    "formatted": "123123 Москва, ул. Волкова, д. 7, кв. 12"
  },
  "contacts": [
    {
      "value": "+7 976 241-42-09",
      "type": "phone"
    }
  ]
}
EOF
{
  "client_uuid": "40a10224-890d-4fca-8f46-1eef1102dc28"
}

Такой подход позволяет в один запрос синхронизировать данные с Планадо.