#Créditos y consumo

El acceso a la API pública depende del plan contratado por la empresa. Los planes compatibles incluyen una bolsa común de créditos para todas sus integraciones. No se asigna una bolsa distinta a cada cliente o credencial.

La configuración inicial incluye 2.000 créditos mensuales en el plan de 199 € y 5.000 en el plan de 299 €. Estos valores pueden cambiar en la configuración comercial del plan.

La bolsa se renueva el primer día de cada mes a las 00:00, según la zona horaria de la empresa. Los créditos no utilizados no pasan al mes siguiente.

#Coste de las operaciones

Cada operación muestra su coste junto al método y la ruta en el portal de desarrolladores. Al publicar este sistema:

• Las operaciones de negocio cuestan un crédito por petición.
• POST /api/public/v1/token no consume créditos.
• GET /api/public/v1/usage no consume créditos.

Cada página solicitada en un listado cuenta como una petición. Los listados públicos devuelven hasta 50 registros por página.

El coste se aplica a la petición atribuible aunque termine con un error de validación o de negocio. Los fallos internos de la plataforma no consumen créditos. La referencia del portal es la fuente vigente para consultar el coste de cada operación.

#Consultar el consumo

Usa un bearer token válido para consultar el periodo actual:

GET /api/public/v1/usage
Authorization: Bearer <token>

No hace falta conceder un scope adicional. La respuesta contiene:

• allowance: créditos incluidos en el periodo.
• consumed: créditos ya confirmados como consumidos.
• remaining: saldo confirmado disponible.
• accountingStatus: estado del recuento, con los valores healthy, pending o unconfirmed.
• periodStartUtc, periodEndUtc y resetAtUtc: límites y renovación del periodo en UTC.
• operations: peticiones y créditos agrupados por operación.
• clients: desglose correspondiente al cliente de API conectado.

Cuando accountingStatus es pending o unconfirmed, remaining puede ser null. No uses un saldo sin confirmar para decidir si puedes enviar nuevas operaciones.

#Cabeceras de respuesta

Las respuestas atribuibles pueden incluir estas cabeceras:

• X-Credits-Charged: créditos cobrados por la petición.
• X-Monthly-Credits-Remaining: saldo mensual confirmado.
• X-Monthly-Credits-Reset: fecha y hora de renovación en UTC.
• X-Credit-Accounting-Status: estado del recuento.

El saldo no se devuelve cuando el recuento está pendiente o no se ha podido confirmar.

#Cuota agotada y recuento no disponible

Si no hay saldo suficiente, la API rechaza la operación antes de ejecutarla con HTTP 429 y el código monthly_credit_quota_exceeded. El error indica el coste intentado, el saldo observado y la fecha de renovación.

Un 429 también puede corresponder al límite de peticiones en un intervalo corto. Consulta el campo code de la respuesta y la cabecera Retry-After para distinguir ambos casos.

Si el sistema no puede comprobar el saldo de forma segura, devuelve HTTP 503 con el código credit_accounting_temporarily_unavailable. Reintenta la petición más tarde y conserva el correlationId si necesitas comunicar la incidencia a soporte.