Выписки

Заказ выписки в банк, ожидание готовности (асинхронно), скачивание в одном из 4 форматов: 1c v1.02 / 1c v1.03 / csv / json.

:::info Требования к токену Все endpoint'ы ниже требуют:

• purpose=integration;
• scope_read_statements=true + per-account allow_read_statements=true на целевом РС. :::

Жизненный цикл заявки

Поток асинхронный: POST создаёт запись в статусе processing и инициирует запрос в банк. Фоновый worker опрашивает банк каждые 30 секунд и обновляет статус. Клиент опрашивает GET /statements/{id} до status=ready, после чего качает в нужном формате.

POST /statements                          → status=processing
GET  /statements/{id}                     → processing | ready | failed
GET  /statements/{id}/export?format=1c    → 1C v1.02 / v1.03 (cp1251)
GET  /statements/{id}/export?format=csv   → UTF-8 CSV
GET  /statements/{id}/export?format=json  → JSON

Request — POST /statements

POST /api/v1/integration/statements

Заказывает выписку за период. Идемпотентен по external_id: повтор с тем же external_id и теми же параметрами → 200 с существующим statement_id, банк не вызывается повторно.

Тело запроса (application/json)

curl --silent --show-error -X POST \
     -H "Authorization: Bearer bcs_live_<TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "bank_account_id": "<bank-account-uuid>",
       "external_id":     "ERP-stmt-2026-05-18-account-123",
       "date_from":       "2026-05-01",
       "date_to":         "2026-05-17"
     }' \
     "https://bsc.example.com/api/v1/integration/statements"

{
  "statement_id": "<uuid>",
  "status": "processing",
  "bank_account_id": "<bank-account-uuid>",
  "external_id": "ERP-stmt-2026-05-18-account-123",
  "date_from": "2026-05-01",
  "date_to": "2026-05-17",
  "created_at": "2026-05-18T09:48:29Z"
}

:::warning Лимит периода — 31 день Этот предел продиктован самым строгим из поддерживаемых банков (тоже самое ограничение действует в их собственных API). Запрашивать выписки за более длинный период — несколькими подряд идущими request'ами по 31 дню. :::

Poll — GET /statements/{statement_id}

GET /api/v1/integration/statements/{statement_id}

Опрос статуса. Рекомендуется не чаще одного раза в 5 секунд (worker сам опрашивает банк каждые 30s, чаще не имеет смысла).

curl --silent --show-error \
     -H "Authorization: Bearer bcs_live_<TOKEN>" \
     "https://bsc.example.com/api/v1/integration/statements/<statement_id>"

{
  "statement_id": "<uuid>",
  "status": "ready",
  "bank_account_id": "<bank-account-uuid>",
  "external_id": "ERP-stmt-2026-05-18-account-123",
  "date_from": "2026-05-01",
  "date_to": "2026-05-17",
  "created_at": "2026-05-18T09:48:29Z",
  "fetched_at": "2026-05-18T09:48:57Z",
  "operations_count": 42
}

Поля ответа

Export — GET /statements/{id}/export

GET /api/v1/integration/statements/{statement_id}/export?format=<format>&version=<version>

Скачивает выписку в выбранном формате. Требует status=ready (иначе 409 not_ready).

Параметры query-string

1C v1.02 / v1.03 — стандарт 1С

Кодировка cp1251 (как ждёт 1С). Charset в Content-Type явно проставляется. Имя файла — stmt_<account_alias>_<from>_<to>.txt.

curl --silent --show-error -OJ \
     -H "Authorization: Bearer bcs_live_<TOKEN>" \
     "https://bsc.example.com/api/v1/integration/statements/<statement_id>/export?format=1c&version=1.03"

csv — UTF-8 с заголовком

Кодировка utf-8, разделитель ,, экранирование по RFC 4180. Колонки: doc_date, doc_number, amount, currency, direction, payer_inn, payer_name, payer_account, payee_inn, payee_name, payee_account, purpose.

curl --silent --show-error -OJ \
     -H "Authorization: Bearer bcs_live_<TOKEN>" \
     "https://bsc.example.com/api/v1/integration/statements/<statement_id>/export?format=csv"

json — машинно-читаемый

UTF-8, без обёртки. Структура: {"statement_id", "bank_account_id", "period_from", "period_to", "operations": [{"direction", "doc_type", "doc_number", "doc_date", "amount", "currency", "purpose", "payer": {…}, "payee": {…}}]}. Account-номера контрагентов в открытом виде (не masked), так как это машинно-читаемый формат и клиент сам решает, что показывать пользователю.

curl --silent --show-error \
     -H "Authorization: Bearer bcs_live_<TOKEN>" \
     "https://bsc.example.com/api/v1/integration/statements/<statement_id>/export?format=json"

Идемпотентность

:::info Тот же external_id + те же (bank_account_id, date_from, date_to) → 200 OK с существующим statement_id, банк не вызывается повторно. :::

Тот же external_id с другим периодом / РС → 409 conflict. Чтобы заказать выписку с другими параметрами — выпустить новый external_id (например, добавить timestamp / hash в строку).

Edge cases — wire-словарь

bank_not_supported (HTTP 501)

Если банк-адаптер не реализует SupportsStatements, backend возвращает 501 с error.code = "bank_not_supported" (не not_supported). Префикс bank_ добавляет общий bank-error классификатор. HTTP-status (501) — стабильнее для matching'а.

invalid JSON body — HTTP 400

Невалидный JSON или malformed UUID в body — общий decodeJSON возвращает error.code = "invalid request body" (сообщение на английском). Поведенчески эквивалентно validation_error; срабатывает до ручного валидатора.

not_ready на export — HTTP 409

GET /export?format=… при status != ready → 409 not_ready. Дождитесь готовности через poll.

Ошибки