Запросы и ответы

Базовый URL

Все запросы к API отправляются по HTTPS:

https://api.pachca.com/api/shared/v1

Заголовки

Подробнее о типах токенов и скоупах — в разделе Авторизация.

Тело запроса

Параметры передаются в формате JSON, кодировке UTF-8. Для методов, работающих с сущностями, тело оборачивается в корневой ключ с именем сущности:

{  "message": {    "entity_id": 12345,    "content": "Привет!"  }}

Пример запроса

pachca users create \  --first-name=Олег \  --last-name=Петров \  --email=olegp@example.com \  --phone-number=+79001234567 \  --nickname=olegpetrov \  --department=Продукт \  --title=CIO \  --role=user \  --list-tags='["Product","Design"]' \  --chat-ids='[12345]' \  --custom-properties='[{"id":1678,"value":"Санкт-Петербург"}]' \  --json \  --token YOUR_ACCESS_TOKEN

Формат ответа

Ответы возвращаются в формате JSON, кодировке UTF-8.

Одиночный объект

Успешный ответ содержит данные в объекте data:

{  "data": {    "id": 12,    "first_name": "Олег",    "last_name": "Петров",    "email": "olegp@example.com"  }}

Список с пагинацией

Списочные методы возвращают массив data и блок meta.paginate с курсорами и флагами:

{  "data": [    { "id": 1, "name": "Общий" },    { "id": 2, "name": "Проект" }  ],  "meta": {    "paginate": {      "next_page": "eyJpZCI6MTAsIl9rZCI6Im4ifQ",      "prev_page": "eyJpZCI6MSwgIl9rZCI6InAifQ",      "has_next": true,      "has_prev": false    }  }}

Подробнее — в разделе Пагинация.

Пустой ответ

Некоторые методы (например, удаление) возвращают 204 No Content без тела ответа.

Ошибка

При ошибке возвращается одна из двух структур в зависимости от типа ошибки:

{  "errors": [    {      "key": "image",      "value": null,      "message": "Поле обязательно для заполнения",      "code": "blank",      "payload": null    }  ]}

{  "error": "unauthenticated",  "error_description": "Требуется авторизация"}

Подробнее — в разделах Ошибки и Лимиты.

Соглашения

В ответах время всегда приходит в UTC: с буквой Z на конце и ровно тремя знаками долей секунды. В запросах можно присылать и смещение — 2024-01-15T10:30:00.000+03:00 будет понято правильно. А вот время без смещения считается за UTC, а не за ваш часовой пояс: пояс из карточки сотрудника на разбор входящих значений нигде не влияет. Поэтому время, названное сотрудником («в три часа»), переводите в UTC или присылайте со смещением сами.

Тестирование API

Scalar

Онлайн-клиент с интерфейсом для тестирования всех методов API прямо в браузере — без установки. Достаточно вставить токен и отправить запрос.

Postman / Bruno

Коллекция содержит все методы API с примерами запросов и настроенной авторизацией. Совместима с:

• Postman — File > Import
• Bruno (open-source альтернатива) — File > Import > Postman Collection

https://dev.pachca.com/pachca.postman_collection.json