API revendeur : fonctionnement

Fonctionnement de la plateforme revendeur : solde revendeur, réserve, clés clients, codes, forfaits et tout ce que fait l’espace client, via une API REST pour votre propre site ou bot.

Comment ça marche

Un revendeur recharge son propre solde au prix de gros et vend des jetons (tokens) à ses clients sous forme de clés et de codes. Tout ce que vous pouvez faire dans l’espace client (l’onglet revendeur sur app.oneprovider.dev) est aussi disponible via l’API : vous pouvez ainsi créer votre propre site, bot ou page de paiement.

• Solde revendeur. Un solde en USD distinct de votre argent personnel. Vous le rechargez au prix de gros ; GET /pricing renvoie le prix pour 1 USD et la remise.
• Clés clients. Chaque clé a une limite de dépense en USD et une date d’expiration (une clé créée à partir d’un forfait ou d’un lot de codes peut aussi n’avoir aucune expiration : expires_at vaut alors null et la limite reste appliquée). Votre client l’utilise comme n’importe quelle clé OneProvider.
• Codes. Des lots de codes à usage unique que vous vendez où vous voulez. Un code activé devient une clé dont la limite est égale au montant du code.
• Forfaits. Vos prix pour les clients : montant de la clé, prix, devise et durée de validité. Les clés sont émises à partir d’eux via POST /orders.
• Dashboard neutre par clé. Chaque clé a un lien dashboard_url : votre client voit sa consommation et le solde restant sans votre marque et sans que le secret de la clé soit exposé.

La règle de l’argent : réserve et débit

Le solde revendeur comporte trois chiffres :

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

L’argent n’est pas débité quand vous créez quelque chose, mais quand le client reçoit et dépense la valeur. D’ici là, il est seulement réservé :

• Un lot de codes ne fait que réserver le montant. La révocation des codes non activés libère la réserve.
• Un code activé devient une clé dont la limite reste réservée.
• Émettre une clé réserve sa limite ; ce qui est dépensé sur la clé est débité du solde revendeur.
• Supprimer une clé ou abaisser sa limite remet aussitôt le reste non dépensé dans Disponible (Free).
• Mettre une clé en pause conserve sa réserve.

Chaque nouvelle clé, recharge de clé et lot de codes doit tenir dans Disponible (Free) ; sinon la réponse est 409 insufficient_balance. Les trois chiffres viennent de GET /balance : balance_usd, reserved_usd, available_usd.

Première requête

1. Dans l’espace client, ouvrez l’onglet revendeur, « API et paramètres », et créez un jeton. La valeur n’est affichée qu’une seule fois.
2. Placez le jeton dans une variable d’environnement sur votre serveur et appelez /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’exemple n’affiche qu’une partie des champs de la réponse ; l’argent est toujours une chaîne avec deux décimales. L’ensemble complet figure dans la référence des méthodes et dans l’OpenAPI .

Recharger le solde revendeur

Les prestataires de paiement disponibles et leurs minimums se trouvent dans topup_providers de GET /balance. Un paiement se crée avec POST /balance/topups (autorisation billing ; l’en-tête Idempotency-Key est obligatoire). Vous transmettez au payeur le lien de paiement renvoyé.

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 réponse contient order_id et pay_url (201). Statut du paiement : GET /balance/topups/{order_id} ; le crédit est aussi signalé par l’événement webhook balance.topped_up.

Journal d’audit

GET /audit (autorisation read) renvoie le journal de chaque action sur votre compte : depuis l’espace client, par les jetons API et par le système. Les lignes sont immuables (aucune route de modification ni de suppression) et ne contiennent jamais de secrets : ni clés, ni jetons, ni codes, ni secrets de webhook. L’objet est présenté de façon abrégée : la fin d’une clé, le libellé d’un lot ou le nom d’un forfait.

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 vaut user (l’espace client), token, system ou bot (le bot de vente du revendeur). money (null si l’action n’a pas touché à l’argent) indique les variations signées de la réserve et du débit ; available_after peut être null. La réponse contient aussi la liste complète des actions dans 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

Conventions

• Base URL : https://app.oneprovider.dev/partner/v1.
• JSON partout ; l’argent est une chaîne en USD avec deux décimales ("12.50") ; les dates sont en ISO 8601 UTC (2026-10-08T12:00:00Z).
• Appelez l’API uniquement depuis votre serveur : il n’y a pas de CORS, et le jeton ne doit jamais se retrouver dans un navigateur ni dans une application mobile.
• Jetons, autorisations, limite de débit, erreurs, idempotence et pagination : Autorisation et limites .

Suite

• Clés et clients  : émettre, recharger, mettre en pause, supprimer.
• Commandes  : comment créer votre propre site.
• Codes et forfaits .
• Webhooks  : événements et vérification de la signature.
• Référence des méthodes et openapi.yaml .