Límites y convenciones

Límites de peticiones, paginación y las convenciones comunes a toda la API.

Límites de peticiones

Cada clave API lleva asociado un límite de peticiones por segundo y una cuota mensual:

La cuota mensual es por clave, no por cuenta: cada clave tiene su propio contador, y se reinicia el día 1. Rotar tampoco lo reinicia. La clave nueva hereda el consumo de la anterior. Lo que llevas gastado se lee en el campo consumo de GET /v1/cuenta, junto con la marca de tiempo de la lectura: va unos minutos por detrás, así que sirve para anticipar el tope, no para decidir si la siguiente llamada entrará. Superar cualquiera de los dos límites devuelve 429. Trátalo con retroceso exponencial, que el cliente de Python ya trae; si el 429 responde a la cuota mensual, reintentar no ayuda: contacta con el equipo para ampliar el plan.

Los límites se comparten entre la API de facturación y la API de gestión: las consultas de estado y las comprobaciones de /v1/cuenta también cuentan. Para volúmenes altos, los webhooks eliminan la mayor parte del polling.

Paginación

Un solo patrón en todos los listados: la petición acepta limite y cursor, y la respuesta devuelve proximaPagina (el cursor de la página siguiente, null cuando no hay más):

GET /v1/facturas?nifEmisor=B98765432&limite=100
GET /v1/facturas?nifEmisor=B98765432&limite=100&cursor=eyJQSyI6…

En los listados de facturación, limite es 100 por defecto y 500 como máximo. Pedir más del máximo no es un error: la respuesta se recorta a 500. Un limite no entero o menor que 1 sí lo es: 400 INVALID_PARAMETER, nombrando el parámetro. Los listados de la API de gestión son más indulgentes: un limite inválido cae al valor por defecto en lugar de responder un error. El cursor es opaco: pásalo de vuelta tal cual en cursor, sin interpretarlo ni construirlo. Los cursores caducan; no los persistas entre sesiones.

Convenciones

• Formato: JSON en peticiones y respuestas, Content-Type: application/json. Las excepciones: el QR (image/png) y el XML firmado (application/xml).
• Importes: cadenas decimales con dos decimales ("121.00"). Nunca números en coma flotante: 121.0 puede perder precisión por el camino, y un céntimo descuadrado es un registro rechazado. El formato lo fijan los esquemas de las administraciones: hasta 12 dígitos enteros, como máximo dos decimales y el punto como separador. La notación científica ("1e3"), la coma decimal ("1,00"), un tercer decimal y un valor no numérico responden 400 nombrando el campo. En TicketBAI, cantidad e importeUnitario admiten hasta ocho decimales.
• Campos de texto: la API se encarga del escapado del XML, así que el texto viaja tal cual: sin entidades XML o HTML ya codificadas (<, �, &…), que se rechazan con 400 en ambos sistemas por ser una doble codificación, y sin caracteres de control ilegales en XML. Un & suelto en un nombre es correcto. Los límites de longitud y las restricciones de serie y numero los fija cada especificación. Ver VeriFactu y TicketBAI.
• Fechas de factura: dd-mm-aaaa ("03-04-2026"), el formato de la normativa. Reglas completas (no-futuro, zona horaria, fecha de operación) en Fechas de la factura.
• Marcas de tiempo generadas por la API: ISO 8601 UTC con sufijo Z (creadoEn, validadoEn).
• Alta síncrona, remisión asíncrona: los endpoints de emisión devuelven 200 con el registro validado, firmado y encolado; el resultado de la remisión se consulta en /estado o llega por webhook.
• Avisos: el campo avisos, cuando aparece, lista avisos de validación no bloqueantes. Revísalos: suelen anticipar rechazos futuros.

El campo idMaquina

Todos los endpoints de emisión y anulación aceptan un idMaquina opcional (máx. 64 caracteres, A-Za-z0-9._-): el identificador del dispositivo, TPV o proceso que originó la petición. Se conserva en el registro y se devuelve en /v1/registros (trazabilidad para tu propia observabilidad, sin efecto en el procesamiento).

Para emisores de gran volumen con muchos dispositivos existe un modo contratado, Alta capacidad, en el que idMaquina deja de ser metadato y pasa a encaminar una cadena de encadenado por dispositivo. Los dispositivos se dan de alta con /v1/clientes/{nif}/dispositivos y cada serie queda atada de forma permanente a un solo dispositivo. Si emites desde decenas de TPV con el mismo NIF, habla con el equipo.