Finance OS / API

OpenAPI-спецификация

Машиночитаемое описание контура клиентских кошельков Merchant API в формате OpenAPI 3.1 (YAML): клиенты, крипто-кошельки, выводы, расчёты, мастер-счёт, AML-проверки и песочница. Импортируйте файл в Postman, Insomnia или Swagger UI, либо сгенерируйте по нему клиент на своём языке.

ℹ
Ссылка на файл

https://www.fin-os.io/docs/openapi/customer-wallets.yaml

Файл открыт без авторизации и отдаётся с типом application/yaml. Он описывает только контракт интеграции - секретов и внутренних деталей платформы в нём нет.

Что описано

Клиенты optional
Создание и поиск, карточка, обновление, удаление, блокировка и разблокировка, единая история операций. Подробности - Customers.
Кошельки клиентов optional
Адреса пополнения, балансы, журнал движений, принудительная сверка, предпросмотр и создание вывода, статус заявки, расчёты charge и payout. Подробности - Customer Wallets.
Мастер-счёт optional
Баланс, леджер, адрес пополнения, внутренние переводы, витрина цен и лимитов. Подробности - Merchant Balance.
AML-проверки optional
Проверка адреса, список и карточка проверки, выгрузка PDF. Подробности - AML Screening.
Песочница optional
Симуляция депозита тестовым ключом. Подробности - Sandbox.

Разделы верификации, платежей и виртуальных карт в этот файл не входят - они описаны на своих страницах документации.

Соглашения спецификации

  • Аутентификация - схема bearerAuth: заголовок Authorization: Bearer sk_live_… либо sk_test_…. Окружение выбирается префиксом ключа.
  • Успех - конверт {"data": …}; списки дополняются объектом meta.
  • Ошибка - конверт {"error": {"code", "message", "request_id"}}, реестр кодов - в схеме Error и на странице Error Codes.
  • Суммы - строки, разбирайте как decimal.
  • Идемпотентность - заголовок Idempotency-Key обязателен у вывода, charge, payout и внутренних переводов мастер-счёта; необязателен у AML-проверки.
⚠
Документация первична
Спецификация описывает форму запросов и ответов, но не поведение: порядок проверок при выводе, семантику полей status и state, правила повторов вебхуков и условия тарификации смотрите на страницах раздела. Файл обновляется вместе с API - подтягивайте его перед генерацией клиента.

Примеры кода

# Скачать спецификацию
curl -o finance-os-customer-wallets.yaml \
  https://www.fin-os.io/docs/openapi/customer-wallets.yaml

# Быстрый просмотр в Swagger UI (docker)
docker run --rm -p 8080:8080 \
  -e SWAGGER_JSON=/spec/finance-os-customer-wallets.yaml \
  -v "$PWD:/spec" swaggerapi/swagger-ui
# Генерация клиента (openapi-generator)
# pip install openapi-generator-cli
import urllib.request

SPEC = 'https://www.fin-os.io/docs/openapi/customer-wallets.yaml'

urllib.request.urlretrieve(SPEC, 'finance-os-customer-wallets.yaml')

# openapi-generator-cli generate \
#   -i finance-os-customer-wallets.yaml \
#   -g python \
#   -o ./finos-client