API de revendedores: cómo funciona

Cómo funciona la plataforma de revendedores: el saldo de revendedor, la reserva, las claves de clientes, los códigos, los planes y todo lo que hace el panel, disponible por una API REST para tu propio sitio o bot.

Cómo funciona

Un revendedor recarga su propio saldo al precio mayorista y vende tokens a sus clientes en forma de claves y códigos. Todo lo que puedes hacer en el panel (la pestaña de revendedor en app.oneprovider.dev) también está disponible por la API, así que puedes crear tu propio sitio, bot o página de pago.

• Saldo de revendedor. Un saldo en USD aparte de tu dinero personal. Lo recargas al precio mayorista; GET /pricing devuelve el precio por 1 USD y el descuento.
• Claves de clientes. Cada clave tiene un límite de gasto en USD y un vencimiento (una clave creada a partir de un plan o de un lote de códigos también puede no tener vencimiento: entonces expires_at es null y el límite sigue vigente). Tu cliente la usa como cualquier clave de OneProvider.
• Códigos. Lotes de códigos de un solo uso que vendes donde quieras. Un código activado se convierte en una clave cuyo límite es igual al importe del código.
• Planes. Tus precios para los clientes: importe de la clave, precio, moneda y vencimiento. Con ellos se emiten claves mediante POST /orders.
• Dashboard neutro por clave. Cada clave tiene un enlace dashboard_url: tu cliente ve su consumo y el saldo restante sin tu marca y sin exponer el secreto de la clave.

La regla del dinero: reserva y descuento

El saldo de revendedor tiene tres cifras:

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

El dinero no se descuenta cuando creas algo, sino cuando el cliente recibe y gasta el valor. Hasta entonces solo está reservado:

• Un lote de códigos solo reserva el importe. Al revocar los códigos sin activar, la reserva se libera.
• Un código activado se convierte en una clave cuyo límite sigue reservado.
• Emitir una clave reserva su límite; lo que se gasta en la clave se descuenta del saldo de revendedor.
• Eliminar una clave o bajar su límite devuelve de inmediato el resto sin gastar a Disponible (Free).
• Pausar una clave mantiene su reserva.

Cada clave nueva, recarga de clave y lote de códigos tiene que caber en Disponible (Free); si no, la respuesta es 409 insufficient_balance. Las tres cifras salen de GET /balance: balance_usd, reserved_usd, available_usd.

Primera solicitud

1. En el panel abre la pestaña de revendedor, «API y ajustes», y crea un token. El valor se muestra una sola vez.
2. Guarda el token en una variable de entorno de tu servidor y llama a /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"
}

El ejemplo muestra solo algunos de los campos de la respuesta; el dinero siempre es una cadena con dos decimales. El conjunto completo está en la referencia de métodos y en la OpenAPI .

Recargar el saldo de revendedor

Los proveedores de pago disponibles y sus mínimos están en topup_providers de GET /balance. Un pago se crea con POST /balance/topups (permiso billing; el encabezado Idempotency-Key es obligatorio). Entregas al pagador el enlace de pago que se devuelve.

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 respuesta contiene order_id y pay_url (201). Estado del pago: GET /balance/topups/{order_id}; el abono también se anuncia con el evento de webhook balance.topped_up.

Registro de auditoría

GET /audit (permiso read) devuelve el registro de cada acción en tu cuenta: desde el panel, con tokens de API y del sistema. Las filas son inmutables (no hay ruta para editar ni eliminar) y nunca contienen secretos: ni claves, ni tokens, ni códigos, ni secretos de webhook. El objeto se muestra de forma resumida: el final de una clave, la etiqueta de un lote o el nombre de un plan.

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 es user (el panel), token, system o bot (el bot de la tienda del revendedor). money (null cuando la acción no tocó dinero) muestra los cambios con signo de la reserva y del descuento; available_after puede ser null. La respuesta también incluye la lista completa de acciones en 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

Convenciones

• Base URL: https://app.oneprovider.dev/partner/v1.
• JSON en todas partes; el dinero es una cadena en USD con dos decimales ("12.50"); las fechas son ISO 8601 UTC (2026-10-08T12:00:00Z).
• Llama a la API solo desde tu servidor: no hay CORS, y el token nunca debe ir en un navegador ni en una app móvil.
• Tokens, permisos, límite de frecuencia, errores, idempotencia y paginación: Autorización y límites .

Siguiente

• Claves y clientes : emitir, recargar, pausar, eliminar.
• Pedidos : cómo crear tu propio sitio.
• Códigos y planes .
• Webhooks : eventos y verificación de la firma.
• Referencia de métodos y openapi.yaml .