Pedidos de la API de revendedores

Crea tu propia tienda: el cliente te paga, tú llamas a POST /orders y obtienes una clave. Idempotencia por external_order_id y recargas de claves existentes.

El flujo de ventas

1. Tu cliente te paga en tu sitio con tu propia página de pago (OneProvider no participa en ese pago).
2. Tu servidor recibe la confirmación del pago y llama a POST /orders.
3. OneProvider reserva el límite de la clave en tu saldo de revendedor (el dinero se descuenta a medida que se gasta) y crea un pedido con el estado completed.
4. Entregas al cliente la clave de la respuesta y, si quieres, el dashboard_url.

Un pedido emite una clave nueva (kind: "new_key") o recarga una existente (kind: "topup" cuando se pasa key_id).

Crear un pedido

Lo que se entrega lo define un plan (plan_id, consulta Códigos y planes ) o directamente un importe: limit_usd y expires_days o expires_hours. El cliente se puede pasar como customer_id o customer_external_id (un cliente creado antes). Los campos charged_amount y charged_currency registran lo que el cliente te pagó; alimentan GET /stats y no afectan al cobro.

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 es el objeto clave (como en la respuesta de emisión), el secreto está en key.key. Solo llega para una clave nueva, en la respuesta de POST /orders (y en una repetición exacta de ella); GET /orders y GET /orders/{id} no lo incluyen. Guarda el secreto en la misma transacción en la que registras el pedido. Cuando el pedido se hace con un plan sin plazo (expires_never), la clave tiene expires_at null.

Idempotencia por external_order_id

external_order_id es el número del pedido en tu sistema. Repetir una solicitud con el mismo número y los mismos parámetros no emite una segunda clave ni cobra dos veces: recibes el mismo pedido y la misma clave (con el mismo secreto, así que una respuesta perdida por el camino se recupera repitiendo la llamada). El mismo número con parámetros distintos da 409 external_order_id_conflict. Así puedes reintentar con seguridad tras un tiempo de espera agotado o una conexión caída. Puedes encontrar un pedido con GET /orders?external_order_id=shop-1042.

Recargar una clave existente

Pasa key_id y un importe (limit_usd o un plan):

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"}'

En la respuesta, kind es topup y no hay secreto. El importe se suma al límite total de la clave y, como todo, tiene que caber en Disponible (Free); se reserva y se descuenta a medida que se gasta.

Ejemplo de manejador de pagos (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

Vigila available_usd y suscríbete al webhook balance.low para recargar antes de que un pedido reciba 409 insufficient_balance. Consulta Webhooks .