Facturas de compra

Las facturas que te envían tus proveedores y subcontratas, leídas por la app e imputadas a una obra. Las facturas que emites a tus clientes no están en la API.

Listar facturas

GET/api/v1/invoicesread:invoices

Por fecha de factura, de la más reciente a la más antigua.

Parámetros (query)

Parámetro	Tipo	Descripción
status string	string	en_cola y digitalizando (la app aún la está leyendo), pending_review (leída, pendiente de revisar), pendiente (revisada, sin conciliar), aprobada (aprobada sin albaranes que conciliar), conciliada (cuadra con sus albaranes) o discrepancia (no cuadra).
project_id uuid	uuid	Facturas de una obra.
provider_id uuid	uuid	Facturas de un proveedor (también vale proveedor_id).
q string	string	Busca en el número de factura y en el proveedor.
paid boolean	boolean	true: las pagadas (con fecha de pago). false: las pendientes de pago (sin los abonos, que no se pagan). También vale pagada.
from / to date	date	Fecha de la factura desde / hasta (YYYY-MM-DD).
limit / cursor —	—	Paginación: de 1 a 200 por página (50 por defecto).

curl "https://app.buildnexion.com/api/v1/invoices?project_id=6f1c2a9e-3b7d-4c1e-9a52-1d0e8b7c4a21&from=2026-09-01" \
  -H "Authorization: Bearer $BUILDNEXION_API_KEY"

Respuesta

{
  "data": [
    {
      "id": "c41e7b92-0d5a-4a3f-9e68-7b2d1c0f5a84",
      "project_id": "6f1c2a9e-3b7d-4c1e-9a52-1d0e8b7c4a21",
      "number": "F-2026/0457",
      "supplier": "Materiales del Sur SL",
      "provider_id": "4a9d1e73-6c2b-4d8f-90e5-b17a3c6d2e08",
      "amount": 1815,
      "type": "factura",
      "date": "2026-09-30",
      "due_date": "2026-10-30",
      "paid_date": "2026-10-28",
      "notes": null,
      "status": "conciliada",
      "rectified_invoice_id": null,
      "image_url": "https://…supabase.co/storage/v1/object/sign/facturas-images/…?token=…",
      "created_at": "2026-10-01T07:52:18.640+00:00",
      "delivery_notes": [
        {
          "id": "e7a2c5d8-91b4-4f60-b3d7-28c6e1a09f53",
          "supplier": "Materiales del Sur SL",
          "total_amount": 1815,
          "delivery_date": "2026-09-12",
          "status": "approved"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 50,
    "next_cursor": null
  }
}

Campos

Parámetro	Tipo	Descripción
number string \| null	string \| null	Número de la factura.
supplier / provider_id string / uuid \| null	string / uuid \| null	Nombre del proveedor tal como figura en la factura y, si está identificado, su id (ver Proveedores).
amount number	number	Importe total de la factura, IVA incluido, en euros. En un abono, en negativo.
type string	string	factura o abono (factura rectificativa o nota de abono: resta del coste de la obra).
date / due_date date \| null	date \| null	Fecha de la factura y de vencimiento.
paid_date date \| null	date \| null	Fecha en que se pagó; null si no consta como pagada. Un abono no se paga.
status string	string	Estado (ver el filtro status). Un abono no se concilia con albaranes: al aprobarlo queda aprobada.
rectified_invoice_id uuid \| null	uuid \| null	En un abono, la factura que rectifica, si se ha indicado.
image_url string \| null	string \| null	Enlace al archivo original (PDF o imagen). Caduca en 1 hora: descárgalo al momento o vuelve a pedir la factura.
delivery_notes array	array	Albaranes conciliados con la factura: id, supplier, total_amount, delivery_date, status.

Leer una factura

GET/api/v1/invoices/{id}read:invoices

Lo mismo, más lines: las líneas que la app leyó del documento, tal como salen de la lectura (normalmente descripcion, cantidad, unidad, precio_unitario e importe). Si no se leyeron líneas, [].

curl "https://app.buildnexion.com/api/v1/invoices/c41e7b92-0d5a-4a3f-9e68-7b2d1c0f5a84" \
  -H "Authorization: Bearer $BUILDNEXION_API_KEY"

Para las facturas vencidas, pide /invoices?paid=false y quédate con las que tienen due_date anterior a hoy.

El webhook invoice.created trae además la base imponible, el IVA, la forma de pago, el IBAN y los datos del proveedor leídos de la factura (ver eventos).