Open API

Open API нужен в тех случаях, когда Synchra.24 должна не только работать как приложение для сотрудников, но и обмениваться данными с внешними системами компании.

Чаще всего интеграции используют в трех сценариях:

• забирать данные из компании во внешнюю систему;
• создавать записи в Synchra.24 из внешней системы;
• синхронизировать справочники, задачи, заявки, документы и другие процессы между несколькими сервисами.

Этот документ построен в двух частях:

1. сначала показаны основные сценарии с понятными примерами;
2. ниже идет полный каталог методов по разделам в одном и том же формате.

Как устроен доступ

Для Open API чаще всего нужны два заголовка:

• X-OpenAPI-Token — токен интеграции;
• X-Provider-Token — токен конкретной компании.

Если говорить проще:

• X-OpenAPI-Token подтверждает, что интеграция вообще имеет право работать;
• X-Provider-Token подтверждает, с какой именно компанией вы сейчас работаете.

Базовая цепочка работы

Обычно интеграция выглядит так:

1. вы создаете Open API токен в параметрах компании;
2. вызываете метод параметров компании и получаете provider token;
3. дальше вызываете методы нужного раздела уже с двумя заголовками.

Первый обязательный запрос:

GET /api/v1/providers/user/params/{provider_id}
X-OpenAPI-Token: <ваш_openapi_token>

Из ответа нужно взять:

• result.token — это и есть X-Provider-Token;
• при необходимости остальные параметры компании.

Дальше большинство запросов будут выглядеть так:

X-OpenAPI-Token: <ваш_openapi_token>
X-Provider-Token: <token_компании>
Content-Type: application/json

Что важно помнить

• Лимит Open API: 300 запросов в минуту на один X-OpenAPI-Token.
• Многие GET-методы поддерживают общие query-поля: page, size, search, sort, date_from, date_to.
• Там, где backend уже задает устойчивую структуру body, ниже приведены конкретные поля и примеры.
• Там, где метод принимает более свободный JSON, это отдельно отмечено.

Список методов

OPEN API методы

Как пользоваться этим документом

Если вы строите интеграцию под конкретный сценарий, лучше идти так:

1. сначала определить бизнес-процесс;
2. найти нужный раздел в каталоге методов;
3. взять основной create или update метод;
4. проверить результат в интерфейсе Synchra.24;
5. только потом добавлять списки, фильтры и синхронизацию в обе стороны.

Так интеграция запускается быстрее и без лишней сложности на старте.

Визиты посетителей

Сервис «Визиты» доступен через API компании. Требуются X-OpenAPI-Token, X-Provider-Token, лицензия visits (Trial, Pro или Ultimate) и соответствующие права роли.

Метод	Путь	Назначение
GET	/api/v1/tm/visits	Журнал с поиском, фильтрами и пагинацией.
POST	/api/v1/tm/visits	Создание визита.
GET	/api/v1/tm/visit-guests	Поиск повторных посетителей.
GET	/api/v1/tm/visits/{id}	Карточка с историей.
PUT	/api/v1/tm/visits/{id}	Изменение до входа, с текущей version.
POST	/api/v1/tm/visits/{id}/status	Прибытие, вход, завершение, отмена или неявка.
POST	/api/v1/tm/visits/{id}/admission	Разрешение или отклонение допуска.
POST	/api/v1/tm/visits/{id}/pass	Выпуск QR и, при включённой самостоятельной отметке, public_url.
POST	/api/v1/tm/visits/resolve-pass	Проверка персонального QR внутри своей компании.

Создание, изменение, статусы и выпуск пропуска требуют control_visits_manage, решение по допуску — control_visits_admission. Просмотр доступен с control_visits_view, control_visits_manage или control_visits_admission.

Создание и обновление

{
  "guest": { "first_name": "Иван", "last_name": "Иванов", "organization": "Перевозчик" },
  "location": "Склад №2",
  "purpose": "Разгрузка",
  "planned_start": "2026-11-01T09:00:00+03:00",
  "planned_end": "2026-11-01T12:00:00+03:00",
  "responsible_id": 123,
  "require_admission": true,
  "self_arrival_enabled": true,
  "external_system": "crm",
  "external_id": "delivery-456"
}

responsible_id должен принадлежать компании; он обязателен для самостоятельной отметки. Для существующего посетителя передайте guest.id. Фотография guest.photo — имя файла в хранилище своей компании, не URL; при явной замене или удалении фото существующего посетителя передайте guest_photo_changed: true.

Пара external_system + external_id уникальна в компании: повторный POST с тем же содержимым возвращает существующий визит без дублирования. Если содержимое отличается, ответ — 409. Для изменения найдите запись по этим фильтрам, получите карточку и передайте полные данные с актуальной version в PUT.

Поиск и переходы состояний

Журнал поддерживает search, status (несколько значений через запятую), admission, location, responsible_id, guest_id, external_system, external_id, date_from, date_to, sort=ASC|DESC, page, size. Размер страницы — до 100; без size возвращается до 100 записей. Для страниц по 20 передавайте size=20. Даты — RFC3339, правая граница исключается; выбираются пересекающиеся плановые интервалы.

Для изменения статуса передайте, например, {"status":"arrived","version":1,"comment":"Прибыл на КПП"}. Для допуска — {"status":"allowed","version":2}. При действии по QR дополнительно передайте pass_token. Все отметки времени задаёт сервер. Недопустимый переход или устаревшая версия дают 409; после конфликта перечитайте карточку.

Состояния посещения: expected, arrived, inside, completed, cancelled, no_show. Допуск: not_required, pending, allowed, denied. Разрешение допуска само по себе не отмечает вход. Переход inside требует разрешения, если согласование включено.

Все ответы используют оболочку code, message, status, result. Выпуск пропуска возвращает секретные token, qr_value и, при включённой опции, public_url: не записывайте их в общедоступные журналы. Новый выпуск и изменение визита отзывают прежний пропуск.

Публичные методы страницы посетителя не входят в Open API компании и не предоставляют доступ к её данным. Для обмена с внешней системой используйте методы таблицы и события visit.*. Полные схемы запросов и ответов доступны в Swagger.