Listar todas las facturas
Lista tus facturas de venta con paginación por cursor. Admite filtrado por `status[in]`, `client_id`, `series_id`, `issued_on[gte|lte]` y `total[gte|lte]`.
En: header
Parámetros de consulta
uuidNúmero de objetos a devolver. Entero entre 1 y 100. Por defecto 25.
251 <= value <= 100Cursor para paginación hacia delante. Usa el uuid del último objeto de la página anterior.
uuidCursor para paginación hacia atrás. Usa el uuid del primer objeto de la página actual.
uuidEstado de la factura. Coincidencia exacta con status.
Estado de la factura. Lista separada por comas. Coincide cualquiera de los valores.
Client ID (UUID v7). Coincidencia exacta con client_id.
uuidClient ID (UUID v7). Lista separada por comas. Coincide cualquiera de los valores.
Series ID (UUID v7). Coincidencia exacta con series_id.
uuidSeries ID (UUID v7). Lista separada por comas. Coincide cualquiera de los valores.
Fecha de creación (ISO 8601). Mayor o igual que el valor dado.
date-timeFecha de creación (ISO 8601). Menor o igual que el valor dado.
date-timeFecha de creación (ISO 8601). Estrictamente mayor que el valor dado.
date-timeFecha de creación (ISO 8601). Estrictamente menor que el valor dado.
date-timeFecha de vencimiento. Mayor o igual que el valor indicado.
dateFecha de vencimiento. Menor o igual que el valor indicado.
dateFecha de vencimiento. Estrictamente mayor que el valor indicado.
dateFecha de vencimiento. Estrictamente menor que el valor indicado.
dateImporte total. Mayor o igual que el valor dado.
Importe total. Menor o igual que el valor dado.
Importe total. Estrictamente mayor que el valor dado.
Importe total. Estrictamente menor que el valor dado.
Código de moneda ISO 4217 (p. ej. EUR). Coincidencia exacta con currency.
Código de moneda ISO 4217 (p. ej. EUR). Lista separada por comas. Coincide cualquiera de los valores.
Número de factura. Coincidencia exacta con number.
Filtrar por tag de clasificación (slug en minúscula). Admite múltiples valores con tags[in]=a,b (JSON_CONTAINS, semántica OR — coincide con las facturas que llevan CUALQUIERA de los tags). Coincidencia exacta sobre tags.
Filtrar por tag de clasificación (slug en minúscula). Admite múltiples valores con tags[in]=a,b (JSON_CONTAINS, semántica OR — coincide con las facturas que llevan CUALQUIERA de los tags). Lista separada por comas. Coincide cualquiera de los valores.
Orden de los resultados. Usa un campo para ascendente o un prefijo - para descendente (p. ej. -created). Campos permitidos: created, total, number. Combinado con el cursor, el orden se mantiene determinista (un orden secundario estable por el id del cursor, al estilo Stripe). Si se omite, los resultados siguen el orden de cursor por defecto (created descendente).
"created" | "-created" | "total" | "-total" | "number" | "-number"Cuerpo de la respuesta
application/json
application/json
application/json
application/json
application/json
application/json
{
"data": [
{
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
"object": "invoice",
"number": "FAC-2026-00042",
"is_number_assigned": true,
"type": "F1",
"series": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02",
"code": "FAC-2026"
},
"client": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
"name": "Acme Soluciones SL"
},
"status": "paid",
"issued_on": "2026-03-15",
"due_on": "2026-04-14",
"subtotal": 1000,
"taxes_total": 210,
"total": 1210,
"currency": "EUR",
"notes": "Servicios profesionales marzo 2026.",
"external_id": "ERP-2026-0042",
"lines": [
{
"object": "invoice_line",
"description": "Consultoría técnica (10 h)",
"product": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03",
"name": "Consultoría técnica (hora)"
},
"quantity": 10,
"unit_price": 100,
"tax_rate": 21,
"discount_percent": 0,
"subtotal": 1000,
"taxes": 210,
"total": 1210
}
],
"metadata": {
"order_id": "PO-2026-0042"
},
"tags": [
"consultoria",
"cliente-vip"
],
"custom_fields": [
{
"field": "centro_coste",
"value": "CC-2026-001"
},
{
"field": "numero_pedido",
"value": "PO-2026-0042"
}
],
"operation_regime": "general",
"exclude_347": false,
"verifactu_status": "accepted",
"paid_amount": 1210,
"pending_amount": 0,
"payments": {
"detail": [
{
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90",
"object": "payment",
"invoice_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
"amount": 1210,
"payment_date": "2026-03-20",
"payment_method": "bank_transfer",
"payment_method_text": "Transferencia bancaria",
"reference": "TRF-2026-0042",
"notes": null,
"created_at": "2026-03-20T10:30:00Z",
"updated_at": "2026-03-20T10:30:00Z"
}
],
"total": 1210,
"pending": 0
},
"is_corrective": false,
"corrective": null,
"payment": {
"method": "bank_transfer",
"reference": "TRF-2026-0042",
"date": "2026-03-20"
},
"public_link": {
"object": "public_link",
"url": "https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
"enabled": true,
"expires_at": "2026-09-15T23:59:59Z",
"max_days": 120
},
"substituted_by": null,
"recurring": null,
"paid_at": "2026-03-20T10:30:00Z",
"paid_on": "2026-03-20",
"sent_at": "2026-03-15T11:45:00Z",
"voided_at": null,
"void_reason": null,
"created_at": "2026-03-15T11:30:00Z",
"updated_at": "2026-03-20T10:30:00Z"
}
],
"has_more": true,
"next_cursor": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c"
}{
"error": {
"type": "authentication_error",
"code": "missing_api_key",
"message": "No se ha proporcionado una API key válida en el header Authorization.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
"request_id": "req_01HKQS5N8VR7QXJ9K3T6BWPMZA"
}
}{
"error": {
"type": "authorization_error",
"code": "insufficient_scope",
"message": "Esta API key no tiene el scope requerido para esta operación.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
"request_id": "req_01HKQS5NBC3P8M1KX4V7SLNHQD"
}
}{
"error": {
"type": "invalid_request_error",
"code": "parameter_invalid",
"message": "El campo `name` es obligatorio y no puede estar vacío.",
"param": "name",
"doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid",
"request_id": "req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"
}
}{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Has excedido el rate limit de 60 peticiones por minuto. Reintenta tras 30 segundos.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
"request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVL"
}
}{
"error": {
"type": "api_error",
"code": "internal_error",
"message": "Ha ocurrido un error inesperado. Si persiste, contacta con soporte adjuntando el request_id.",
"param": null,
"doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
"request_id": "req_01HKQS5NLX2D7X0U5H6J1KCAWM"
}
}Buscar una factura por número
Busca una única factura por su número, con un `year` opcional para desambiguar entre ejercicios fiscales. Devuelve 404 si no se encuentra y 422 si el número es ambiguo y no se proporciona `year`.
Marca la factura como pagada
Marca una factura como totalmente pagada. Idempotente: si ya está pagada, devuelve la factura sin cambios. Devuelve 422 si la factura está en un estado que no puede transicionar a `paid`.