English Version 🇬🇧

JetBot API v1.0

Документация по интеграции для партнеров.

Production Base URL: https://api.jetbot.pw
Sandbox Base URL: https://dev.jetbot.pw (для тестов)

1. Подключение и Аутентификация

Для работы с API необходимо выполнить следующие шаги:

  1. Получить Bearer Token: Обратитесь к администратору JetBot для создания учетной записи API и получения токена доступа.
  2. Сгенерировать ключи RSA: Вам потребуется пара ключей RSA (4096 бит) для подписи запросов.
    • Приватный ключ (Private Key) остается у вас и используется для генерации подписи.
    • Публичный ключ (Public Key) необходимо передать администратору для верификации ваших запросов.
  3. Whitelist IP: Предоставьте статический IP-адрес вашего сервера, с которого будут отправляться запросы. Доступ к API разрешен только с доверенных IP.

Важно: Баланс мерчанта в API напрямую связан с балансом вашего Telegram-аккаунта в боте. Для пополнения баланса необходимо произвести стандартную операцию пополнения (депозит) через Telegram-бота: @jetpaycryptobot.

Важно: Для Sandbox (песочницы) используются отдельные учетные данные, токены и URL. Запрашивайте доступ к песочнице отдельно для безопасного тестирования интеграции.

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

Все запросы к API должны содержать HTTP-заголовок авторизации:

Authorization: Bearer YOUR_TOKEN

2. Формирование подписи (Signature)

Методы, изменяющие состояние (например, создание выплаты), требуют обязательного параметра signature для защиты от подделки запросов.

Алгоритм создания подписи RSA-SHA512:

  1. Соберите все параметры тела запроса (JSON или Form-data) в словарь.
  2. Исключите поле signature из этого словаря, если оно там есть.
  3. Отсортируйте параметры по ключам (именам параметров) в алфавитном порядке (A-Z).
  4. Соберите строку для подписи в формате: METHOD_PATH?key1=value1&key2=value2.
    Пример строки: /api/payout?amount=1000&order_id=123&recipient=4444555566667777
    Обратите внимание: значения параметров должны быть такими же, как в отправляемом запросе.
  5. Подпишите полученную строку своим Приватным ключом (Private Key) используя алгоритм хеширования SHA512.
  6. Закодируйте полученную бинарную подпись в строку формата Base64.
  7. Передайте эту строку в параметре signature в теле запроса.

Пример кода на Python:

from cryptography.hazmat.primitives import serialization, hashes
from cryptography.hazmat.primitives.asymmetric import padding
import base64

def sign_request(method_path, data, private_key_path):
    # 1. Сортировка и сборка строки
    sorted_keys = sorted([k for k in data.keys() if k != 'signature'])
    params = [f"{k}={data[k]}" for k in sorted_keys]
    data_string = f"{method_path}?{'&'.join(params)}"
    
    # 2. Загрузка ключа
    with open(private_key_path, "rb") as key_file:
        private_key = serialization.load_pem_private_key(
            key_file.read(), password=None
        )
        
    # 3. Подпись
    signature = private_key.sign(
        data_string.encode(),
        padding.PKCS1v15(),
        hashes.SHA512()
    )
    
    return base64.b64encode(signature).decode()

3. Методы API

GET /api/balance

Получение текущего баланса вашего мерчант-аккаунта в USDT.

Пример ответа:

{
  "balance": 5400.50,
  "currency": "USDT"
}
GET /api/rate

Получение актуального курса USDT/RUB для вашего мерчант-аккаунта. Подпись не требуется.

Пример ответа:

{
  "rate": "71.82"
}

Поле rate — строка с двумя знаками после точки (разделитель — точка), рублей за 1 USDT.

POST /api/payout

Создание новой заявки на выплату средств на банковскую карту (в рублях).

Параметр Тип Обязательно Описание
amount Float/Int Да Сумма выплаты в рублях (RUB). Минимальная и максимальная сумма зависят от текущих лимитов сервиса (обычно 100 - 60000 RUB).
recipient String Да Номер банковской карты получателя (только цифры, без пробелов, 16 знаков).
order_id String Да Уникальный идентификатор заказа в вашей системе. Используется для предотвращения дублей и проверки статуса.
phone String Нет Номер телефона получателя в формате 79xxxxxxxxx (11 цифр). Если не указан, используется заглушка.
name String Нет Имя получателя (латиница или кириллица). Полезно для некоторых банковских шлюзов.
signature String Да RSA-SHA512 подпись запроса (см. раздел "Формирование подписи").

Пример успешного ответа:

{
  "status": "success",
  "id": "provider_abc123",  // ID транзакции в процессинговом шлюзе
  "payout_id": 42          // Внутренний ID выплаты в JetBot
}
POST /api/payout/sbp

Создание новой заявки на выплату через СБП (Систему быстрых платежей) — по номеру телефона и банку получателя, без номера карты. Это отдельный метод; /api/payout и его поведение не меняются.

Особенности СБП-выплат:

Подпись: формируется так же, как для /api/payout, но путь метода — /api/payout/sbp (пример строки: /api/payout/sbp?amount=5000&bank=Сбербанк&name=Иван Иванов&order_id=123&phone=79001234567).

Параметр Тип Обязательно Описание
amount Float/Int Да Сумма выплаты в рублях (RUB). От 100 до 20 000 RUB.
bank String Да Название банка получателя (например, «Сбербанк», «Тинькофф»). 2–50 символов.
name String Да Имя получателя.
phone String Да Номер телефона получателя (российский мобильный, формат 79xxxxxxxxx; ввод с 8 или +7 нормализуется автоматически).
order_id String Да Уникальный идентификатор заказа в вашей системе.
signature String Да RSA-SHA512 подпись запроса (путь метода — /api/payout/sbp).

Пример успешного ответа:

{
  "status": "created",      // СБП-выплата принята и ожидает ручного подтверждения
  "id": "19E3BABE0796332",  // Публичный ID (используется для проверки статуса и чека)
  "order_id": "my_order_001",
  "payout_id": 42           // Внутренний ID выплаты в JetBot
}
GET /api/payout/<ID>

Получение актуального статуса выплаты. В качестве <ID> можно использовать:

Пример ответа:

{
  "id": 42,
  "order_id": "my_order_001",
  "amount": 1500.00,
  "status": "confirmed",     // Возможные статусы: confirmed, pending, failed, cancelled
  "jetbot_status": "success", // Детальный статус шлюза: success, process, error и т.д.
  "payout_type": "card",     // Тип выплаты: "card" (на карту) или "sbp" (СБП)
  "recipient": "4276....1234", // Для СБП — реквизиты в 3 строки: имя, банк, телефон
  "created_at": "2023-10-27 14:30:00"
}
GET /api/payout/<public_id>/receipt

Скачивание PDF-чека по успешной выплате. В качестве <public_id> используется ID с чека (поле id, возвращаемое при создании выплаты). Внутренний номер выплаты (payout_id), order_id и другие идентификаторы для скачивания чека не принимаются. Подпись не требуется.

Ответ — файл в формате PDF (Content-Type: application/pdf). Время на чеке указано по московскому времени (МСК, UTC+3).

Пример запроса (cURL):

curl -H "Authorization: Bearer <TOKEN>" \
     -o receipt.pdf \
     https://api.jetbot.pw/api/payout/358472DC4B20E6A/receipt

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

4. Коды ошибок

Код Описание
400 Bad Request. Ошибка валидации параметров (неверный формат карты, отсутствие обязательных полей и т.д.).
401 Unauthorized. Неверный или отсутствующий Bearer Token.
402 Payment Required. Недостаточно средств на балансе мерчанта для совершения выплаты.
403 Forbidden. Доступ запрещен. Возможные причины: IP-адрес не в белом списке, неверная цифровая подпись (signature).
404 Not Found. Запрашиваемый ресурс (например, выплата по ID) не найден.
500 Internal Server Error. Внутренняя ошибка сервера или ошибка на стороне провайдера выплат.
503 Service Unavailable. Сервис временно недоступен или превышен лимит запросов (Rate Limit).

5. Ограничения (Rate Limits)

Для обеспечения стабильности работы API применяются следующие ограничения: