API per rivenditori: come funziona

Come funziona la piattaforma per rivenditori: il saldo da rivenditore, la riserva, le chiavi dei clienti, i codici, i piani e tutto ciò che l'area personale fa tramite un'API REST per il tuo sito o bot.

Come funziona

Un rivenditore ricarica il proprio saldo al prezzo all'ingrosso e vende token ai suoi clienti sotto forma di chiavi e codici. Tutto ciò che puoi fare nell'area personale (la scheda Rivenditore su app.oneprovider.dev) è disponibile anche tramite l'API, così puoi costruire il tuo sito, bot o checkout.

• Saldo da rivenditore. Un saldo in USD separato dai tuoi soldi personali. Lo ricarichi al prezzo all'ingrosso; GET /pricing restituisce il prezzo per 1 USD e lo sconto.
• Chiavi dei clienti. Ogni chiave ha un limite di spesa in USD e una scadenza (una chiave creata da un piano o da un lotto di codici può anche non avere scadenza: allora expires_at è null e il limite vale comunque). Il tuo cliente la usa come qualsiasi chiave OneProvider.
• Codici. Lotti di codici monouso che vendi dove vuoi. Un codice attivato diventa una chiave il cui limite è pari all'importo del codice.
• Piani. I tuoi prezzi per i clienti: importo della chiave, prezzo, valuta e scadenza. Le chiavi vengono emesse da qui tramite POST /orders.
• Dashboard neutra per chiave. Ogni chiave ha un link dashboard_url: il tuo cliente vede consumo e saldo residuo senza il tuo brand e senza che il segreto della chiave venga esposto.

La regola dei soldi: riserva e addebito

Il saldo da rivenditore ha tre numeri (nel blocco qui sotto «Free» è «Disponibile» nell'area personale):

Reseller balance (balance_usd) = your money on the platform
Reserved (reserved_usd) = unredeemed codes + remaining limits of live keys
Free (available_usd) = Reseller balance - Reserved

I soldi non vengono addebitati quando crei qualcosa, ma quando il cliente riceve e spende il valore. Fino ad allora sono solo riservati:

• Un lotto di codici riserva soltanto l'importo. Revocando i codici non attivati la riserva viene rilasciata.
• Un codice attivato diventa una chiave il cui limite resta riservato.
• Emettere una chiave ne riserva il limite; la spesa sulla chiave si addebita sul saldo da rivenditore.
• Eliminare una chiave o abbassarne il limite restituisce subito il residuo non speso a Disponibile (Free).
• Mettere in pausa una chiave ne mantiene la riserva.

Ogni nuova chiave, ricarica di chiave e lotto di codici deve rientrare in Disponibile; altrimenti la risposta è 409 insufficient_balance. Tutti e tre i numeri arrivano da GET /balance: balance_usd, reserved_usd, available_usd.

Prima richiesta

1. Nell'area personale apri la scheda Rivenditore, «API e impostazioni», e crea un token. Il valore viene mostrato una sola volta.
2. Metti il token in una variabile d'ambiente sul tuo server e chiama /balance:

export OP_PARTNER_TOKEN="rsk_..."
curl -s https://app.oneprovider.dev/partner/v1/balance \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

{
"balance_usd": "120.00",
"reserved_usd": "35.50",
"available_usd": "84.50"
}

L'esempio mostra solo alcuni dei campi della risposta; i soldi sono sempre una stringa con due decimali. L'elenco completo è nel riferimento dei metodi e nell'OpenAPI .

Ricaricare il saldo da rivenditore

I provider di pagamento disponibili e i loro minimi sono in topup_providers di GET /balance. Un pagamento si crea con POST /balance/topups (scope billing; l'header Idempotency-Key è obbligatorio). Il link di pagamento restituito lo consegni a chi paga.

curl -s -X POST https://app.oneprovider.dev/partner/v1/balance/topups \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: topup-2026-10-08-001" \
-H "Content-Type: application/json" \
-d '{"balance_usd":"100.00","provider":"<id from topup_providers>"}'

La risposta contiene order_id e pay_url (201). Stato del pagamento: GET /balance/topups/{order_id}; l'accredito viene annunciato anche dall'evento webhook balance.topped_up.

Registro di audit

GET /audit (scope read) restituisce il registro di ogni azione sul tuo account: dall'area personale, con i token API e dal sistema. Le righe sono immutabili (non esiste una route per modificarle o eliminarle) e non contengono mai segreti: né chiavi, né token, né codici, né segreti dei webhook. L'oggetto è mostrato in breve: la parte finale di una chiave, l'etichetta di un lotto o il nome di un piano.

curl -s "https://app.oneprovider.dev/partner/v1/audit?period=7d&action=key.&limit=50" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

{
"items": [
{
"id": "<row id>",
"at": "2026-10-08T12:00:00Z",
"actor": { "kind": "token", "label": "shop backend" },
"action": "key.created",
"object": { "type": "key", "label": "anna-main (...4f2a)" },
"money": { "reserve_delta": "25.00", "debit_delta": "0.00", "available_after": "59.50" },
"ip": "203.0.113.7",
"request_id": "req_..."
}
],
"next": null,
"actions": ["key.created", "key.topped_up"]
}

actor.kind è user (l'area personale), token, system oppure bot (il bot di vendita del rivenditore). money (null quando l'azione non ha toccato i soldi) mostra le variazioni con segno della riserva e dell'addebito; available_after può essere null. La risposta contiene anche l'elenco completo delle azioni in actions:

key.created key.topped_up key.limit_changed key.updated key.paused key.resumed key.exhausted key.rotated key.extended key.expiry_changed key.deleted
code_batch.created code_batch.revoked code_batch.expired code.redeemed
plan.created plan.updated plan.deleted
token.created token.revoked
webhook.created webhook.deleted webhook.tested webhook.retried
balance.topup order.completed
customer.created customer.updated customer.blocked customer.unblocked
settings.updated account.activated

Convenzioni

• Base URL: https://app.oneprovider.dev/partner/v1.
• JSON ovunque; i soldi sono una stringa in USD con due decimali ("12.50"); gli orari sono ISO 8601 UTC (2026-10-08T12:00:00Z).
• Chiama l'API solo dal tuo server: non c'è CORS e il token non deve mai finire in un browser o in un'app mobile.
• Token, scope, rate limit, errori, idempotenza e paginazione: Autorizzazione e limiti .

Avanti

• Chiavi e clienti : emettere, ricaricare, mettere in pausa, eliminare.
• Ordini : come costruire il tuo sito.
• Codici e piani .
• Webhook : eventi e verifica della firma.
• Riferimento dei metodi e openapi.yaml .