Ordini dell'API rivenditori

Costruisci il tuo negozio: il cliente paga te, tu chiami POST /orders e ottieni una chiave. Idempotenza con external_order_id e ricariche di chiavi esistenti.

Il flusso di vendita

1. Il tuo cliente ti paga sul tuo sito con il tuo checkout (OneProvider non fa parte di quel pagamento).
2. Il tuo server riceve la conferma del pagamento e chiama POST /orders.
3. OneProvider riserva il limite della chiave sul tuo saldo da rivenditore (i soldi si addebitano man mano che vengono spesi) e crea un ordine con lo stato completed.
4. Consegni al cliente la chiave dalla risposta e, se vuoi, il dashboard_url.

Un ordine emette una nuova chiave (kind: "new_key") oppure ne ricarica una esistente (kind: "topup" quando si passa key_id).

Creare un ordine

Che cosa consegnare lo decide un piano (plan_id, vedi Codici e piani ) oppure direttamente un importo: limit_usd e expires_days o expires_hours. Il cliente si può passare come customer_id o customer_external_id (un cliente creato in precedenza). I campi charged_amount e charged_currency registrano quanto ti ha pagato il cliente; alimentano GET /stats e non influiscono sull'addebito.

curl -s -X POST https://app.oneprovider.dev/partner/v1/orders \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: shop-1042" \
-H "Content-Type: application/json" \
-d '{
"external_order_id": "shop-1042",
"limit_usd": "10.00",
"expires_days": 30,
"customer_external_id": "user-77",
"name": "anna-main",
"charged_amount": "890.00",
"charged_currency": "RUB"
}'

{
"id": 42,
"external_order_id": "shop-1042",
"status": "completed",
"kind": "new_key",
"key_id": "<key id>",
"amount_usd": "10.00",
"charged_amount": "890.00",
"charged_currency": "RUB",
"created_at": "2026-10-08T12:00:00Z",
"key": {
"id": "<key id>",
"name": "anna-main",
"status": "active",
"limit_usd": "10.00",
"expires_at": "2026-11-07T12:00:00Z",
"dashboard_url": "<dashboard link>",
"key": "sk-..."
}
}

key è l'oggetto chiave (come nella risposta di emissione), il segreto è in key.key. Arriva solo per una nuova chiave, nella risposta di POST /orders (e in una sua ripetizione identica); GET /orders e GET /orders/{id} non lo contengono. Conserva il segreto nella stessa transazione in cui registri l'ordine. Quando l'ordine nasce da un piano senza durata (expires_never), la chiave ha expires_at null.

Idempotenza con external_order_id

external_order_id è il numero dell'ordine nel tuo sistema. Ripetere una richiesta con lo stesso numero e gli stessi parametri non emette una seconda chiave né addebita due volte: ottieni lo stesso ordine e la stessa chiave (con lo stesso segreto, quindi una risposta persa per strada si recupera ripetendo la chiamata). Lo stesso numero con parametri diversi dà 409 external_order_id_conflict. Così si può riprovare in sicurezza dopo un timeout o una connessione caduta. Puoi trovare un ordine con GET /orders?external_order_id=shop-1042.

Ricaricare una chiave esistente

Passa key_id e un importo (limit_usd o un piano):

curl -s -X POST https://app.oneprovider.dev/partner/v1/orders \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: shop-1043" \
-H "Content-Type: application/json" \
-d '{"external_order_id":"shop-1043","key_id":"<key id>","limit_usd":"10.00","charged_amount":"890.00","charged_currency":"RUB"}'

Nella risposta kind è topup e non c'è alcun segreto. L'importo viene aggiunto al limite totale della chiave e, come tutto, deve rientrare in Disponibile (Free): viene riservato e addebitato man mano che si spende.

Esempio di gestore dei pagamenti (Python)

import os
import requests
BASE = "https://app.oneprovider.dev/partner/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["OP_PARTNER_TOKEN"]}
def fulfil_paid_order(order_no: str, user_id: str, plan_id, paid: str, currency: str) -> dict:
"""Call it after YOUR payment provider confirmed the payment (it may be called twice)."""
r = requests.post(
BASE + "/orders",
headers={**HEADERS, "Idempotency-Key": "order-" + order_no},
json={
"external_order_id": order_no,
"plan_id": plan_id,
"customer_external_id": user_id,
"charged_amount": paid,
"charged_currency": currency,
},
timeout=30,
)
if r.status_code == 409 and r.json()["error"]["code"] == "insufficient_balance":
raise RuntimeError("Top up the reseller balance, then retry the same call")
r.raise_for_status()
order = r.json()
# order["key"] (the key object, the secret is order["key"]["key"]) is present on a new_key order, a repeat returns it again
return order

Tieni d'occhio available_usd e iscriviti al webhook balance.low per ricaricare prima che un ordine incontri 409 insufficient_balance. Vedi Webhook .