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

Базовый URL

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

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

Заголовки

ЗаголовокЗначениеКогда нужен
AuthorizationBearer YOUR_ACCESS_TOKENВсегда
Content-Typeapplication/json; charset=utf-8POST, PUT, PATCH

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

Тело запроса

Параметры передаются в формате 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 \  --no-suspended \  --list-tags=Product,Design \  --custom-properties='[{"id":1678,"value":"Санкт-Петербург"}]' \  --skip-email-notify \  --json \  --token YOUR_ACCESS_TOKEN

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

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

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

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

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

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

Списочные методы возвращают массив data и блок meta с курсором для следующей страницы:

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

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

Пустой ответ

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

Ошибка

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

Ошибка валидации (422)
{  "errors": [    {      "key": "invalid",      "message": "Не может быть пустым",      "value": "first_name"    }  ]}
Ошибка авторизации (401)
{  "error": "unauthenticated",  "error_description": "Требуется авторизация"}

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

Соглашения

СоглашениеПример
Имена полей — snake_casefirst_name, entity_id, created_at
Даты и время — ISO 86012024-01-15T10:30:00.000+03:00
Идентификаторы — целые числа"id": 12345
Пустые значения — null"nickname": null
Логические поля — boolean"suspended": false

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

Scalar

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

Открыть Scalar API Client

Браузерный клиент на основе OpenAPI-спецификации. Бесплатно, без регистрации.

Браузерный клиент Scalar отправляет запросы через прокси-сервер proxy.scalar.com — это необходимо из-за ограничений браузера (CORS). Токен проходит через сервер Scalar, но по их заявлению данные не логируются. Scalar — проект с открытым исходным кодом (MIT), включая код прокси. Если вы хотите избежать передачи токена через сторонний сервер, используйте Postman или Bruno — они работают локально и отправляют запросы напрямую.

Postman / Bruno

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

  • Postman — File > Import
  • Bruno (open-source альтернатива) — File > Import > Postman Collection
Коллекция Postman/Bruno
https://dev.pachca.com/pachca.postman_collection.json
Скачать коллекцию

Файл в формате Postman Collection v2.1, совместим с Postman и Bruno.