Facturas

Las facturas son documentos emitidos por proveedores e imputados a un proyecto. Cada factura puede asociarse a uno o varios albaranes y a partidas concretas del presupuesto.

El objeto factura

json

{
  "id":              "inv_W3pNxL2YqAt",
  "project_id":      "prj_8GcyLwT4mPq",
  "provider_id":     "prov_4kqRpBn",
  "invoice_number":  "F-2026-00128",
  "issue_date":      "2026-05-12",
  "due_date":        "2026-06-11",
  "status":          "pending",
  "subtotal_amount": 248050,
  "tax_amount":      52091,
  "total_amount":    300141,
  "currency":        "EUR",
  "reconciliation_status": "unmatched",
  "delivery_note_ids":     [],
  "budget_item_ids":       [],
  "created_at":            "2026-05-12T10:14:22.000Z",
  "updated_at":            "2026-05-12T10:14:22.000Z"
}

Todos los importes están en céntimos (enteros). 300141 = 3.001,41 €.

Listar facturas

GET/v1/invoices

Devuelve facturas paginadas. Por defecto las más recientes primero.

Query parameters

Parámetro	Tipo	Descripción
project_id	string	Filtra por proyecto.
provider_id	string	Filtra por proveedor.
status	string	pending · paid · cancelled
from	date	Fecha mínima (ISO YYYY-MM-DD) sobre issue_date.
to	date	Fecha máxima sobre issue_date.
cursor	string	Cursor de la página anterior (devuelto en pagination.next_cursor).
limit	integer	Entre 1 y 100. Default 25.

curl "https://api.buildnexion.com/v1/invoices?project_id=prj_8GcyLwT4mPq&limit=25" \
  -H "Authorization: Bearer bn_live_xxxxxxxxxxxxxxxxxxxx"

json

{
  "data": [
    { "id": "inv_W3pNxL2YqAt", "invoice_number": "F-2026-00128", "total_amount": 300141, "status": "pending" }
  ],
  "pagination": { "next_cursor": "Y3Vyc29yPTI=", "limit": 25 }
}

Obtener una factura

GET/v1/invoices/{id}

Path

Parámetro	Tipo	Descripción
id*	string	ID de la factura (inv_*).

Crear una factura

POST/v1/invoices

Body

Parámetro	Tipo	Descripción
project_id*	string	Proyecto al que se imputa.
provider_id*	string	Proveedor emisor.
invoice_number*	string	Nº de factura del proveedor.
issue_date*	date	Fecha de emisión (YYYY-MM-DD).
due_date	date	Fecha de vencimiento.
subtotal_amount*	integer	Base imponible en céntimos.
tax_amount*	integer	IVA / impuestos en céntimos.
total_amount*	integer	Total en céntimos.
currency	string	ISO-4217. Default EUR.
pdf_url	string	URL del PDF original (opcional, se descarga y archiva).

curl -X POST https://api.buildnexion.com/v1/invoices \
  -H "Authorization: Bearer bn_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id":      "prj_8GcyLwT4mPq",
    "provider_id":     "prov_4kqRpBn",
    "invoice_number":  "F-2026-00128",
    "issue_date":      "2026-05-12",
    "due_date":        "2026-06-11",
    "subtotal_amount": 248050,
    "tax_amount":      52091,
    "total_amount":    300141,
    "currency":        "EUR"
  }'

Si ya existe una factura con el mismo provider_id, invoice_number e issue_date, recibirás 409 duplicate_resource con el ID existente en details.existing_id.

Actualizar una factura

PATCH/v1/invoices/{id}

Sólo se actualizan los campos enviados. Para cambiar el estado a pagada:

bash

curl -X PATCH https://api.buildnexion.com/v1/invoices/inv_W3pNxL2YqAt \
  -H "Authorization: Bearer bn_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid", "paid_at": "2026-05-30" }'

Eliminar una factura

DELETE/v1/invoices/{id}

Borrado lógico: la factura se archiva y deja de aparecer en los listados, pero queda recuperable durante 90 días.

Notas

Paginación: usa pagination.next_cursor y pásalo como cursor en la siguiente llamada. Si es null, has llegado al final.
Conciliación: para enlazar la factura con albaranes, usa POST /v1/invoices/{id}/match con un body { "delivery_note_ids": [...] }.
OCR: si subes el PDF vía la app, la factura se crea automáticamente con los campos extraídos. Por API debes enviar los campos ya parseados.