Codes et formules de l’API revendeur
Émettez des lots de codes activables, révoquez-les, activez un code en clé et gérez vos formules tarifaires via l’API revendeur OneProvider. Exemples.
Émettez des lots de codes activables, révoquez-les, transformez un code en clé et gérez vos forfaits tarifaires via l’API revendeur.
Tous les modèles, leurs capacités et leurs tarifs Index de la documentation pour les agents IA :https://oneprovider.dev/docs/llms.txt Lots de codes
Un lot se crée avec POST /code-batches (autorisation codes ; l’en-tête Idempotency-Key est obligatoire) : label, count jusqu’à 200, amount_usd jusqu’à 5000 par code. Facultatifs : key_expires_days ou key_expires_hours (durée de vie de la clé après l’activation du code, 90 jours par défaut), ou key_expires_never: true (une clé sans expiration, la limite reste appliquée ; pas avec une durée de vie), et codes_valid_until (jusqu’à quand un code peut être activé, ISO 8601, dans le futur et au plus 2 ans à l’avance ; ensuite les codes non activés sont révoqués automatiquement et la réserve est libérée).
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 lot ne fait que réserver son coût (count x amount_usd) sur le solde revendeur : il doit tenir dans Disponible (Free), mais rien n’est débité. Quand un code est activé, il devient une clé dont la limite reste réservée, et l’argent est débité à mesure qu’il est dépensé. La révocation des codes non activés libère la réserve. Objet lot : id, label, count, amount_usd, used, revoked, key_expires_hours, key_expires_days, key_expires_never, codes_valid_until, created_at (key_expires_hours et key_expires_days valent null aussi bien pour un lot sans expiration de clé que pour un lot avec la valeur par défaut de 90 jours : key_expires_never permet de les distinguer). GET /code-batches/{id} contient aussi activations : qui a activé quel code et quand (code_tail, redeemed_at, key_id), du plus récent au plus ancien, au plus 1000 ; la réponse de révocation contient aussi revoked_now et 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"Objet code : code, status (active, used, revoked : active/used/revoked), amount_usd, batch_id, redeemed_at, key_id. Statut d’un code : GET /codes/{code}.
Activer un code via l’API
Si vous transformez vous-même un code en clé, appelez POST /codes/{code}/redeem (l’en-tête Idempotency-Key est obligatoire). Le client peut être transmis sous la forme customer_id ou 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 réponse 201 contient la clé et son secret (une répétition du même appel avec la même Idempotency-Key renvoie la même clé). Un code déjà activé d’une autre manière donne 409 code_used, un code révoqué 409 code_revoked ; customer_id avec customer_external_id donne 400 invalid, un client bloqué donne 409 customer_blocked.
Forfaits
Un forfait est votre prix pour les clients : combien d’USD reçoit la clé, combien le client vous paie et dans quelle devise, pour quelle durée. Les forfaits alimentent POST /orders (le paramètre plan_id). Le maximum est de 20 forfaits (409 plan_limit). Lire les forfaits demande l’autorisation read, les modifier demande plans.
| Champ | Description |
|---|---|
name | Nom, jusqu’à 40 caractères. |
balance_usd | Le montant que reçoit la clé. |
price, currency | Votre prix pour le client et sa devise : USD, RUB, XTR ou USDT. |
expires_days / expires_hours | Durée de vie de la clé : de 1 à 365 jours ou de 1 à 8760 heures (l’un des deux ; 30 jours par défaut). La réponse contient expires_hours (la source de vérité) ; expires_days vaut null quand la durée n’est pas un nombre entier de jours. |
expires_never | true : les clés du forfait n’expirent jamais (la limite du solde reste appliquée). Pas avec expires_days ni expires_hours (400 invalid). La réponse a alors expires_hours et expires_days à null. |
sort, active | Ordre d’affichage et indicateur d’activité. |
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 renvoie les limites à respecter : montant minimal et maximal de la clé, durée de vie maximale, montant maximal d’un code, taille du lot, nombre de forfaits et de jetons, nombre de clés actives (key_limit), et plan_currencies (les devises des forfaits). Un forfait peut être créé avec une Idempotency-Key (facultative) : une répétition renvoie le même forfait au lieu d’un second. Un PATCH qui ne mentionne pas la durée de vie la laisse inchangée. La suppression, la hausse du prix et le changement de devise sont refusés tant qu’un achat via le bot est ouvert sur le forfait (409 plan_in_use).