Códigos y planes de la API de revendedores
Emite lotes de códigos canjeables, revócalos, canjea un código por una clave y gestiona tus planes con la API de revendedores de OneProvider. Con ejemplos.
Emite lotes de códigos canjeables, revócalos, canjea un código por una clave y gestiona tus planes de tarifas con la API de revendedores.
Todos los modelos, capacidades y precios Índice de la documentación para agentes de IA:https://oneprovider.dev/docs/llms.txt Lotes de códigos
Un lote se crea con POST /code-batches (permiso codes; el encabezado Idempotency-Key es obligatorio): label, count hasta 200, amount_usd hasta 5000 por código. Opcionales: key_expires_days o key_expires_hours (cuánto vive la clave después de activar el código, por defecto 90 días), o key_expires_never: true (una clave sin vencimiento, el límite sigue vigente; no se combina con una vida útil), y codes_valid_until (hasta cuándo se puede activar un código, ISO 8601, en el futuro y como máximo a 2 años; después los códigos sin activar se revocan automáticamente y la reserva se devuelve).
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 lote solo reserva su costo (count × amount_usd) en el saldo de revendedor: tiene que caber en Disponible (Free), pero no se descuenta nada. Cuando se activa un código, se convierte en una clave cuyo límite sigue reservado, y el dinero se descuenta a medida que se gasta. Al revocar los códigos sin activar, la reserva se libera. Objeto lote: id, label, count, amount_usd, used, revoked, key_expires_hours, key_expires_days, key_expires_never, codes_valid_until, created_at (key_expires_hours y key_expires_days son null tanto en un lote sin vencimiento de clave como en uno con el valor por defecto de 90 días: key_expires_never los distingue). GET /code-batches/{id} también incluye activations: quién activó qué código y cuándo (code_tail, redeemed_at, key_id), de más reciente a más antiguo, como máximo 1000; la respuesta de revocación también incluye revoked_now y 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"Objeto código: code, status (active, used, revoked: active/used/revoked), amount_usd, batch_id, redeemed_at, key_id. Estado de un código: GET /codes/{code}.
Canjear un código por la API
Si conviertes tú mismo un código en una clave, llama a POST /codes/{code}/redeem (el encabezado Idempotency-Key es obligatorio). El cliente se puede pasar como customer_id o 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 respuesta 201 contiene la clave y su secreto (repetir la misma llamada con el mismo Idempotency-Key devuelve la misma clave). Un código ya canjeado de otra forma da 409 code_used, uno revocado 409 code_revoked; customer_id junto con customer_external_id es 400 invalid, un cliente bloqueado es 409 customer_blocked.
Planes
Un plan es tu precio para los clientes: cuántos USD recibe la clave, cuánto te paga el cliente, en qué moneda y por cuánto tiempo. Los planes alimentan POST /orders (el parámetro plan_id). El máximo es de 20 planes (409 plan_limit). Para leer los planes hace falta el permiso read, para cambiarlos plans.
| Campo | Descripción |
|---|---|
name | Nombre, hasta 40 caracteres. |
balance_usd | El importe que recibe la clave. |
price, currency | Tu precio para el cliente y su moneda: USD, RUB, XTR o USDT. |
expires_days / expires_hours | Vida útil de la clave: de 1 a 365 días o de 1 a 8760 horas (una de las dos; por defecto 30 días). La respuesta incluye expires_hours (la fuente de verdad); expires_days es null cuando la vida útil no es un número entero de días. |
expires_never | true: las claves del plan nunca vencen (el límite de saldo sigue vigente). No se combina con expires_days ni expires_hours (400 invalid). En la respuesta, expires_hours y expires_days son null. |
sort, active | Orden de visualización e indicador de activo. |
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 devuelve los límites que debes respetar: importe mínimo y máximo de la clave, vida útil máxima, importe máximo del código, tamaño del lote, la cantidad de planes y de tokens, la cantidad de claves activas (key_limit) y plan_currencies (las monedas de los planes). Un plan se puede crear con un Idempotency-Key (opcional): una repetición devuelve el mismo plan en lugar de crear un segundo. Un PATCH que no menciona la vida útil la deja como estaba. Eliminar, subir el precio y cambiar la moneda se rechazan mientras haya una compra abierta en el bot con ese plan (409 plan_in_use).