SafeMatch API

Публичное API платформы SafeMatch для P2P-обмена криптовалюты на фиат. Данный документ описывает все доступные методы для интеграции площадок с SafeMatch.

1. Аутентификация

Все запросы к API (кроме /health) требуют аутентификации. Для аутентификации используются три обязательных заголовка:

Формирование подписи

Подпись формируется по следующему алгоритму:

1. Составить строку для подписи: HTTP_МЕТОД + ПУТЬ + TIMESTAMP + ТЕЛО_ЗАПРОСА
   • HTTP_МЕТОД — метод запроса заглавными буквами (POST, GET, DELETE)
   • ПУТЬ — путь запроса (например, /orders)
   • TIMESTAMP — значение заголовка X-Timestamp
   • ТЕЛО_ЗАПРОСА — JSON-тело, сериализованное с отсортированными ключами и без пробелов (разделители: , и :). Для запросов без тела эта часть опускается
2. Вычислить HMAC-SHA256 от полученной строки, используя ваш секретный ключ
3. Результат передать в заголовке X-Signature в hex-формате

Пример (Python):

import hmac
import hashlib
import json
import time

api_key = "ваш-api-key"
secret_key = "ваш-secret-key"

method = "POST"
path = "/orders"
timestamp = str(int(time.time()))

body = {"side": "IN", "min_price": 90.0, "max_price": 95.0,
        "fiat": "RUB", "token": "USDT", "fiat_qty": 10000}
body_str = json.dumps(body, sort_keys=True, separators=(",", ":"))

message = method + path + timestamp + body_str
signature = hmac.new(secret_key.encode(), message.encode(), hashlib.sha256).hexdigest()

headers = {
    "X-API-Key": api_key,
    "X-Timestamp": timestamp,
    "X-Signature": signature,
    "Content-Type": "application/json"
}

Для загрузки файлов (например, чек в формате PDF) подпись формируется аналогично, но тело запроса в подпись не включается — используется только МЕТОД + ПУТЬ + TIMESTAMP.

---

2. Управление заявками

Сводная таблица

---

Создаёт новую заявку на покупку (IN) или продажу (OUT) криптовалюты.

Тело запроса (IN — покупка криптовалюты):

{
  "side": "IN",
  "min_price": 90.0,
  "max_price": 95.0,
  "fiat": "RUB",
  "token": "USDT",
  "fiat_qty": 10000
}

Тело запроса (OUT — продажа криптовалюты):

{
  "side": "OUT",
  "min_price": 90.0,
  "max_price": 95.0,
  "fiat": "RUB",
  "token": "USDT",
  "fiat_qty": 50000,
  "max_payments": 3,
  "banks": [
    {
      "bank_name": "Сбербанк",
      "recipient_details": "2200 0000 0000 0000",
      "recipient_name": "Иван Иванов",
      "detail_type": "CARD",
      "priority": 1
    }
  ]
}

Объект banks[]:

Успешный ответ:

{
  "id": "a1b2c3d4-...",
  "side": "IN",
  "min_price": 90.0,
  "max_price": 95.0,
  "fiat": "RUB",
  "token": "USDT",
  "fiat_qty": 10000,
  "max_payments": null,
  "banks": null,
  "status": "waiting",
  "created_at": "2026-03-09T12:00:00"
}

Возможные ошибки:

---

Удаляет вашу заявку. Удаление возможно только для заявок в статусе «Ожидание сопоставления».

Параметры:

Успешный ответ:

{
  "id": "a1b2c3d4-...",
  "result": "success"
}

Возможные ошибки:

---

Загружает PDF-файл чека об оплате для IN-заявки (покупка). После загрузки заявка переходит в статус «Ожидание подтверждения» — продавец должен подтвердить получение средств.

Формат запроса: multipart/form-data

Параметры:

Успешный ответ:

{
  "id": "a1b2c3d4-...",
  "result": "success"
}

Возможные ошибки:

---

Создатель OUT-заявки (продавец) подтверждает, что получил фиатный перевод от покупателя. После подтверждения заявка покупателя завершается, криптовалюта зачисляется покупателю.

Параметры:

Успешный ответ:

{
  "id": "a1b2c3d4-...",
  "result": "success"
}

Возможные ошибки:

---

Создатель OUT-заявки (продавец) не подтверждает получение оплаты по загруженному чеку. Автоматически создаётся апелляция для разбирательства.

Параметры:

Тело запроса:

{
  "reason": "check_not_confirmed",
  "description": "Оплата не поступила на указанный счёт"
}

Допустимые причины (reason): check_not_confirmed

Успешный ответ:

{
  "appeal_id": "appeal-uuid-...",
  "order_id": "out-order-uuid-...",
  "reason": "check_not_confirmed",
  "status": "waiting_confirmation",
  "created_at": "2026-03-09T12:00:00"
}

Возможные ошибки:

---

Если один из IN-ордеров в вашей OUT-заявке был отменён, система автоматически ищет замену. Этот метод позволяет отменить поиск замены и продолжить с текущими IN-заявками.

Параметры:

Успешный ответ:

{
  "id": "a1b2c3d4-...",
  "result": "success"
}

Возможные ошибки:

---

3. Апелляции

Создаёт апелляцию по завершённой заявке. Доступно для обоих участников сделки (создатель IN и создатель OUT).

Тело запроса:

{
  "order_id": "a1b2c3d4-...",
  "reason": "no_money_in_account",
  "description": "Средства не поступили на счёт в течение 2 часов"
}

Допустимые причины для IN-заявок (покупка):

Допустимые причины для OUT-заявок (продажа):

Успешный ответ:

{
  "appeal_id": "appeal-uuid-...",
  "order_id": "a1b2c3d4-...",
  "reason": "no_money_in_account",
  "status": "completed",
  "created_at": "2026-03-09T12:00:00"
}

Возможные ошибки:

---

4. Получение данных

Возвращает подробную информацию о заявке. Доступно только участникам сделки (создатель или контрагент).

Параметры:

Успешный ответ:

{
  "id": "a1b2c3d4-...",
  "side": "IN",
  "user_side": "IN",
  "min_price": 90.0,
  "max_price": 95.0,
  "fiat_qty": 10000,
  "fiat": "RUB",
  "token": "USDT",
  "max_payments": null,
  "banks": [...],
  "created_at": 1741510800,
  "matched_at": 1741510860,
  "status": "waiting_payment",
  "creator_id": 1,
  "contr_id": 2,
  "rate": 92.5,
  "in_orders_data": null,
  "out_order_id": "out-uuid-...",
  "receipt_data": null,
  "payment_method": null,
  "transfer_time": null,
  "crypto_amount": 108.1,
  "freezeed_crypto": null,
  "fee_collected": 0.0,
  "expected_fiat_qty": null,
  "filled_fiat_qty": null
}

---

Возвращает список ваших заявок с пагинацией, сортировкой и фильтрами.

Параметры (query):

Успешный ответ:

{
  "orders": [
    {
      "id": "a1b2c3d4-...",
      "side": "IN",
      "status": "waiting",
      "fiat_qty": 10000,
      "fiat": "RUB",
      "token": "USDT",
      "created_at": 1741510800,
      ...
    }
  ],
  "total_count": 42,
  "page": 1,
  "page_size": 10,
  "total_pages": 5
}

---

5. Скачивание чека

Возвращает PDF-файл чека по его идентификатору. Доступно только участникам сделки.

Параметры:

ID чека можно получить из поля receipt_data в данных заявки.

Ответ: PDF-файл (application/pdf).

Возможные ошибки:

---

6. WebSocket-уведомления

Для получения уведомлений в реальном времени подключитесь к WebSocket-сервису по адресу wss://ws.safematch.pro. Документация по подключению доступна через GET /ws/docs.

Типы уведомлений:

Каждое уведомление содержит актуальные данные по заявке, включая статус, реквизиты и прочие параметры.

---

7. Статусы заявок

---

8. Общие коды ответов