Практические материалы по запуску и развитию

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: 100 запросов в минуту на один 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. только потом добавлять списки, фильтры и синхронизацию в обе стороны.

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