Commandes de l’API revendeur

Créez votre propre boutique : le client vous paie, vous appelez POST /orders et obtenez une clé. Idempotence par external_order_id et recharges de clés existantes.

Le parcours de vente

1. Votre client vous paie sur votre site via votre propre page de paiement (OneProvider ne participe pas à ce paiement).
2. Votre serveur reçoit la confirmation du paiement et appelle POST /orders.
3. OneProvider réserve la limite de la clé sur votre solde revendeur (l’argent est débité à mesure qu’il est dépensé) et crée une commande au statut completed.
4. Vous remettez au client la clé de la réponse et, si vous le souhaitez, le dashboard_url.

Une commande sert soit à émettre une nouvelle clé (kind: "new_key"), soit à recharger une clé existante (kind: "topup" quand key_id est transmis).

Créer une commande

Ce qu’il faut livrer est défini par un forfait (plan_id, voir Codes et forfaits ) ou directement par un montant : limit_usd et expires_days ou expires_hours. Le client peut être transmis sous la forme customer_id ou customer_external_id (un client créé auparavant). Les champs charged_amount et charged_currency enregistrent ce que le client vous a payé ; ils alimentent GET /stats et n’influent pas sur le débit.

curl -s -X POST https://app.oneprovider.dev/partner/v1/orders \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: shop-1042" \
-H "Content-Type: application/json" \
-d '{
"external_order_id": "shop-1042",
"limit_usd": "10.00",
"expires_days": 30,
"customer_external_id": "user-77",
"name": "anna-main",
"charged_amount": "890.00",
"charged_currency": "RUB"
}'

{
"id": 42,
"external_order_id": "shop-1042",
"status": "completed",
"kind": "new_key",
"key_id": "<key id>",
"amount_usd": "10.00",
"charged_amount": "890.00",
"charged_currency": "RUB",
"created_at": "2026-10-08T12:00:00Z",
"key": {
"id": "<key id>",
"name": "anna-main",
"status": "active",
"limit_usd": "10.00",
"expires_at": "2026-11-07T12:00:00Z",
"dashboard_url": "<dashboard link>",
"key": "sk-..."
}
}

key est l’objet clé (comme dans la réponse d’émission), le secret se trouve dans key.key. Il n’arrive que pour une nouvelle clé, dans la réponse de POST /orders (et dans une répétition exacte de celle-ci) ; GET /orders et GET /orders/{id} ne le contiennent pas. Conservez le secret dans la même transaction que celle où vous enregistrez la commande. Quand la commande provient d’un forfait sans durée (expires_never), la clé a expires_at à null.

Idempotence par external_order_id

external_order_id est le numéro de commande dans votre système. Répéter une requête avec le même numéro et les mêmes paramètres n’émet pas de seconde clé et ne débite pas deux fois : vous récupérez la même commande et la même clé (avec le même secret, ce qui permet de récupérer une réponse perdue en route en répétant l’appel). Le même numéro avec des paramètres différents donne 409 external_order_id_conflict. On peut donc réessayer sans risque après un délai dépassé ou une connexion coupée. Vous pouvez retrouver une commande avec GET /orders?external_order_id=shop-1042.

Recharger une clé existante

Transmettez key_id et un montant (limit_usd ou un forfait) :

curl -s -X POST https://app.oneprovider.dev/partner/v1/orders \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: shop-1043" \
-H "Content-Type: application/json" \
-d '{"external_order_id":"shop-1043","key_id":"<key id>","limit_usd":"10.00","charged_amount":"890.00","charged_currency":"RUB"}'

Dans la réponse, kind vaut topup et il n’y a pas de secret. Le montant s’ajoute à la limite totale de la clé et, comme tout, doit tenir dans Disponible (Free) : il est réservé, puis débité à mesure qu’il est dépensé.

Exemple de gestionnaire de paiement (Python)

import os
import requests
BASE = "https://app.oneprovider.dev/partner/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["OP_PARTNER_TOKEN"]}
def fulfil_paid_order(order_no: str, user_id: str, plan_id, paid: str, currency: str) -> dict:
"""Call it after YOUR payment provider confirmed the payment (it may be called twice)."""
r = requests.post(
BASE + "/orders",
headers={**HEADERS, "Idempotency-Key": "order-" + order_no},
json={
"external_order_id": order_no,
"plan_id": plan_id,
"customer_external_id": user_id,
"charged_amount": paid,
"charged_currency": currency,
},
timeout=30,
)
if r.status_code == 409 and r.json()["error"]["code"] == "insufficient_balance":
raise RuntimeError("Top up the reseller balance, then retry the same call")
r.raise_for_status()
order = r.json()
# order["key"] (the key object, the secret is order["key"]["key"]) is present on a new_key order, a repeat returns it again
return order

Surveillez available_usd et abonnez-vous au webhook balance.low pour recharger avant qu’une commande ne se heurte à 409 insufficient_balance. Voir Webhooks .