Sapita

API Sapita

Подключите своё ПО к своим книгам. Каждый ключ ограничен одной компанией и доступом, который ему нужен, и его можно отозвать в любой момент.

Для чего нужен API

API предназначен для разработчиков, которые хотят работать с книгами компании из собственного ПО. Создавайте черновики счетов, читайте счета и отчёты, отправляйте документы поставщиков в Sapita и импортируйте файлы банковских выписок.

Читать справку по API

Как начать

  1. Создайте ключ в настройках компании. Дайте ему имя, выберите области доступа и, если хотите, дату истечения.
  2. Передавайте ключ с каждым запросом по HTTPS в заголовке Authorization как bearer-токен.
  3. Читайте справку по конечным точкам, которые разрешают ваши области доступа, и вызывайте их из своего ПО.

Ключи API и области доступа

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

Храните ключи в секрете: не публикуйте их в открытых репозиториях и в коде браузера. Если ключ утёк, отзовите его в настройках и создайте новый.

Ограничения частоты запросов

Для каждого ключа установлен лимит запросов за период. Запрос сверх лимита получает ответ 429 с заголовком Retry-After, чтобы ваше ПО могло подождать и повторить попытку. Запросы на создание принимают заголовок Idempotency-Key, поэтому повтор после таймаута не создаёт вторую запись.

Актуальные лимиты, а также лимиты добросовестного использования для записи и хранения документов указаны в справке.

Ошибки и версии

Ошибки возвращаются в стандартном формате problem details, поэтому каждая из них называет свой тип, статус и причину. Версия входит в путь, например /v1. Изменения внутри версии только добавляют возможности, поэтому интеграция, построенная сегодня, продолжит работать. Несовместимое изменение выйдет с новой версией.

SDK

Вместе с API поставляется типизированный клиент для TypeScript и JavaScript. Он создан из того же документа OpenAPI, что и справка, поэтому его типы совпадают с запросами, которые принимает сервер. Он повторяет безопасные запросы после ограничения частоты или ошибки сервера и никогда не записывает ваш ключ в журнал.

Статус

API входит в состав Sapita и доступен каждому клиенту. Описание OpenAPI для каждой версии опубликовано по адресу api.sapita.app/v1/openapi.json.