# Proxy Soxy Partner API — server examples

RU: бот Proxy Soxy → **Управление прокси → Помощь → API-ключ → Выпустить ключ**.
Для расходов: **Разрешить расходы API…**, подтвердить разрешение. Секрет показывается один раз;
перевыпуск отзывает старый ключ и требует нового разрешения расходов. Пополняется баланс Proxy Soxy.

EN: Proxy Soxy bot → **My proxies → Help → API key → Issue a key**.
Select **«Разрешить расходы API…»** in the RU bot and confirm. A reissued key needs new consent.
For purchases use the RU bot and its account key; the EN bot has no spending-permission button. The RU bot uses Russian spending-button labels.
Current spending requires **RU/RUB**. English documentation does not enable USD payments.
No public virtual-money sandbox or self-service test key is offered.

Base URL: `https://api.soxydata.com/v1`. Store the key only on your server. Never log credentials.
`example.mjs` and `example.py` execute **GET only**; optional functions are not called automatically.
Set `STATIC_API_KEY` securely. Python 3.8+ / Node.js 18+; no dependencies. `client.d.mts` supplies TypeScript types.
Use your own HTTP mocks for tests; do not run the Postman collection wholesale against production.

## Price and purchase / Цена и покупка

`catalog()` → `balance()` → `quote(selection)` → show the price → durably save
`quote_id` + idempotency key → `confirm(quote_id, idem)` → `operation(id)` → `proxies(customer_ref)`.
Only `COMPLETED` confirms complete fulfilment. All amounts are minor units; 1500 = RUB 15.00.
A quote lasts 120 seconds. Price/selection drift is refused, not silently charged at a new price.

Proxy + UDP selection:
```json
{"kind":"purchase","country":"US","count":2,"days":30,"customer_ref":"buyer-42","udp":true}
```
Separate UDP selection:
```json
{"kind":"udp","customer_ref":"buyer-42","proxy_ids":["bott-example001"],"udp_mode":"connect"}
```
Use `order_id` of the original completed purchase instead of `proxy_ids`, never both.
`udp_mode=extend` covers an unpaid gap after a separate main proxy renewal; no implicit main-term extension.
The quote returns proxy/UDP/total minor amounts and per-access UDP dates. Read `proxies[].udp` for current entitlement.

`customer_ref` is scoped to your payer account, **not** a Telegram ID. Use the same reference for reads and add-ons.
For purchases for yourself, omit it. Credentials belong only to the selected authorized customer.

## Recovery / Восстановление

Persist the intent before confirm. If a response is lost, retry the **same quote and key**;
if operation_id is known, read it and explicitly `reconcile(id)` when needed. No SDK write is retried automatically.
DEBIT_UNKNOWN / PAID_HELD / APPLYING / MANUAL_REVIEW are not a new-purchase instruction.
Notification errors do not roll back a purchase. `notifications(id)` reads delivery state;
`retryNotification(id)` / `retry_notification(id)` only retries eligible rejected payer delivery, not UNKNOWN.
No duplicate debit or fulfilment is requested by these notification methods.

Webhook signatures use HMAC-SHA256 over `<t>.<raw body>`. Persist event_id for deduplication.
The legacy literal `wallet: "BOT-T"` is retained in the external response for compatibility: it means the Proxy Soxy balance.
It is not a separate wallet or a requirement to register elsewhere.

[RU documentation](https://api.soxydata.com/ru/) · [English](https://api.soxydata.com/en/) · [OpenAPI](https://api.soxydata.com/openapi.yaml).
