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:
Excepción: POST /api/v1/auth/sessions devuelve un objeto JSON plano a nivel raíz — sin envelope data:
Las respuestas de lista incluyen un objeto meta con información de paginación:
El endpoint 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):
El objeto errors está indexado por external_invoice_id.
Paginación
Los endpoints de lista aceptan dos parámetros de consulta:
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.
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.
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:
Códigos de error
