Codici e piani dell'API rivenditori

Emetti lotti di codici riscattabili, revocali, riscatta un codice in una chiave e gestisci i tuoi piani tariffari con l'API per rivenditori.

Lotti di codici

Un lotto si crea con POST /code-batches (scope codes; l'header Idempotency-Key è obbligatorio): label, count fino a 200, amount_usd fino a 5000 per codice. Facoltativi: key_expires_days o key_expires_hours (quanto vive la chiave dopo l'attivazione del codice, predefinito 90 giorni), oppure key_expires_never: true (una chiave senza scadenza, il limite vale comunque; non insieme a una durata), e codes_valid_until (fino a quando un codice si può attivare, ISO 8601, nel futuro e al massimo entro 2 anni; dopo, i codici non attivati vengono revocati automaticamente e la riserva viene rilasciata).

curl -s -X POST https://app.oneprovider.dev/partner/v1/code-batches \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: batch-oct-001" \
-H "Content-Type: application/json" \
-d '{"label":"October promo","count":50,"amount_usd":"5.00","key_expires_hours":24,"codes_valid_until":"2026-12-31T23:59:59Z"}'

Un lotto riserva soltanto il suo costo (count x amount_usd) sul saldo da rivenditore: deve rientrare in Disponibile (Free), ma non viene addebitato nulla. Quando un codice viene attivato diventa una chiave il cui limite resta riservato, e i soldi si addebitano man mano che vengono spesi. Revocando i codici non attivati la riserva viene rilasciata. Oggetto lotto: id, label, count, amount_usd, used, revoked, key_expires_hours, key_expires_days, key_expires_never, codes_valid_until, created_at (key_expires_hours e key_expires_days sono entrambi null sia per un lotto senza scadenza delle chiavi sia per uno con i 90 giorni predefiniti: li distingue key_expires_never). GET /code-batches/{id} contiene anche le attivazioni: chi ha attivato quale codice e quando (code_tail, redeemed_at, key_id), dalla più recente, al massimo 1000; la risposta di revoca contiene anche revoked_now e refunded_usd.

# list batches, read one, list its codes
curl -s https://app.oneprovider.dev/partner/v1/code-batches -H "Authorization: Bearer $OP_PARTNER_TOKEN"
curl -s https://app.oneprovider.dev/partner/v1/code-batches/<batch id> -H "Authorization: Bearer $OP_PARTNER_TOKEN"
curl -s "https://app.oneprovider.dev/partner/v1/code-batches/<batch id>/codes?status=active&limit=100" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"
# revoke what is still unredeemed
curl -s -X POST https://app.oneprovider.dev/partner/v1/code-batches/<batch id>/revoke -H "Authorization: Bearer $OP_PARTNER_TOKEN"

Oggetto codice: code, status (active, used, revoked: active/used/revoked), amount_usd, batch_id, redeemed_at, key_id. Stato di un singolo codice: GET /codes/{code}.

Riscattare un codice tramite l'API

Se trasformi tu un codice in una chiave, chiama POST /codes/{code}/redeem (l'header Idempotency-Key è obbligatorio). Il cliente si può passare come customer_id o customer_external_id.

curl -s -X POST https://app.oneprovider.dev/partner/v1/codes/<code>/redeem \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: redeem-<code>" \
-H "Content-Type: application/json" \
-d '{"customer_external_id":"user-77"}'

La risposta 201 contiene la chiave e il suo segreto (una ripetizione della stessa chiamata con la stessa Idempotency-Key restituisce la stessa chiave). Un codice già riscattato in un altro modo dà 409 code_used, uno revocato 409 code_revoked; customer_id insieme a customer_external_id è 400 invalid, un cliente bloccato è 409 customer_blocked.

Piani

Un piano è il tuo prezzo per i clienti: quanti USD riceve la chiave, quanto ti paga il cliente e in quale valuta, per quanto tempo. I piani alimentano POST /orders (il parametro plan_id). Il massimo è 20 piani (409 plan_limit). Per leggere i piani serve lo scope read, per modificarli plans.

curl -s -X POST https://app.oneprovider.dev/partner/v1/plans \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Start 10 USD","balance_usd":"10.00","price":"890.00","currency":"RUB","expires_days":30,"sort":1,"active":true}'
curl -s -X PATCH https://app.oneprovider.dev/partner/v1/plans/<plan id> -H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" -d '{"active":false}'
curl -s -X DELETE https://app.oneprovider.dev/partner/v1/plans/<plan id> -H "Authorization: Bearer $OP_PARTNER_TOKEN"

GET /pricing restituisce i limiti da rispettare: importo minimo e massimo della chiave, durata massima, importo massimo del codice, dimensione del lotto, il numero di piani e di token, il numero di chiavi attive (key_limit) e plan_currencies (le valute dei piani). Un piano si può creare con una Idempotency-Key (facoltativa): una ripetizione restituisce lo stesso piano invece di un secondo. Un PATCH che non menziona la durata la lascia com'era. Eliminare, alzare il prezzo e cambiare valuta sono rifiutati finché sul piano c'è un acquisto aperto nel bot (409 plan_in_use).