URL base
Todos los endpoints de la API son relativos a:
Versiones
La versión estable actual es v1. Todos los endpoints v1 tienen el prefijo /api/v1/.
No existen cabeceras de negociación de versión — la versión forma parte de la ruta de la URL.
- Content type:
application/json
- Codificación: UTF-8
- Todos los timestamps deben estar en formato ISO 8601 (
YYYY-MM-DDTHH:MM:SSZ)
- Las fechas (sin hora) deben ser
YYYY-MM-DD
Todas las respuestas devuelven JSON.
Excepción: GET /api/v1/batch_invoices/{id}/pdf devuelve un payload binario application/pdf (el PDF de la factura emitida asociada).
La mayoría de endpoints que devuelven un único recurso envuelven el contenido en la clave data:
{
"data": {
"id": 123,
"status": "received",
...
}
}
POST /api/v1/auth/sessions devuelve un objeto JSON plano a nivel raíz — sin envelope data:
{
"session_token": "...",
"expires_at": "2026-03-27T10:30:00Z"
}
meta con información de paginación:
{
"data": [...],
"meta": {
"current_page": 1,
"total_pages": 4,
"total_count": 87,
"per_page": 25
}
}
POST /api/v1/invoice_batches puede incluir adicionalmente una clave errors junto a data cuando algunas facturas del lote fallan la validación (éxito parcial):
{
"data": { ... },
"errors": {
"inv-bad-001": ["Issuer nif no puede estar en blanco"]
}
}
errors está indexado por external_invoice_id.
Paginación
Los endpoints de lista aceptan dos parámetros de consulta:
| Parámetro | Tipo | Por defecto | Máximo | Descripción |
|---|
page | integer | 1 | — | Número de página (base 1) |
per_page | integer | 25 | 100 | Resultados por página |
Idempotencia
POST /api/v1/invoice_batches requiere la cabecera Idempotency-Key con un UUID válido. Reenviar la misma clave dentro de la ventana de idempotencia devuelve la respuesta cacheada sin reprocesar el lote.
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Rate limiting
La mayoría de endpoints protegidos aplican límites de tasa por organización. Cuando se supera el límite, la API devuelve 429 Too Many Requests con la cabecera Retry-After indicando los segundos de espera.
HTTP/1.1 429 Too Many Requests
Retry-After: 30
POST /api/v1/invoice_batches está excluido del rate limiting — la idempotencia ya previene el procesamiento duplicado.
Respuestas de error
Todos los errores siguen un envelope consistente:
{
"error": {
"code": "string",
"message": "Descripción legible"
}
}
Códigos de error
| Estado HTTP | Código | Descripción |
|---|
400 | bad_request | Parámetro requerido ausente o vacío |
401 | unauthorized | Autenticación ausente, inválida o expirada |
404 | not_found | Recurso no encontrado en la organización actual |
422 | missing_idempotency_key | La cabecera Idempotency-Key está ausente |
422 | invalid_idempotency_key | Idempotency-Key no es un UUID válido |
422 | validation_failed | El cuerpo de la solicitud falló la validación (ver message) |
422 | unprocessable_content | El registro no pudo guardarse por errores de validación |
429 | too_many_requests | Demasiadas solicitudes — consulta la cabecera Retry-After |
