Основы API
Методы API

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

Базовый 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": "Привет!"  }}
Обёртка используется не во всех методах — точную структуру тела смотрите в описании каждого метода.

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

Создание сотрудника
curl "https://api.pachca.com/api/shared/v1/users" \  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \  -H "Content-Type: application/json" \  -d '{  "user": {    "email": "olegp@example.com"  }}'

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

Ответы возвращаются в формате 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.