API документация

01 С чего начать

API OneSix позволяет принимать платежи через счета (invoice) и выводить средства (transfer) программно. Запросы авторизуются API-ключом проекта с HMAC-подписью.

Интеграция строится в три шага:

1. Создайте проект в личном кабинете и подтвердите владение доменом (DNS).
2. Получите API-ключ проекта: пару id + secret.
3. Подписывайте запросы ключом (HMAC-SHA256) и вызывайте методы API.

Registration → Project (pending) → Domain verification → Moderation → Project (active) → API key → API requests

Форматы идентификаторов

02 Подпись запросов (HMAC)

Все запросы к публичному API авторизуются по API-ключу и подписываются алгоритмом HMAC-SHA256. Сессия (cookie / Authorization: Bearer) для API не используется.

Ключи

У проекта один активный ключ (status: active). Ротации ключей пока нет. Секрет key возвращается методом GET /api/projects/{project_id}/api-keys/, храните его в безопасном месте.

Заголовки запроса

Подпись обязательна для всех методов публичного API (GET и POST).

Алгоритм подписи

Шаг 1. Соберите объект данных:

{
  "params": "url_encoded_query_string",
  "body": {},
  "path": "/api/invoice/"
}

• params: query-строка как в URL, без ? (например project_id=...&page=1). Для запроса без query это пустая строка "".
• body: распарсенный JSON тела запроса. Для GET-запросов без тела это пустой объект {}.
• path: путь запроса со слешами, включая префикс /api (например /api/invoice/).

Шаг 2. Сериализуйте объект строго с сортировкой ключей:

json.dumps(data, separators=(",", ":"), sort_keys=True)

Шаг 3. Вычислите подпись:

payload   = str(timestamp) + json_string
signature = HMAC-SHA256(key=secret, message=payload).hexdigest()

Шаг 4. Передайте X-API-Key-ID, X-Timestamp, X-Signature в заголовках.

Важно

• X-Timestamp должен быть в пределах ±15 секунд от серверного времени. При расхождении часов синхронизируйтесь через GET /api/-/time/.
• Подпись одноразовая. Повтор того же X-Signature вернёт 401 Signature already used!. Для каждого запроса нужны новый timestamp и новая подпись.
• TOTP (2FA) на пути API не требуется.
• Если у ключа задан список разрешённых IP, запросы принимаются только с них.

Генерация подписи

import hmac, hashlib, json, time

def sign(secret: str, timestamp: int, data: dict) -> str:
    s = json.dumps(data, separators=(",", ":"), sort_keys=True)
    payload = f"{timestamp}{s}"
    return hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()

secret     = "<key>"
api_key_id = "<uuid>"
path       = "/api/invoice/"
params     = ""
body       = {
    "name": "Order 1",
    "target_amount": 100,
    "is_termless": True,
    "is_payer_comission": True,
    "description": "",
    "private_description": "",
}

ts   = int(time.time())
data = {"params": params, "body": body, "path": path}
signature = sign(secret, ts, data)

headers = {
    "X-API-Key-ID": api_key_id,
    "X-Timestamp": str(ts),
    "X-Signature": signature,
    "Content-Type": "application/json",
}

$secret = "<key>";
$path   = "/api/invoice/";
$params = "";
$body   = [
    "name"               => "Order 1",
    "target_amount"      => 100,
    "is_termless"        => true,
    "is_payer_comission" => true,
    "description"        => "",
    "private_description"=> "",
];

$data = ["params" => $params, "body" => $body, "path" => $path];
ksort($data); // params, path, body -> sort_keys=True
$json      = json_encode($data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
$timestamp = time();
$signature = hash_hmac("sha256", $timestamp . $json, $secret);

const crypto = require("crypto");

function sign(secret, timestamp, data) {
  // sort top-level keys, compact JSON without spaces
  const ordered = {};
  Object.keys(data).sort().forEach((k) => (ordered[k] = data[k]));
  const s = JSON.stringify(ordered);
  return crypto.createHmac("sha256", secret).update(`${timestamp}${s}`).digest("hex");
}

const secret = "<key>";
const data = {
  params: "",
  body: { name: "Order 1", target_amount: 100, is_termless: true, is_payer_comission: true, description: "", private_description: "" },
  path: "/api/invoice/",
};
const ts = Math.floor(Date.now() / 1000);
const signature = sign(secret, ts, data);

Примеры запросов

# params = ""  (no query)
# body   = {}  (no body)
# path   = "/api/invoice/my/<invoice_id>/"
# data   = {"body":{},"params":"","path":"/api/invoice/my/<invoice_id>/"}

curl "https://devonesite.site/api/invoice/my/<invoice_id>/" \
  -H "X-API-Key-ID: <UUID>" \
  -H "X-Timestamp: 1718659200" \
  -H "X-Signature: <hex>"

curl "https://devonesite.site/api/invoice/" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key-ID: <UUID>" \
  -H "X-Timestamp: 1718659200" \
  -H "X-Signature: <hex>" \
  -d '{"name":"Order 1","target_amount":100,"is_termless":true,"is_payer_comission":true,"description":"","private_description":""}'

Серверное время

Возвращает текущее серверное время (unix, число). Используйте для синхронизации X-Timestamp, если часы клиента могут расходиться более чем на 15 секунд.

Какие методы принимают API-ключ

Ошибки подписи и авторизации

03 Счета (Invoice)

Счёт - это запрос на оплату фиксированной суммы. После создания возвращается адрес для оплаты и платёжная страница. Сумма указывается в фиате (target_amount), оплата поступает в USDT по текущему курсу (rate_pair: USDT_RUB, rate приходит в ответе).

POST /api/invoice/

Тело запроса (InvoiceCreateDTO)

Ответ (MyInvoiceDTO)

GET /api/invoice/my/{invoice_id}/

Возвращает ваш счёт (MyInvoiceDTO, с private_description). По ключу действует дополнительный фильтр: доступны только счета проекта этого ключа.

GET /api/invoice/{invoice_id}/

Публичная страница счёта, без авторизации. Возвращает PublicInvoiceDTO: то же, что MyInvoiceDTO, но без private_description и project_id. Используется для платёжной страницы.

Статусы счёта

04 Выводы (Transfer)

Создание вывода средств на внешний блокчейн-адрес.

POST /api/gw/transfer/

Тело запроса (WithdrawalCreateDTO)

Ответ: JSON-объект транзакции вывода (тип, статус, идентификатор операции).

05 Справочные данные

Публичные методы без авторизации, полезные при интеграции.

GET /api/gw/currencies/

Список поддерживаемых валют. Используйте поле symbol как значение symbol_id при создании вывода.

Query: search - фильтр. Ответ пагинированный (data[], pages_count, current_page, total).

Каждый элемент (CurrencyDTO):

GET /api/gw/fees/

Комиссии и минимальные суммы по символам (GwFeeDTO[]):

GET /api/gw/fees/calculate/

Расчёт комиссии для конкретной суммы.

Query (все обязательны): amount, operation_type (deposit / withdrawal / swap), symbol_id.

Ответ (GwServiceFeeCalculationDTO): symbol_id, operation_type, amount, fee_amount, net_amount, gross_amount.

GET /api/gw/currencies/rates/

Курсы валютных пар (CurrencyRateDTO[]):

06 Управление проектами

Проекты

POST /api/projects/ (ProjectCreateDTO)

PATCH /api/projects/{project_id}/ (ProjectUpdateDTO): category, description, logo_img_id (encoded id вашей картинки), brand_color (# + 6 hex). Логотип должен принадлежать вам.

Карточка проекта (ProjectDTO)

{
  "id": "uuid",
  "public_id": "aabbccddeeff",
  "name": "Shop",
  "status": "pending",
  "category": "goods",
  "site_url": "https://shop.example.com",
  "contact_telegram": "@shop",
  "description": null,
  "logo_img_id": null,
  "brand_color": null,
  "is_site_verified": false,
  "verify_method": null,
  "verify_token": null,
  "verified_at": null,
  "rejected_reason": null,
  "created_at": "...",
  "updated_at": "..."
}

status: pending → active (после верификации и одобрения модератором) / rejected / disabled.

Верификация домена (DNS)

POST /verification/: тело {"method": "dns"}. Ответ:

{
  "method": "dns",
  "verify_token": "<hex>",
  "instruction": "Add a TXT record for shop.example.com with value j1ulwfmkyj0-site-verification=<token>"
}

Покажите пользователю: добавить TXT-запись на хост из site_url со значением j1ulwfmkyj0-site-verification=<verify_token>.

POST /verification/check/: если TXT найден, is_site_verified=true, заполняется verified_at, статус остаётся pending (ждёт модерацию). Если домен уже подтверждён, вернётся 200 без ошибки. Если TXT нет, вернётся 400 Site verification failed.

API-ключи проекта

[
  {
    "id": "key uuid, this is X-API-Key-ID",
    "key": "hex secret, 64 chars",
    "status": "active",
    "created_at": "...",
    "archived_at": null
  }
]

status: active / archived. У проекта один активный ключ. Ротации пока нет.

Операции и конверсии проекта

Пагинация: page с 1, per_page по умолчанию 10. В ответе current_page = page - 1 (с нуля), pages_count, total, data[].

Операция (ProjectAdminTransactionDTO): id, type, subject (usdt/rub), symbol_id, is_incoming, amount, state (created/pending/dirty_lock/executed/cancelled), tx_hash, description, executed_at, created_at, project_id.

Конверсия (SwapOrderResponseDTO): id, from_symbol_id, to_symbol_id, from_amount, to_amount, rate, status (created/processing/executed/cancelled/failed), created_at, project_id, user.

Списки в кабинете с фильтром проекта

GET /api/invoice/?project_id=<uuid>
GET /api/transaction/?project_id=<uuid>
GET /api/gw/swap_order/?project_id=<uuid>

07 Коды ошибок

Проекты и верификация (400)

Авторизация и подпись (401)

Не найдено (404)