Первый запрос за две минуты

Subdued передаёт документы и уведомления между системами вашей компании через обычный REST API. Всё, что нужно для старта, собрано на этой странице.

curl https://api.subduedenterprise.ru/v2/documents \
  -H "Authorization: Bearer $SUBDUED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Акт сверки за сентябрь", "recipient": "org_4f2a91"}'

{
  "id": "doc_7c1e0b",
  "title": "Акт сверки за сентябрь",
  "status": "pending",
  "created_at": "2026-09-28T09:14:03Z"
}

Чтобы повторить пример, выполните три шага:

1. Войдите в личный кабинет и откройте раздел «Интеграции».
2. Создайте токен с правами documents:write и сохраните его в переменную окружения SUBDUED_TOKEN.
3. Отправьте запрос выше. Документ появится в списке со статусом pending, пока получатель его не откроет.

Аутентификация

Каждый запрос подписывается токеном в заголовке Authorization со схемой Bearer. Токен показывается один раз при создании: если вы его потеряли, выпустите новый и отзовите старый.

Токен действует 90 дней. За неделю до окончания срока владелец получает письмо со ссылкой на перевыпуск.

Права доступа

Формат запросов

API принимает и возвращает JSON в кодировке UTF-8. Даты передаются в формате ISO 8601 и всегда в UTC, а идентификаторы начинаются с префикса типа объекта: doc_, org_, evt_.

Безопасные повторы

Если запрос на создание оборвался по сети, его можно отправить ещё раз, не боясь дубликата. Добавьте заголовок Idempotency-Key с уникальным значением, например UUID:

curl https://api.subduedenterprise.ru/v2/documents \
  -H "Authorization: Bearer $SUBDUED_TOKEN" \
  -H "Idempotency-Key: 6b0f9c3e-2d5a-4b7e-9f11-0c8a3d6e1a52" \
  -d '{"title": "Счёт № 1024", "recipient": "org_4f2a91"}'

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

Пагинация

Списки возвращаются страницами. Размер страницы задаётся параметром limit (от 1 до 100, по умолчанию 25). Чтобы получить следующую страницу, передайте в параметре cursor значение next_cursor из предыдущего ответа.

GET /v2/documents?limit=2&cursor=eyJvIjoyfQ

{
  "data": [ /* два документа */ ],
  "next_cursor": "eyJvIjo0fQ",
  "has_more": true
}

Когда has_more равен false, документы закончились. Курсор нужно считать непрозрачной строкой: не разбирайте её и не собирайте самостоятельно.

Вебхуки

Вместо постоянных опросов подпишитесь на события: Subdued сам отправит POST-запрос на ваш адрес, когда статус документа изменится.

События

Проверка подписи

Каждый запрос содержит заголовок Subdued-Signature: HMAC-SHA256 от тела запроса, посчитанный на секрете вашей подписки. Сравните его со своим значением до того, как доверять содержимому.

# Python
import hmac, hashlib

expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, header_signature):
    return "forbidden", 403

Ответьте кодом 2xx в течение 10 секунд. Иначе доставка повторится ещё пять раз с нарастающими паузами: 1 минута, 5 минут, 30 минут, 2 часа, 12 часов. После этого событие остаётся доступным в журнале доставок кабинета.

Коды ошибок

При ошибке API возвращает соответствующий HTTP-код и JSON с полями code и message. Логику программы стоит строить на code: текст сообщения может меняться.

Лимиты

На один токен приходится до 60 запросов в минуту. Текущее состояние лимита видно в заголовках каждого ответа:

• RateLimit-Limit: сколько запросов разрешено в окне;
• RateLimit-Remaining: сколько осталось;
• RateLimit-Reset: через сколько секунд окно обнулится.

Размер тела запроса не должен превышать 5 МБ. Для файлов большего размера используйте загрузку по частям, она описана в разделе «Документы» личного кабинета.

Журнал изменений

Версия 2.415 сентября 2026

Добавлено событие document.expired. Параметр limit в списках теперь принимает значения до 100.

Версия 2.32 июля 2026

Появился заголовок Idempotency-Key для запросов на создание. Срок жизни токенов сокращён со 180 до 90 дней.

Версия 2.221 апреля 2026

Пагинация переведена на курсоры. Параметр page объявлен устаревшим и будет удалён в версии 3.0.