210 lines
13 KiB
HTML
210 lines
13 KiB
HTML
<!doctype html>
|
||
<html lang="ru">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<meta name="description" content="Публичная документация API сервисов OVE">
|
||
<title>OVE API Reference</title>
|
||
<link rel="stylesheet" href="/styles.css">
|
||
<script src="/app.js" defer></script>
|
||
</head>
|
||
<body>
|
||
<div class="noise" aria-hidden="true"></div>
|
||
<aside class="sidebar" id="sidebar">
|
||
<a class="brand" href="#top" aria-label="OVE API">
|
||
<span class="brand-mark">O</span>
|
||
<span><strong>OVE</strong><small>API reference</small></span>
|
||
</a>
|
||
<nav aria-label="Основная навигация">
|
||
<a href="#overview">Обзор</a>
|
||
<a href="#quickstart">Быстрый старт</a>
|
||
<a href="#auth">Авторизация</a>
|
||
<a href="#messenger">Messenger API</a>
|
||
<a href="#bots">Bot API</a>
|
||
<a href="#oauth">OAuth / OIDC</a>
|
||
<a href="#gateway">Crypto Gateway</a>
|
||
<a href="#donations">Donations + OBS</a>
|
||
<a href="#webhooks">Webhooks</a>
|
||
<a href="#errors">Ошибки</a>
|
||
</nav>
|
||
<div class="sidebar-foot">
|
||
<span class="status-dot"></span> Production polygon
|
||
<a href="/openapi/messenger.json" download>Messenger OpenAPI ↗</a>
|
||
<a href="/openapi/gateway.json" download>Gateway OpenAPI ↗</a>
|
||
<a href="/openapi/donations.json" download>Donations OpenAPI ↗</a>
|
||
</div>
|
||
</aside>
|
||
|
||
<main id="top">
|
||
<header class="topbar">
|
||
<button class="menu" id="menu" aria-label="Открыть меню" aria-expanded="false">☰</button>
|
||
<label class="search">
|
||
<span>⌕</span>
|
||
<input id="search" type="search" placeholder="Поиск endpoint, пути или метода…" autocomplete="off">
|
||
<kbd>/</kbd>
|
||
</label>
|
||
<a class="spec-link" href="/openapi/gateway.json">OpenAPI</a>
|
||
</header>
|
||
|
||
<section class="hero" id="overview">
|
||
<div class="eyebrow">PUBLIC API · OVE.RS</div>
|
||
<h1>Один вход.<br><em>Все сервисы OVE.</em></h1>
|
||
<p class="lead">Документация публичных HTTP API Messenger, Crypto Gateway и Donation Service: авторизация, сообщения, боты, платежи, OBS alerts, webhooks и операторские методы.</p>
|
||
<div class="hero-actions">
|
||
<a class="button primary" href="#quickstart">Начать интеграцию</a>
|
||
<a class="button secondary" href="#endpoints">Все endpoints</a>
|
||
</div>
|
||
<div class="service-strip">
|
||
<article><span class="service-icon messenger">M</span><div><b>Messenger</b><code>https://ms.ove.rs</code></div><i>REST · OAuth · WS</i></article>
|
||
<article><span class="service-icon gateway">C</span><div><b>Crypto Gateway</b><code>https://cr.ove.rs</code></div><i>REST · HMAC</i></article>
|
||
<article><span class="service-icon donations">D</span><div><b>Donations</b><code>https://do.ove.rs</code></div><i>REST · SSE · OBS</i></article>
|
||
</div>
|
||
</section>
|
||
|
||
<section class="doc-section" id="quickstart">
|
||
<div class="section-label">01 — Quick start</div>
|
||
<h2>Первый запрос</h2>
|
||
<p>Все ответы API — JSON, если endpoint явно не обозначен как HTML, WebSocket или файл. Для Messenger получите токен через email-код, затем передавайте его в заголовке Bearer.</p>
|
||
<div class="code-card">
|
||
<div class="code-head"><span>Email login</span><button class="copy" data-copy-target="quick-code">Копировать</button></div>
|
||
<pre id="quick-code"><code>curl -X POST https://ms.ove.rs/auth/email/start \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"email":"you@example.com"}'
|
||
|
||
curl -X POST https://ms.ove.rs/auth/email/verify \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"email":"you@example.com","code":"123456"}'</code></pre>
|
||
</div>
|
||
<div class="callout"><strong>HTTPS в тестовом полигоне.</strong> Сертификаты выпущены локальным CA OVE. Добавьте CA в доверенные на устройстве; не отключайте проверку TLS в production-клиенте.</div>
|
||
</section>
|
||
|
||
<section class="doc-section" id="auth">
|
||
<div class="section-label">02 — Security</div>
|
||
<h2>Три схемы авторизации</h2>
|
||
<div class="auth-grid">
|
||
<article><span>01</span><h3>Messenger Bearer</h3><p>Пользовательский или bot token передается как <code>Authorization: Bearer <token></code>.</p></article>
|
||
<article><span>02</span><h3>Gateway HMAC</h3><p>Каждый merchant-запрос подписывается ключом, timestamp и одноразовым UUID nonce.</p></article>
|
||
<article><span>03</span><h3>Operator Bearer</h3><p><code>/admin/v1/*</code> принимает отдельный секрет <code>GATEWAY_ADMIN_TOKEN</code>.</p></article>
|
||
</div>
|
||
<h3>Каноническая строка Gateway</h3>
|
||
<pre><code>timestamp + "\n" +
|
||
nonce + "\n" +
|
||
HTTP_METHOD + "\n" +
|
||
path_and_query + "\n" +
|
||
hex(sha256(raw_request_body))</code></pre>
|
||
<p>Результат подпишите HMAC-SHA256 и отправьте lowercase hex в <code>X-Api-Signature</code>. Также обязательны <code>X-Api-Key</code>, <code>X-Api-Timestamp</code>, <code>X-Api-Nonce</code>; для изменяющих запросов — <code>Idempotency-Key</code>.</p>
|
||
</section>
|
||
|
||
<section class="doc-section" id="messenger">
|
||
<div class="section-label">03 — Messenger</div>
|
||
<h2>Клиенты, сообщения и real-time</h2>
|
||
<p>HTTP API покрывает аккаунты, чаты, E2E-ключи, файлы, голосовые сессии, Dastars и очередь обновлений. Native Android транспорт MST5 работает через общий router на <code>ms.ove.rs:8067</code>: после защищённого handshake он передаёт CBOR-команды и мультиплексированные ответы внутри зашифрованного потока.</p>
|
||
<div class="facts">
|
||
<div><b>Updates</b><span>long polling + ACK</span></div>
|
||
<div><b>Voice</b><span>WebSocket ticket</span></div>
|
||
<div><b>E2E</b><span>не зависит от username</span></div>
|
||
<div><b>Files</b><span>multipart upload</span></div>
|
||
</div>
|
||
</section>
|
||
|
||
<section class="doc-section" id="bots">
|
||
<div class="section-label">04 — Bots</div>
|
||
<h2>Bot API</h2>
|
||
<p>Создайте бота через проверенного <code>botfather</code> или <code>POST /bots</code>. Bot token использует ту же Bearer-схему. Обновления хранятся до подтверждения через <code>POST /updates/ack</code>.</p>
|
||
<div class="two-col">
|
||
<div><h3>Кнопки</h3><p><code>url</code>, <code>callback</code> и <code>pay_dsr</code>; не более 12 кнопок, текст до 64 символов.</p></div>
|
||
<div><h3>Реакции</h3><p>Бот получает callback для обычных и платных реакций. Пакет платной реакции может содержать <code>amount > 1</code>.</p></div>
|
||
</div>
|
||
</section>
|
||
|
||
<section class="doc-section" id="oauth">
|
||
<div class="section-label">05 — Identity</div>
|
||
<h2>OAuth 2.0 Device Flow + OIDC</h2>
|
||
<p>Сервис запрашивает device code у Messenger, показывает QR или user code, а пользователь подтверждает вход в Android-клиенте. Токен обменивается только после решения пользователя.</p>
|
||
<div class="flow"><span>1 · device_authorization</span><b>→</b><span>2 · QR / code</span><b>→</b><span>3 · approve</span><b>→</b><span>4 · token</span></div>
|
||
</section>
|
||
|
||
<section class="doc-section" id="gateway">
|
||
<div class="section-label">06 — Payments</div>
|
||
<h2>Crypto Gateway</h2>
|
||
<p>Создавайте invoice и withdrawal, сверяйте баланс и принимайте подписанные callbacks. Денежные величины всегда передаются строками в атомарных единицах — без float.</p>
|
||
<div class="asset-table" role="table" aria-label="Поддерживаемые активы">
|
||
<div class="thead"><span>Asset</span><span>Network</span><span>Decimals</span></div>
|
||
<div><b>BTC</b><span>bitcoin</span><code>8</code></div>
|
||
<div><b>LTC</b><span>litecoin</span><code>8</code></div>
|
||
<div><b>TON</b><span>ton</span><code>9</code></div>
|
||
<div><b>TRX</b><span>tron</span><code>6</code></div>
|
||
<div><b>USDT</b><span>ton / tron</span><code>6</code></div>
|
||
</div>
|
||
<div class="callout"><strong>Hosted checkout.</strong> URL из ответа invoice открывается как <code>/pay/{token}</code>; JSON-статус доступен в <code>/pay/{token}/status</code>. Таймер оплаты синхронизирован с серверным временем.</div>
|
||
</section>
|
||
|
||
<section class="doc-section" id="webhooks">
|
||
<div class="section-label">07 — Events</div>
|
||
<h2>Подпись callbacks</h2>
|
||
<pre><code>signature = hex(HMAC-SHA256(
|
||
webhook_secret,
|
||
timestamp + "." + event_id + "." + raw_body
|
||
))</code></pre>
|
||
<p>Проверяйте <code>X-Gateway-Timestamp</code>, <code>X-Gateway-Event-Id</code> и <code>X-Gateway-Signature</code>. Доставка at-least-once повторяется до 24 часов — дедуплицируйте события по <code>event_id</code>.</p>
|
||
</section>
|
||
|
||
<section class="doc-section" id="donations">
|
||
<div class="section-label">08 — Donations</div>
|
||
<h2>Страница доната и OBS Browser Source</h2>
|
||
<p>Стример входит через Messenger, получает публичный адрес <code>do.ove.rs/u/{slug}</code> и секретную ссылку виджета. Доноры авторизоваться не обязаны: Donation Service создаёт invoice в Crypto Gateway и показывает его hosted checkout.</p>
|
||
<div class="flow"><span>1 · public donation</span><b>→</b><span>2 · Gateway checkout</span><b>→</b><span>3 · signed webhook</span><b>→</b><span>4 · OBS SSE alert</span></div>
|
||
<div class="callout"><strong>Вывод средств.</strong> Каждый запрос резервирует доступный баланс и отдельно подтверждается свайпом в Messenger. В окне подтверждения показаны актив, сумма, сеть и сокращённый адрес.</div>
|
||
</section>
|
||
|
||
<section class="doc-section endpoints-section" id="endpoints">
|
||
<div class="section-label">09 — Reference</div>
|
||
<h2>Все endpoints</h2>
|
||
<div class="endpoint-toolbar">
|
||
<div id="service-filters" class="filters"></div>
|
||
<span id="endpoint-count"></span>
|
||
</div>
|
||
<div id="endpoint-list" class="endpoint-list" aria-live="polite"></div>
|
||
<div id="empty" class="empty" hidden>Ничего не найдено. Попробуйте другой запрос.</div>
|
||
</section>
|
||
|
||
<section class="doc-section" id="errors">
|
||
<div class="section-label">10 — Errors</div>
|
||
<h2>Ошибки и повторные запросы</h2>
|
||
<div class="error-grid">
|
||
<div><code>400</code><span>Неверные поля или состояние</span></div>
|
||
<div><code>401</code><span>Нет или неверна авторизация</span></div>
|
||
<div><code>403</code><span>Недостаточно прав</span></div>
|
||
<div><code>404</code><span>Объект не найден</span></div>
|
||
<div><code>409</code><span>Конфликт / повтор</span></div>
|
||
<div><code>429</code><span>Превышен лимит</span></div>
|
||
<div><code>5xx</code><span>Временная ошибка сервиса</span></div>
|
||
</div>
|
||
<p>Для безопасного повтора merchant POST используйте тот же <code>Idempotency-Key</code>. Не повторяйте запрос с новым ключом, пока результат предыдущего неизвестен.</p>
|
||
</section>
|
||
|
||
<footer>
|
||
<span>OVE API · public contract</span>
|
||
<span>Internal wallet gRPC и системные bot nodes не публикуются.</span>
|
||
</footer>
|
||
</main>
|
||
|
||
<template id="endpoint-template">
|
||
<article class="endpoint">
|
||
<button class="endpoint-summary" type="button" aria-expanded="false">
|
||
<span class="method"></span>
|
||
<code class="path"></code>
|
||
<span class="endpoint-title"></span>
|
||
<span class="auth-badge"></span>
|
||
<span class="chevron">⌄</span>
|
||
</button>
|
||
<div class="endpoint-body">
|
||
<p class="endpoint-description"></p>
|
||
<div class="endpoint-meta"></div>
|
||
<div class="endpoint-example"></div>
|
||
</div>
|
||
</article>
|
||
</template>
|
||
</body>
|
||
</html>
|