Как начать работу с публичным API 101

Публичное API 101 позволяет подключить к 101 собственный сервис, корпоративную систему или автоматизацию. Интеграция обращается к методам по HTTPS, получает структурированные ответы и выполняет действия в пределах прав авторизованного пользователя.

Главный источник истины — живая OpenAPI-схема. Список методов, параметры и модели ответов могут развиваться. Перед реализацией проверяйте текущий контракт в Swagger UI 101 или в OpenAPI-схеме.

Что такое публичное API 101

API — программный интерфейс для прямого обмена с сервером 101. Ваш backend формирует HTTP-запрос, передаёт авторизацию и данные, а 101 проверяет контракт, пользователя, компанию, права и бизнес-правила.

Рабочий production-адрес:

https://app.101-group.ru

Пути методов начинаются с /api/. Например, безопасный запрос списка компаний пользователя:

GET https://app.101-group.ru/api/company/v2/

Когда выбирать API

Нужно синхронизировать 101 с CRM, ERP, BI или внутренним сервисом.
Нужно регулярно читать данные по расписанию без диалога с AI.
Нужно построить собственный интерфейс поверх разрешённых данных 101.
Нужно автоматизировать проверенный бизнес-процесс на сервере.
Нужен метод, который есть в OpenAPI, но не представлен отдельным инструментом MCP 101.

Если сотруднику удобнее работать с 101 обычным языком в ChatGPT или Codex, рассмотрите MCP 101. MCP предоставляет отобранные инструменты и встроенные подтверждения для поддерживаемых операций записи. API даёт низкоуровневый HTTP-контракт, поэтому интерфейс подтверждения, повторные попытки, журналирование и обработку ошибок проектирует разработчик интеграции.

Какие возможности представлены в API

На дату проверки публичная схема описывает методы по следующим направлениям:

авторизация и профиль пользователя;
компании, участники и права;
проекты и контрагенты;
события и финансовые сущности;
счета и статьи расходов;
задачи и комментарии;
Wiki и управление доступом к материалам;
CRM-сценарии;
прайс-листы и отчёты;
генерация предусмотренных контрактом документов.

Это обзор доменов, а не обещание конкретной операции. Наличие метода, обязательные поля, разрешённые значения и ответ нужно проверять в актуальной схеме.

Что понадобится

аккаунт 101 с доступом к нужной компании;
подходящая роль и права на конкретные сущности;
серверное приложение, способное безопасно хранить секреты;
HTTPS и контролируемое журналирование без токенов и персональных данных;
разработчик, который умеет работать с REST, JSON и OpenAPI.

Документация внутри кабинета доступна по адресу 101-app.com/api-docs после входа в 101. Публичная Swagger UI доступна отдельно: app.101-group.ru/api/docs/.

Как читать документацию

Откройте Swagger UI.
Выберите нужный раздел и метод.
Проверьте HTTP-метод и полный path, включая завершающий слеш.
Изучите description, параметры пути и запроса, request body и обязательные поля.
Проверьте схемы успешных ответов и ошибок.
Убедитесь, что метод не помечен устаревшим.
Для теста начинайте с безопасного GET, который ничего не меняет.

Не переносите path из старой статьи или фрагмента кода без сверки. Например, в схеме могут одновременно оставаться новый метод и его legacy-предшественник; для новой интеграции выбирайте актуальную версию из OpenAPI.

Авторизация по шагам

Метод входа:

POST /api/auth/sign-in/

Он принимает login — email или телефон — и password. Пример запроса с безопасными заполнителями:

curl -X POST 'https://app.101-group.ru/api/auth/sign-in/' \
  -H 'Content-Type: application/json' \
  --data '{
    "login": "YOUR_LOGIN",
    "password": "YOUR_PASSWORD"
  }'

Успешный ответ содержит:

token — access token для запросов;
refresh_token — токен обновления;
access_token_expires_at и refresh_token_expires_at — метки истечения;
идентификаторы пользователя, которые не следует показывать в пользовательском интерфейсе без необходимости.

Не вставляйте настоящий логин, пароль или токен в Help, репозиторий, frontend-код, скриншот, чат или систему аналитики. Запрос входа должен выполняться на доверенном сервере.

2. Передайте access token

Публичный интерфейс документации 101 формирует заголовок:

Authorization: JWT <token>

Пример первого запроса только на чтение:

curl 'https://app.101-group.ru/api/company/v2/' \
  -H 'Accept: application/json' \
  -H 'Authorization: JWT YOUR_TOKEN'

Метод возвращает компании, участником которых является текущий пользователь. Не сохраняйте полный ответ в публичных логах: он может содержать внутренние сведения компании.

3. Обновляйте пару токенов

Актуальный метод обновления:

POST /api/auth/refresh-token/

Он принимает поле refreshToken и возвращает новую пару token + refreshToken с полями accessTokenExpiresAt и refreshTokenExpiresAt.

curl -X POST 'https://app.101-group.ru/api/auth/refresh-token/' \
  -H 'Content-Type: application/json' \
  --data '{"refreshToken":"YOUR_REFRESH_TOKEN"}'

Сразу заменяйте старую пару новой. Не рассчитывайте, что старый refresh token останется действительным после ротации.

Минимальный безопасный сценарий

На backend получите JWT-пару.
Выполните GET /api/company/v2/.
Покажите пользователю список доступных компаний без изменения данных.
Попросите пользователя явно выбрать компанию, если их несколько.
Только после выбора загружайте проекты или другие сущности этой компании.
Добавьте обработку 401, 403 и обновления токена.
Перед операциями записи внедрите отдельный экран проверки точных параметров.

Этот порядок снижает риск выполнить действие не в той компании. Нельзя молча выбирать первую компанию из ответа.

Основные сценарии интеграции

Связь с CRM

Интеграция может сопоставлять разрешённые сущности CRM с контрагентами или проектами 101 и показывать сотруднику данные в привычном процессе. Схему сопоставления, источник истины и правила разрешения конфликтов нужно определить до разработки.

Отчётность и аналитика

Backend может получать разрешённые данные по расписанию и передавать их в BI. Храните дату последней успешной синхронизации, используйте доступные фильтры и пагинацию из OpenAPI, не выгружайте все данные без необходимости.

Автоматизация задач

Можно построить процесс, который читает задачи, сверяет сроки и уведомляет ответственных. Если процесс меняет статус или добавляет комментарий, он должен показывать целевую задачу и новое значение до выполнения.

Документы

Если схема содержит подходящий метод генерации документа, перед запросом проверьте компанию, проект, период и тип документа. Полученный файл храните и передавайте с учётом его чувствительности и срока жизни ссылки.

Операции записи и подтверждения

В прямом API нет универсального диалогового подтверждения, аналогичного MCP. Ответственность лежит на интеграции. Для денег, приглашений, удаления и массовых изменений используйте следующий шаблон:

получить актуальное состояние сущности;
рассчитать изменение без записи;
показать пользователю компанию, сущность, старое и новое значение;
получить явное подтверждение;
выполнить ровно один запрос с подтверждёнными параметрами;
перечитать сущность и сохранить результат аудита без секретов.

Не используйте автоматические повторы для неидемпотентного POST, пока не доказано, что повтор не создаст дубль.

Безопасность

Храните пароль и токены только на backend или в защищённом хранилище секретов.
Передавайте данные только по HTTPS.
Не добавляйте JWT в URL, query string и логи.
Маскируйте заголовок Authorization и чувствительные поля в трассировке.
Разделяйте production, тестовые окружения и их секреты.
Выдавайте сервису минимально необходимые права.
Ограничивайте исходящие запросы точным доменом 101.
Проверяйте зависимые библиотеки и регулярно обновляйте их.
При компрометации немедленно отзывайте сессии и меняйте пароль.

Как обрабатывать ошибки

Код	Что означает	Действие клиента
400	Запрос не прошёл валидацию или нарушает бизнес-правило	Не повторять вслепую; показать понятную ошибку и исправить параметры
401	Авторизация отсутствует, истекла или недействительна	Безопасно обновить токен либо запросить новый вход
403	Пользователь авторизован, но не имеет нужного права	Не обходить ограничение; проверить роль и компанию
404	Сущность не найдена или недоступна в текущем контексте	Проверить path и выбранную компанию, не раскрывать чужие данные
429	Слишком много запросов, если ограничение применяется к методу	Уважать Retry-After и использовать backoff
5xx	Временная серверная ошибка	Логировать request id без секретов и повторять только безопасные операции

Фактические коды конкретного метода проверяйте в OpenAPI. Не обещайте пользователю, что одна таблица покрывает все бизнес-ошибки.

Пагинация, фильтры и объём данных

У разных методов могут отличаться параметры страницы, размер выдачи, сортировка и фильтры. Используйте только поля, перечисленные в актуальной схеме. Не придумывайте общий параметр limit или page для всего API.

обрабатывайте следующую страницу, пока контракт сообщает о её наличии;
фиксируйте стабильную сортировку, если метод её поддерживает;
ограничивайте период и компанию;
кэшируйте только там, где допустима задержка данных;
не храните ответы дольше, чем требует сценарий.

Ограничения

Публичность документации не означает публичность данных: методы защищены авторизацией и правами.
API возвращает только то, что разрешено текущему пользователю и бизнес-правилами.
Не все внутренние возможности интерфейса 101 обязаны иметь публичный метод.
OpenAPI может обновляться; генерацию клиента и проверки контракта нужно повторять.
Тестовый и dev-серверы в схеме не означают автоматического доступа партнёра к этим окружениям.
Точные лимиты конкретного метода нельзя считать одинаковыми для всего API без явного контракта.

Чек-лист перед запуском

Используется production-домен и актуальный path из OpenAPI.
Секреты находятся на backend и исключены из логов.
Обрабатываются истечение и ротация токенов.
Компания выбирается явно, а не по позиции в списке.
Реализованы пагинация и защита от дублей.
Для опасных записей есть preview и явное подтверждение пользователя.
Интеграция различает 400, 401, 403, 404 и временные ошибки.
После записи выполняется контрольное чтение.
Есть способ отключить интеграцию и удалить сохранённые секреты.