Справочники
- GET/
catalogs/ {catalog-id}Получение справочника - GET/
catalogsПолучение всех справочников - PUT/
catalogsСоздание справочника - POST/
catalogs/ {catalog-id}Синхронизация справочника - POST/
catalogs/ {catalog-id}/ diffИзменение справочника
GET /catalogs/{catalog-id}
Метод возвращает справочник с элементами. Без фильтров он отдает все доступные элементы. Чтобы получить только строки с определёнными значениями колонок, передайте пары параметров column и value. Если условий несколько, повторите оба параметра для каждого из них — элемент должен удовлетворять всем условиям сразу.
В примере запрос возвращает элемент с именем «Andy Mahn»: значение Andy* означает, что имя должно начинаться с Andy.
Параметр use_wildcard=true включает поиск по маске для всех условий: * обозначает любое количество символов, ? — один символ. По умолчанию use_wildcard=false, то есть используется точное совпадение.
Есть два ограничения: нельзя фильтровать по колонкам маршрутизации и нельзя сочетать фильтры с include_deleted=true.
GET https://api.pyrus.com/v4 /catalogs /6625 ?column=Name &value=Andy%2A &use_wildcard=true
Тело ответа
{
"catalog_id": 6625,
"name": "Clients",
"catalog_headers": [
{
"name": "Name",
"type": "text"
},
{
"name": "Company",
"type": "text"
}
],
"items": [
{
"item_id": 15202,
"values": [
"Andy Mahn",
"123 Warehousing"
]
}
]
}
curl
curl -X GET \ 'https://api.pyrus.com/v4/catalogs/6625?column=Name&value=Andy%2A&use_wildcard=true' \ -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \ -H 'Content-Type: application/json'
Параметры
| include_deleted | Добавляет удаленные элементы справочника в результаты запроса. Доступно только пользователям с правами администратора организации. Не используется вместе с фильтрами. |
| column | Название колонки для фильтрации; можно передать несколько раз. |
| value | Значение для соответствующей колонки; количество value должно совпадать с количеством column. Чтобы найти незаполненные поля, передайте пустую строку (не null). |
| use_wildcard | Необязательный параметр (true или false). Включает поиск по маске для всех условий. Символ * обозначает любое количество символов, ? — один символ. По умолчанию — false, то есть используется точное совпадение. |
Если условий несколько, повторите пары column и value. Например: ?column=Name&. Все условия применяются одновременно.
GET /catalogs
Метод возвращает все справочники без элементов.
GET https://api.pyrus.com/v4 /catalogs
Тело ответа
{
"catalogs": [
{
"catalog_id": 31816,
"name": "Catalog1",
"version": 151199,
"deleted": false,
"supervisors": [
1731
],
"external_version": 0
},
{
"catalog_id": 31817,
"name": "Catalog2",
"version": 109104,
"deleted": false,
"external_version": 0
}
]
}
curl
curl -X GET \ https://api.pyrus.com/v4/catalogs \ -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \ -H 'Content-Type: application/json'
PUT /catalogs
Создание справочника. Метод возвращает созданный справочник со всеми элементами.
PUT https://api.pyrus.com/v4 /catalogs
Тело запроса
{
"name": "Clients",
"catalog_headers": [
"Name",
"Company"
],
"items": [
{
"values": [
"Reatha Middendorf",
"Acme, inc."
]
},
{
"values": [
"Daedra Ullrich",
"Widget Corp"
]
},
{
"values": [
"Andy Mahn",
"123 Warehousing"
]
}
]
}
Тело ответа
{
"catalog_id": 6625,
"name": "Clients",
"catalog_headers": [
{
"name": "Name",
"type": "text"
},
{
"name": "Company",
"type": "text"
}
],
"items": [
{
"item_id": 15200,
"values": [
"Reatha Middendorf",
"Acme, inc."
]
},
{
"item_id": 15201,
"values": [
"Daedra Ullrich",
"Widget Corp"
]
},
{
"item_id": 15202,
"values": [
"Andy Mahn",
"123 Warehousing"
]
}
]
}
curl
curl -X PUT \
https://api.pyrus.com/v4/catalogs/ \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Clients",
"catalog_headers": [
"Name",
"Company"
],
"items": [
{
"values": [
"Reatha Middendorf",
"Acme, inc."
]
},
{
"values": [
"Daedra Ullrich",
"Widget Corp"
]
},
{
"values": [
"Andy Mahn",
"123 Warehousing"
]
}
]
}'
POST /catalogs/{catalog-id}
Синхронизация справочника. Метод обновляет значения и заголовки справочника. Нужно передать все значения и текстовые колонки, которые должны остаться в справочнике. Всё, что не указано в запросе, будет удалено — и значения, и текстовые колонки. Колонки маршрутизации добавить или удалить с помощью этого запроса нельзя. Можно только изменить значения для существующей колонки. Для этого ее нужно явно передать в списке колонок. Первая колонка справочника является ключевой, поэтому изменить ее название нельзя. Метод возвращает список значений, которые были добавлены, изменены или удалены.
POST https://api.pyrus.com/v4 /catalogs /6625
Тело запроса
{
"apply": true,
"catalog_headers": [
"Name",
"Company"
],
"items": [
{
"values": [
"Reatha Middendorf",
"Acme"
]
},
{
"values": [
"Daedra Ullrich",
"Widget Corp"
]
},
{
"values": [
"Jean Overturf",
"Demo Company"
]
}
]
}
Тело ответа
{
"apply": true,
"added": [
{
"item_id": 15205,
"values": [
"Jean Overturf",
"Demo Company"
]
}
],
"deleted": [
{
"item_id": 15202,
"values": [
"Andy Mahn",
"123 Warehousing"
]
}
],
"updated": [
{
"item_id": 15200,
"values": [
"Reatha Middendorf",
"Acme"
]
}
],
"catalog_headers": [
{
"name": "Name",
"type": "text"
},
{
"name": "Customer Company",
"type": "text"
}
]
}
curl
curl -X POST \
https://api.pyrus.com/v4/catalogs/6625 \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"apply": true,
"catalog_headers": [
"Name",
"Company"
],
"items": [
{
"values": [
"Reatha Middendorf",
"Acme"
]
},
{
"values": [
"Daedra Ullrich",
"Widget Corp"
]
},
{
"values": [
"Jean Overturf",
"Demo Company"
]
}
]
}'
Параметры
| apply | Укажите true, если хотите обновить справочник, и false, если нужно только посчитать, какие элементы будут добавлены, удалены или обновлены. |
| catalog_headers | Список колонок. Все неперечисленные в нем текстовые колонки будут удалены. |
| items | Список значений. Все неперечисленные в нем значения будут удалены. |
POST /catalogs/{catalog-id}/diff
Изменение справочника. Метод позволяет добавлять новые записи справочника, изменять существующие или удалять ненужные. Первая колонка справочника — ключевая.
Чтобы добавить или изменить записи, передайте массив их значений. Чтобы удалить записи, достаточно передать только список ключей. Метод возвращает список значений, которые были добавлены, изменены или удалены — так же, как метод синхронизации справочника.
POST https://api.pyrus.com/v4 /catalogs /6625 /diff
Тело запроса
{
"upsert": [
{
"values": [
"Reatha Middendorf",
"Acme"
]
},
{
"values": [
"Daedra Ullrich",
"Widget Corp"
]
}],
"delete": ["Jean Overturf"]
}
Тело ответа
{
"apply": true,
"added": [
{
"item_id": 24807,
"values": [
"Daedra Ullrich",
"Widget Corp"
]
}],
"deleted": [
{
"item_id": 23169,
"values": [
"Jean Overturf",
"Demo Company"
]
}],
"updated": [
{
"item_id": 23178,
"values": [
"Reatha Middendorf",
"Acme"
]
}],
"catalog_headers": [
{
"name": "Name",
"type": "text"
},
{
"name": "Company name",
"type": "text"
}]
}
curl
curl -X POST \
https://api.pyrus.com/v4/catalogs/6625/diff \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"upsert": [
{
"values": [
"Reatha Middendorf",
"Acme"
]
},
{
"values": [
"Daedra Ullrich",
"Widget Corp"
]
}],
"delete": ["Jean Overturf"]
}'
Параметры
| upsert | Список значений записей для добавления и изменения. |
| delete | Список ключей (значения первой колонки) для удаления. |