API v1 — FBMarket

1. Получение API-ключа

Ключ выдаётся только админом — нет self-signup. Напишите в Telegram поддержку с темой "API ключ" + укажите ваш email/проект. Лимит: 60 запросов в минуту на ключ (rate-limit, при превышении HTTP 429).

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

X-API-Key: YOUR_KEY_HERE

Каждый запрос требует header. Без ключа или с invalid — HTTP 401 Unauthorized.

3. Каталог (READ-ONLY)

GET /v1/health

Проверка ключа + uptime probe.

curl -H "X-API-Key: $KEY" https://fbmarket.pro/api/v1/health
# {"status":"ok","timestamp":1779497200}

GET /v1/products

Каталог с фильтрами. Query params:

• category (string) — фильтр по категории (см. /v1/categories)
• source_site (string) — фильтр по конкретному источнику
• min_price / max_price (float, USDT)
• min_qty (int, default 1) — минимальное количество в наличии
• page (int, default 1)
• page_size (int, default 50, max 200) — товаров на страницу

curl -H "X-API-Key: $KEY"   "https://fbmarket.pro/api/v1/products?category=aged&min_price=1&page=1&page_size=50"

# {"total": 1179, "page": 1, "page_size": 50, "items": [
#   {"id": 12345, "title": "...", "category": "aged",
#    "price_usdt": 1.234, "quantity": 5, "source_site": "<source-domain>",
#    "is_available": true, "has_real_device": false, "tags": [...]}
# ]}

GET /v1/products/{id}

Детали одного товара по ID.

GET /v1/categories

Список категорий с количеством товаров + минимальной ценой.

4. Баланс и пополнение

GET /v1/balance

Текущий баланс ключа + сумма потрачено/пополнено.

curl -H "X-API-Key: $KEY" https://fbmarket.pro/api/v1/balance
# {"balance_usdt": 50.0, "total_spent_usdt": 12.5,
#  "total_topup_usdt": 62.5, "currency": "USDT"}

POST /v1/balance/topup

Создать топап-intent → получить USDT адрес для перевода. Body:

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json"   -d '{"amount_usdt": 100, "network": "usdt_trc_20"}'   https://fbmarket.pro/api/v1/balance/topup

# {"topup_id": "abc123...", "payment_address": "TYz...",
#  "payment_network": "usdt_trc_20", "amount_usdt": 100.0,
#  "expires_at": 1779500800}

Сети: usdt_trc_20 (Tron), usdt_bep_20 (BSC), usdt_polygon, usdt_arbitrum, usdt_ton, usdt_solana.

После перевода USDT на адрес — баланс кредитуется. Phase 2: auto-credit per chain; MVP: admin верифицирует TX вручную через /api_credit bot command, обычно 1-15 минут.

5. Заказы (balance-debit)

POST /v1/orders

Создать заказ + auto-debit balance + обработка системой.

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json"   -d '{"product_id": 12345, "quantity": 10,
       "payment_method": "balance",
       "webhook_url": "https://your.app/api/facebook-webhook"}'   https://fbmarket.pro/api/v1/orders

# {"order_id": 789, "status": "paid", "price_usdt": 12.34,
#  "quantity": 10}

Если баланс < price → HTTP 402 Payment Required + сообщение с инструкцией topup. payment_method="usdt_trc_20" и др. — HTTP 501 (invoice mode пока не реализован, используйте balance).

GET /v1/orders/{id}

Статус заказа + items[] с credentials когда completed. Доступен только владельцу ключа (key-scoped, 404 если чужой).

curl -H "X-API-Key: $KEY" https://fbmarket.pro/api/v1/orders/789

# {"order_id": 789, "status": "completed",
#  "price_usdt": 12.34, "quantity": 10,
#  "items": [
#    {"login": "...", "password": "...", "cookies": "...", ...},
#    ...
#  ]}

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

В POST /v1/orders передайте webhook_url — мы POST'нем JSON туда при изменении статуса (completed/partial/failed/refunded).

POST $YOUR_WEBHOOK_URL
Content-Type: application/json

{
  "order_id": 789,
  "status": "completed",
  "price_usdt": 12.34,
  "quantity": 10,
  "product_id": 12345,
  "items": [{"login": "...", "password": "...", ...}],
  "error_message": null,
  "fired_at": 1779497200
}

Сервис ожидает HTTP 2xx ответ. На 5xx/timeout — retry до 5 раз с exp-backoff. После 5 неудач webhook помечается как fired (не повторяется).

7. Метрики usage

GET /v1/usage

Per-key статистика: запросы, последняя активность, потрачено.

curl -H "X-API-Key: $KEY" https://fbmarket.pro/api/v1/usage
# {"request_count": 1234, "last_used_at": 1779497200,
#  "first_used_at": 1779480000,
#  "last_endpoint": "/api/v1/products",
#  "total_spent_usdt": 125.50}

8. Доставка аккаунтов

Срок выдачи: 30 секунд — 10 минут после status=paid. Заказ обрабатывается асинхронно — используйте polling GET /v1/orders/{id} или зарегистрируйте webhook_url для уведомления.

1. POST /v1/orders → дебит баланса → status=paid
2. Заказ обрабатывается (30s-10min)
3. Когда готово → status=completed
4. GET /v1/orders/{id} вернёт items[] (login/password/cookies/etc)
5. Webhook fired (если зарегистрирован)

9. Сети USDT и комиссии

10. Лимиты и тарифы

• Rate-limit: 60 запросов в минуту на ключ (HTTP 429 + header Retry-After при превышении)
• Цена через API = такая же как на сайте (без наценки)
• page_size: 1-200 товаров на страницу (по умолчанию 50)
• quantity в заказе: 1-10000 единиц (1 product_id за раз)
• min_qty фильтр: исключает товары где quantity < указанного (default 1)
• min_price / max_price: float в USDT, можно один или оба
• page: pagination, начинается с 1
• Топап: amount_usdt от 1 до 100000, network 6 вариантов
• Webhook timeout: 10s на запрос, до 5 retry с exp-backoff
• Order ownership: GET /v1/orders/{id} только для key который создал заказ (иначе 404)

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

• 401 — invalid X-API-Key
• 402 — insufficient balance (для POST /orders)
• 404 — product/order не найден (или не ваш для orders)
• 409 — insufficient stock (запрашиваемое quantity больше доступного)
• 422 — invalid request body
• 429 — rate-limit (60/min)
• 501 — invoice mode не реализован (используйте balance)
• 503 — Redis down (rate-limit/balance недоступны)

12. Поддержка

Вопросы по API: Telegram поддержка. SLA на ответ: 30 минут в рабочее время (8:00-22:00 МСК), до 4 часов ночью.

Status и uptime API: можно вызвать GET /v1/health в любое время без оплаты.