Autenticazione e limiti dell'API rivenditori

Token Bearer, scope, allowlist IP, rate limit, codici di errore, chiavi di idempotenza e paginazione dell'API per rivenditori.

Token

Un token ha la forma rsk_ seguito da 40 caratteri. Lo crei nell'area personale (scheda Rivenditore, «API e impostazioni»); il valore viene mostrato una sola volta, noi conserviamo solo un hash e gli ultimi 4 caratteri. Puoi avere fino a 10 token attivi e revocarli in qualsiasi momento. Alla creazione puoi dare al token una durata (da 1 a 365 giorni): trascorsa, il token risponde 401 token_expired, e expires_at in GET /me indica quando succede (null: nessuna scadenza).

Authorization: Bearer rsk_...

Scope

Un token porta con sé un insieme di scope. Gli scope sono indipendenti: keys non implica read. GET /me funziona con qualsiasi token valido. Senza lo scope richiesto la risposta è 403 forbidden_scope.

Lo scope di ogni metodo è indicato nel riferimento .

Allowlist IP

Un token può essere limitato a un elenco di indirizzi IPv4/IPv6 o di intervalli CIDR (fino a 20). Una richiesta da un altro indirizzo riceve 403 ip_not_allowed. L'elenco si imposta alla creazione del token.

Rate limit

20 richieste al secondo per token e 100 al secondo per indirizzo IP di origine. Se superato: 429 rate_limited e un header Retry-After. Aspetta quel numero di secondi e riprova.

Errori

Ogni errore ha la stessa forma. Lo stesso id viene inviato nell'header X-Request-Id: comunicalo all'assistenza.

{
"error": {
"code": "insufficient_balance",
"message": "Not enough free reseller balance for this key.",
"request_id": "req_..."
}
}

Gestisci i casi in base a error.code, non al testo del messaggio.

Idempotenza

I metodi che spendono soldi richiedono l'header Idempotency-Key (da 1 a 128 caratteri stampabili); senza (o con uno non valido) la risposta è 400 idempotency_key_required. Sono segnati nel riferimento. Ripetere una richiesta con la stessa chiave e lo stesso corpo (per rivenditore) non spende mai due volte e restituisce lo stesso oggetto, compreso il segreto della chiave creata da quella chiamata: una risposta persa per strada si recupera ripetendo la chiamata. La stessa chiave con un corpo diverso dà 409 idempotency_key_reused. Usa una chiave nuova per ogni nuovo pagamento od ordine; per POST /orders l'identità è external_order_id. L'header è facoltativo (e rispettato se inviato) su PATCH /keys/{id} (un extend_days/extend_hours ripetuto prolunga una volta sola), POST /plans e POST /webhooks (una ripetizione restituisce lo stesso oggetto; il segreto di un webhook non viene mostrato di nuovo).

curl -s -X POST https://app.oneprovider.dev/partner/v1/keys \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"client-1","limit_usd":"10.00"}'

Conserva la chiave di idempotenza insieme al record del tuo ordine, così dopo un errore di rete riprovi esattamente la stessa richiesta.

Paginazione

Gli endpoint di elenco accettano ?limit=1..100 (predefinito 50) e &cursor=. La risposta è {"items": [...], "next": "<cursor>"}; next è null nell'ultima pagina. Il cursore è opaco: restituiscilo così com'è.

curl -s "https://app.oneprovider.dev/partner/v1/keys?limit=100&cursor=<next from the previous page>" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

Sandbox

I token di test rsk_test_... arriveranno presto. Per ora un token così riceve 501 sandbox_not_implemented.