HornyAPI Documentation

Обзор API

HornyAPI Merchant Service - это унифицированный API для работы с различными провайдерами цифровых товаров и услуг. API предоставляет единый интерфейс для управления заказами, продуктами, платежами и интеграцией с внешними провайдерами.

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

API использует следующие методы аутентификации:

• API Key: Уникальный ключ для аутентификации
• Secret Key: Секретный ключ для подписи запросов
• JWT Token: Токен для авторизации запросов
• Access Key: Ключ доступа, присвоенный пользователю

Заголовки для аутентификации

Все API запросы должны включать следующие заголовки:

Authorization: Bearer <JWT_TOKEN>
X-API-Key: <API_KEY>
X-Access-Key: <ACCESS_KEY>  # Для запросов от мерчантов

Доступные методы API

1. Products List (Список продуктов) - Административный

Endpoint: /api/products/

Method: GET

Описание: Получение полного списка продуктов (только для администраторов)

Параметры запроса

• provider_type - фильтр по типу провайдера
• is_available - фильтр по доступности
• currency - фильтр по валюте
• search - поиск по названию и описанию
• ordering - сортировка (name, price, created_at, updated_at)

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

{
    "count": 100,
    "next": "https://api.hornybox.com/api/products/?page=2",
    "previous": null,
    "results": [
        {
            "id": 1,
            "name": "Game Coins",
            "description": "In-game currency",
            "price": 10.99,
            "currency": "RUB",
            "provider": "unipin",
            "category": {
                "id": 1,
                "name": "Game Currency",
                "slug": "game-currency"
            },
            "is_available": true,
            "provider_product_id": "GAME123"
        }
    ]
}

2. Merchant Products List (Список продуктов для мерчантов)

Endpoint: /api/merchant/products/

Method: GET

Описание: Получение списка продуктов для мерчантов

Параметры запроса

• is_available - фильтр по доступности
• currency - фильтр по валюте (по умолчанию RUB)
• search - поиск по названию и описанию
• ordering - сортировка (name, price, created_at, updated_at)
• category - фильтр по категории

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

{
    "count": 100,
    "next": "https://api.hornybox.com/api/merchant/products/?page=2",
    "previous": null,
    "results": [
        {
            "id": 1,
            "name": "Game Coins",
            "description": "In-game currency",
            "price": 10.99,
            "currency": "RUB",
            "category": {
                "id": 1,
                "name": "Game Currency",
                "slug": "game-currency"
            },
            "is_available": true
        }
    ]
}

3. Order Creation (Создание заказа)

Endpoint: /api/orders/

Method: POST

Описание: Создание нового заказа

Тело запроса

{
    "product_id": 1,
    "quantity": 1,
    "user_id": "user123",
    "server_id": "server1",
    "character_id": "char123",
    "payment_method": "credit_card",
    "callback_url": "https://your-site.com/callback"
}

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

{
    "id": "order_123",
    "status": "pending",
    "product": {
        "id": 1,
        "name": "Game Coins",
        "price": 10.99,
        "currency": "USD"
    },
    "amount": 10.99,
    "currency": "USD",
    "created_at": "2023-01-01T12:00:00Z",
    "payment_url": "https://payment.hornybox.com/order_123"
}

4. Order Status (Статус заказа)

Endpoint: /api/orders/{order_id}/

Method: GET

Описание: Получение текущего статуса заказа

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

{
    "id": "order_123",
    "status": "completed",
    "product": {
        "id": 1,
        "name": "Game Coins"
    },
    "amount": 10.99,
    "currency": "USD",
    "created_at": "2023-01-01T12:00:00Z",
    "completed_at": "2023-01-01T12:30:00Z",
    "provider_order_id": "PROV123",
    "delivery_data": {
        "code": "GAME123456",
        "expires_at": "2023-02-01T12:00:00Z"
    }
}

5. Payment Methods (Методы оплаты)

Endpoint: /api/payment-methods/

Method: GET

Описание: Получение списка доступных методов оплаты

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

{
    "methods": [
        {
            "id": "credit_card",
            "name": "Credit Card",
            "currencies": ["USD", "EUR"],
            "min_amount": 1.00,
            "max_amount": 1000.00,
            "fees": {
                "percentage": 2.5,
                "fixed": 0.30
            }
        },
        {
            "id": "crypto",
            "name": "Cryptocurrency",
            "currencies": ["USD", "EUR", "BTC"],
            "min_amount": 10.00,
            "max_amount": null,
            "fees": {
                "percentage": 1.0,
                "fixed": 0.00
            }
        }
    ]
}

6. Balance Check (Проверка баланса)

Endpoint: /api/balance/

Method: GET

Описание: Получение текущего баланса и истории транзакций

Параметры запроса

• currency - валюта баланса (по умолчанию USD)
• start_date - начало периода для истории
• end_date - конец периода для истории

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

{
    "balance": {
        "amount": 1000.00,
        "currency": "USD",
        "last_updated": "2023-01-01T12:00:00Z"
    },
    "transactions": [
        {
            "id": "txn_123",
            "type": "order",
            "amount": -10.99,
            "currency": "USD",
            "description": "Order #123",
            "created_at": "2023-01-01T11:00:00Z"
        },
        {
            "id": "txn_124",
            "type": "deposit",
            "amount": 1000.00,
            "currency": "USD",
            "description": "Balance top-up",
            "created_at": "2023-01-01T10:00:00Z"
        }
    ]
}

Статусы заказов

API использует следующие статусы заказов:

• pending: Заказ создан, ожидает оплаты
• processing: Заказ в обработке
• completed: Заказ успешно выполнен
• failed: Заказ не выполнен
• refunded: Заказ возвращен
• cancelled: Заказ отменен

Обработка ошибок

API возвращает стандартные HTTP коды статуса:

• 200: Успешный запрос
• 400: Неверный запрос
• 401: Не авторизован
• 403: Доступ запрещен
• 404: Ресурс не найден
• 500: Внутренняя ошибка сервера

Пример ответа с ошибкой:

{
    "error": {
        "code": "invalid_request",
        "message": "Invalid product ID",
        "details": {
            "product_id": "Product with ID 999 does not exist"
        }
    }
}

Вебхуки

Для обработки уведомлений от провайдеров, API поддерживает вебхуки:

1. Настройка вебхука для провайдера
2. Обработка входящих уведомлений
3. Автоматическое обновление статусов заказов

Пример вебхука:

{
    "event": "payment.completed",
    "data": {
        "order_id": "order_123",
        "payment_id": "payment_123",
        "amount": 10.99,
        "currency": "USD",
        "timestamp": "2023-01-01T12:30:00Z"
    }
}

Ограничения API

API имеет следующие ограничения на количество запросов:

• 100 запросов в минуту для обычных эндпоинтов
• 1000 запросов в минуту для вебхуков
• Ограничения могут быть изменены для конкретных клиентов

Безопасность

1. Все запросы должны использовать HTTPS
2. JWT токены имеют ограниченный срок действия
3. API ключи должны храниться в безопасном месте
4. Рекомендуется использовать IP-фильтрацию для важных операций

Рекомендации по использованию

1. Всегда проверяйте статус ответа
2. Используйте обработку ошибок
3. Кэшируйте часто запрашиваемые данные
4. Реализуйте механизм повторных попыток для неудачных запросов
5. Ведите логирование важных операций