Introduction

Finance OS API - это REST-интерфейс к финансовой платформе Finance OS для внешних партнёров. Через него мерчант ведёт своих конечных клиентов, выдаёт им крипто-кошельки, принимает и выплачивает средства, проверяет адреса на комплаенс и принимает рублёвые платежи - всё под одним секретным ключом.

Принципы API

• REST — стандартная семантика: GET для чтения, POST для создания, PATCH для обновления, DELETE для удаления.
• JSON — тела запросов и ответов всегда в JSON. Обязательные заголовки: Content-Type: application/json, Accept: application/json.
• HTTPS-only — обычный HTTP отклоняется на уровне nginx.
• Bearer-auth - все приватные endpoints требуют Authorization: Bearer {sk_live_…}: секретный API-ключ учётной записи, выданный в кабинете. Ключ sk_test_… адресует песочницу. Детали - в разделе Authentication.
• UTF-8 — все строки, включая поля адресов и комментариев на кириллице.

Базовый URL

Production:

https://fin-os.io/api/v1

Версия зафиксирована в пути: /api/v1/…. Пути в этой документации указываются целиком, вместе с префиксом. Ломающие изменения выйдут новым major-префиксом, старый продолжит работать до объявленного срока снятия.

Формат данных

Форма ответа

Все успешные ответы имеют единую обёртку:

{
  "data": { ... },
  "meta": { ... }
}

Для списков с пагинацией добавляются поля links и meta.current_page / last_page / per_page / total — детально в Pagination.

Ошибки

Ошибки возвращают HTTP-статус из семейства 4xx/5xx и тело вида:

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."]
  }
}

Полный справочник кодов и форматов — в Errors.

Лимиты

По умолчанию: 60 запросов в минуту на ключ, 10 на IP для неавторизованных публичных endpoints. Превышение → 429 Too Many Requests. Заголовки X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After - в каждом ответе. Подробнее в Rate Limiting.

Поддержка

Технические вопросы: admin@fin-os.io. Об авариях и плановых работах мы оповещаем через статус-страницу (планируется в v1.1).

# Первый запрос: остаток мастер-счёта
curl -X GET https://fin-os.io/api/v1/merchant/balance \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Accept: application/json"

// JavaScript fetch
const TOKEN = process.env.FINOS_SECRET_KEY; // sk_live_xxx из .env

const res = await fetch('https://fin-os.io/api/v1/merchant/balance', {
  headers: {
    'Authorization': `Bearer ${TOKEN}`,
    'Accept': 'application/json',
  },
});
const balance = await res.json();
console.log(balance.data);

// PHP (Laravel HTTP)
$response = Http::withToken($token)
    ->acceptJson()
    ->get('https://fin-os.io/api/v1/merchant/balance');

$balance = $response->json('data');

import requests

TOKEN = os.environ['FINOS_SECRET_KEY']  # sk_live_xxx

r = requests.get(
    'https://fin-os.io/api/v1/merchant/balance',
    headers={
        'Authorization': f'Bearer {TOKEN}',
        'Accept': 'application/json',
    },
)
balance = r.json()['data']