Introducción

La API de BuildNexion te deja leer los datos de tu empresa en JSON: obras, presupuestos, ofertas, facturas de compra, albaranes, proveedores, documentos, cumplimiento de subcontratas, usuarios y el resumen económico de cada obra. Y con los webhooks te avisamos al momento de lo que cambia.

Cómo se organizan los datos

• Presupuesto (/estimates): el trabajo de estudio que se presenta al cliente. Recibe un código al crearse (p. ej. 2026-014).
• Obra (/projects): nace al adjudicar un presupuesto y conserva su código. La obra lleva estimate_id y el presupuesto, project_id.
• Oferta (/budgets): el documento comercial que se envía al cliente, con capítulos y partidas a precio de coste y de venta. Sale de un presupuesto y, si se adjudica, queda en la obra.
• Compras: facturas de compra (las que te envían tus proveedores) y albaranes, imputados a una obra. Las facturas que emites a tus clientes no están en la API.
• Proveedores y subcontratas (/providers), con sus contactos y, en cada obra, su documentación CAE.

Antes de empezar

1. Una cuenta de BuildNexion en periodo de prueba o con la suscripción al día (si no, la API responde 402).
2. Ser administrador de la organización: solo los administradores crean API keys.
3. Una API key, que se crea en Configuración → Integraciones (ver Autenticación).

Tu primera llamada

Lista tus obras. Es la forma más rápida de comprobar que la key funciona:

curl "https://app.buildnexion.com/api/v1/projects?limit=5" \
  -H "Authorization: Bearer $BUILDNEXION_API_KEY"

La respuesta tiene este aspecto:

{
  "data": [
    {
      "id": "6f1c2a9e-3b7d-4c1e-9a52-1d0e8b7c4a21",
      "name": "Reforma integral vivienda C/ Mayor 12",
      "code": "2026-014",
      "status": "active",
      "category": "residencial",
      "client": {
        "name": "Construcciones Ejemplo SL",
        "nif": "B00000000",
        "address": null,
        "email": "obras@ejemplo.es",
        "phone": null
      },
      "contract_amount": 84500,
      "estimate_id": "2b8e4d10-7c3a-4f5e-8d21-0a9b6c3e1f47",
      "is_demo": false,
      "created_at": "2026-08-20T10:14:22.481+00:00",
      "updated_at": "2026-10-02T08:01:10.112+00:00",
      "app_url": "https://app.buildnexion.com/projects/6f1c2a9e-3b7d-4c1e-9a52-1d0e8b7c4a21",
      "…": "(más campos: ver Obras)"
    }
  ],
  "pagination": {
    "limit": 5,
    "next_cursor": "eyJ2IjpbIjIwMjYtMDgtMjBUMTA6MTQ6MjIuNDgxKzAwOjAwIiwiNmYxYzJhOWUtLi4uIl19"
  }
}

Convenciones

• URL base: https://app.buildnexion.com/api/v1. Solo HTTPS.
• Formato: JSON en UTF-8. Las respuestas van en data; los listados añaden pagination (ver Paginación).
• Ids: UUID (6f1c2a9e-3b7d-4c1e-9a52-1d0e8b7c4a21).
• Fechas: los días van como YYYY-MM-DD y los momentos en ISO 8601 con zona horaria, en UTC (2026-10-02T08:01:10.112+00:00).
• Importes: en euros, como número con decimales (1234.56), no en céntimos. Cada campo indica si lleva IVA; el resumen económico va siempre sin IVA.
• Valores en español: muchos estados son los de la app (en_estudio, conciliada, pendiente_factura…). Cada endpoint lista los suyos.
• Obras de demostración: las que crea la app para enseñarla no salen en los listados salvo que pidas include_demo=true.
• Campos nuevos: podemos añadir campos a las respuestas y eventos nuevos a los webhooks sin avisar. Tu integración debe ignorar lo que no conozca. Un cambio incompatible iría en una versión nueva (/api/v2).

Sigue con Autenticación, Paginación y sincronización y Errores.