Autenticación y límites de la API de revendedores

Tokens Bearer, permisos (scopes), lista de IP permitidas, límite de frecuencia, códigos de error, claves de idempotencia y paginación de la API de revendedores.

Tokens

Un token tiene la forma rsk_ seguido de 40 caracteres. Créalo en el panel (pestaña de revendedor, «API y ajustes»); el valor se muestra una sola vez, y nosotros guardamos solo un hash y los últimos 4 caracteres. Puedes tener hasta 10 tokens activos y revocar cualquiera en cualquier momento. Al crear un token se le puede dar una vida útil (de 1 a 365 días): pasada esta, el token responde 401 token_expired, y expires_at en GET /me indica cuándo ocurre (null: sin vencimiento).

Authorization: Bearer rsk_...

Permisos (scopes)

Un token lleva un conjunto de permisos. Los permisos son independientes: keys no implica read. GET /me funciona con cualquier token válido. Sin el permiso necesario, la respuesta es 403 forbidden_scope.

El permiso de cada método figura en la referencia .

Lista de IP permitidas

Un token puede limitarse a una lista de direcciones IPv4/IPv6 o rangos CIDR (hasta 20). Una solicitud desde otra dirección recibe 403 ip_not_allowed. La lista se define al crear el token.

Límite de frecuencia

20 solicitudes por segundo por token y 100 por segundo por dirección IP de origen. Al superarlo: 429 rate_limited y un encabezado Retry-After. Espera esa cantidad de segundos y reintenta.

Errores

Todos los errores tienen la misma estructura. El mismo id se envía en el encabezado X-Request-Id: indícalo al soporte.

{
"error": {
"code": "insufficient_balance",
"message": "Not enough free reseller balance for this key.",
"request_id": "req_..."
}
}

Decide según error.code, no según el texto del mensaje.

Idempotencia

Los métodos que gastan dinero exigen el encabezado Idempotency-Key (de 1 a 128 caracteres imprimibles); sin él (o con uno no válido) la respuesta es 400 idempotency_key_required. Están marcados en la referencia. Repetir una solicitud con la misma clave y el mismo cuerpo (por revendedor) nunca gasta dos veces y devuelve el mismo objeto, incluido el secreto de la clave que creó esa llamada: una respuesta perdida por el camino se recupera repitiendo la llamada. La misma clave con otro cuerpo da 409 idempotency_key_reused. Usa una clave nueva para cada pago o pedido nuevo; en POST /orders la identidad es external_order_id. El encabezado es opcional (y se respeta si se envía) en PATCH /keys/{id} (un extend_days/extend_hours repetido amplía una sola vez), POST /plans y POST /webhooks (una repetición devuelve el mismo objeto; el secreto del webhook no se vuelve a mostrar).

curl -s -X POST https://app.oneprovider.dev/partner/v1/keys \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"client-1","limit_usd":"10.00"}'

Guarda la clave de idempotencia junto con tu propio registro del pedido para que, tras un error de red, reintentes exactamente la misma solicitud.

Paginación

Los endpoints de listas aceptan ?limit=1..100 (por defecto 50) y &cursor=. La respuesta es {"items": [...], "next": "<cursor>"}; next es null en la última página. El cursor es opaco: devuélvelo tal cual.

curl -s "https://app.oneprovider.dev/partner/v1/keys?limit=100&cursor=<next from the previous page>" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

Sandbox

Los tokens de prueba rsk_test_... llegarán pronto. Por ahora un token así recibe 501 sandbox_not_implemented.