La automatización de la facturación en construcción a través de API requiere arquitectura específica para manejar las particularidades del sector: documentos manuscritos, multi-formato de proveedores, estructura BC3, triple conciliación con tolerancias configurables y flujos de excepción dirigidos. Esta guía técnica describe los componentes clave que un equipo de IT de constructora mediana o grande necesita evaluar para conectar el ERP existente con servicios especializados de captura y conciliación.
Arquitectura de referencia
Para automatizar la facturación de construcción mediante API, la arquitectura típica involucra tres sistemas:
Captura: punto donde el albarán entra al ecosistema digital. Puede ser app móvil del encargado, email reenviado, drag-and-drop en navegador, o integración con sistemas de obra (BIM, gestión documental).
Servicio especializado: procesa el albarán (OCR especializado, validación, triple conciliación). Expone API REST para que el ERP consuma los datos estructurados.
API: capa de comunicación entre los dos sistemas. Pull (el ERP consulta) y push (webhooks notifican eventos al ERP).
ERP existente: sistema de registro financiero (Sage, Sigrid, SAP, Oracle, Holded). Recibe los albaranes y facturas ya conciliados.
Los cuatro dominios funcionales de la API
Dominio 1 — Gestión de maestros
El primer paso de cualquier integración: sincronizar los maestros entre ERP y servicio especializado.
Endpoints típicos:
Patrones técnicos exigibles:
- Sincronización incremental (sólo cambios desde última fecha) para evitar transferencias masivas innecesarias.
- Webhooks bidireccionales que notifiquen cambios al ERP cuando un maestro se actualiza desde el servicio especializado.
- Validación de integridad (CIF de proveedor consistente, códigos BC3 válidos).
Dominio 2 — Ingestión de documentos
Los albaranes y facturas entran al servicio especializado por varios canales. La API expone endpoints unificados:
Endpoints típicos:
Soporte de formatos:
- Imágenes: JPG, PNG, HEIC.
- Documentos: PDF (escaneado o nativo).
- Email: reenvío al endpoint de email-to-API.
- Estructurado: JSON, XML, EDI cuando aplique.
Patrones técnicos exigibles:
- Idempotencia (subir el mismo documento dos veces no genera duplicados).
- Procesamiento asíncrono (la respuesta inmediata es 202 Accepted; el resultado se entrega vía webhook o consulta posterior).
- Tamaño máximo razonable (típicamente 10-25 MB por documento).
- Metadata enriquecida (origen, usuario que subió, contexto operativo).
Dominio 3 — Recuperación de documentos procesados
Una vez procesado, el ERP consulta o recibe los documentos estructurados:
Endpoints típicos:
Estructura de respuesta típica para un albarán procesado:
Dominio 4 — Webhooks de eventos
Webhooks notifican al ERP cuando ocurren eventos relevantes, evitando polling continuo:
Eventos típicos:
Patrones técnicos exigibles:
- Reintentos con backoff exponencial si el endpoint del ERP no responde.
- Firmas HMAC para verificar autenticidad del webhook.
- Idempotencia (el ERP debe manejar webhooks duplicados sin duplicar registros).
- Cola de eventos para evitar pérdidas durante caídas del ERP.
Brinkr ofrece API REST documentada con los cuatro dominios cubiertos
OAuth 2.0, idempotencia, webhooks firmados, paginación, sandbox de pruebas. Solicite acceso a la documentación técnica completa y un piloto de integración con su ERP.
Patrones de seguridad y cumplimiento
Autenticación
Estándar exigible: OAuth 2.0 con flujo client credentials para integración server-to-server. Tokens con expiración (típicamente 1 hora) y refresh tokens.
Patrones legacy aceptables: API keys simples para casos puntuales, pero no recomendable como única autenticación en entornos productivos.
Autorización
Roles granulares: read-only, read-write, admin. Permisos por dominio (puede leer albaranes pero no modificar maestros, por ejemplo).
Encriptación
- TLS 1.2+ obligatorio para todas las comunicaciones.
- Datos sensibles (CIFs, importes) encriptados en reposo.
- PII (datos personales del receptor del albarán) bajo políticas RGPD.
Audit log
Cada acción vía API queda registrada con: timestamp, identidad del cliente API, endpoint llamado, payload (sin datos sensibles), respuesta. Consultable para auditoría.
Rate limiting
Protección contra abuso o errores de implementación. Típico: 1000 requests/minuto por cliente, con cabeceras de respuesta indicando cuota restante.
Patrones de integración recomendados
Patrón 1 — Pull periódico desde el ERP
El ERP consulta periódicamente los albaranes y facturas validados:
Ventaja: simple, robusto. Desventaja: latencia de hasta 15 minutos.
Patrón 2 — Push vía webhooks
El servicio especializado notifica al ERP en tiempo real:
Ventaja: tiempo real. Desventaja: requiere endpoint expuesto en el ERP.
Patrón 3 — Batch nightly
Para volúmenes muy altos o ERPs sin API moderna:
Ventaja: simple, sin requisitos técnicos del ERP. Desventaja: desfase de hasta 24 horas.
Patrón 4 — Híbrido (recomendado)
- Webhooks para eventos críticos (matching completado, excepción crítica).
- Pull periódico como red de seguridad.
- Batch nightly como reconciliación adicional.
Triple cobertura asegura que ningún dato se pierde aunque uno de los canales falle.
Manejo de errores y resiliencia
Errores transitorios
Servicios cloud fallan ocasionalmente. La API debe documentar:
- Códigos HTTP estándar (4xx para errores cliente, 5xx para errores servidor).
- Mensajes de error estructurados con trace IDs.
- Recomendación de retry para 429 (rate limit), 502, 503, 504.
Idempotencia
Operaciones de escritura deben ser idempotentes mediante claves de idempotencia:
Reintentos con la misma clave no duplican el documento.
Circuit breaker
Si el servicio especializado tiene problemas persistentes, el ERP debe poder degradar grácilmente: capturar albaranes en cola local, sincronizar cuando el servicio vuelva.
Plan de implementación de la integración API
Semana 1 — Diseño y autenticación
- Acceso a sandbox del proveedor.
- Configuración de credenciales OAuth.
- Primer "hello world" leyendo maestros.
Semanas 2-3 — Sincronización de maestros
- Sync inicial de proveedores, materiales, obras, plan contable.
- Validación de integridad de datos.
- Configuración de webhooks de cambios.
Semana 4 — Flujo de albaranes
- Procesamiento de los primeros albaranes vía API.
- Recuperación de datos estructurados al ERP.
- Validación de mapping campo a campo.
Semanas 5-6 — Flujo de facturas y matching
- Activación de la triple conciliación automática.
- Gestión de excepciones.
- Pruebas de carga con volumen real.
Semana 7+ — Operación
- Ejecución en producción supervisada.
- Monitorización de KPIs de integración.
- Optimización continua.
¿Existe documentación pública de la API?
Para Brinkr y otros proveedores serios, sí — accesible bajo registro o solicitando acceso comercial. La documentación incluye referencia OpenAPI/Swagger, ejemplos en múltiples lenguajes, sandbox de pruebas.
¿Qué lenguajes soporta el SDK?
Los proveedores serios ofrecen SDKs en los lenguajes más comunes: JavaScript/TypeScript, Python, PHP, Java, .NET. Para lenguajes menos comunes, la API REST es directamente consumible con librerías HTTP estándar.
¿Cuánto tarda en desarrollarse la integración?
Para una constructora mediana con equipo IT estándar (1-2 desarrolladores con experiencia REST): 4-6 semanas. Si se usa SDK oficial y patrones estándar, puede ser menos.
¿Es necesario un partner técnico?
Recomendable pero no estrictamente. Equipos IT internos con experiencia en integraciones API pueden hacerlo con la documentación y soporte del proveedor. Partners aportan velocidad y conocimiento del ERP destino.
¿Cómo manejamos las versiones de la API?
Versionado en URL (/api/v1/, /api/v2/) o en header (API-Version: 2026-04-01). Política típica: versiones mayores se mantienen mínimo 24 meses tras nueva versión, con anuncios formales de deprecation.
¿Qué pasa si el proveedor desaparece?
La capacidad de exportación libre garantiza que el archivo histórico es recuperable en formato abierto. La integración técnica con el ERP queda obsoleta, pero los datos no se pierden. Programar exportaciones periódicas es buena práctica.
¿Coste de los volúmenes a través de API?
Pricing típicamente por documento procesado, con planes que incluyen volúmenes amplios (5.000-50.000 documentos/mes según plan). Las llamadas a la API en sí (consultas, webhooks) suelen no facturarse.
Recibe nuevos artículos cada semana
Recursos prácticos sobre digitalización en construcción. Sin spam, una vez por semana, cancelas cuando quieras.
Datos tratados según RGPD. Puedes darte de baja en cualquier momento.
Sigue leyendo
Control de costes en obra: guía completa para constructoras (2026)
Guía práctica del control de costes en obra para constructoras pyme: qué medir, cómo medirlo y por qué la fuga grande está en materiales. Con números reales y ROI.
La administrativa de una constructora que recuperó 8 horas a la semana (caso real)
Caso compuesto de una administrativa de constructora pyme española que pasó de 12 horas a 4 horas semanales en albaranes. Qué cambió en su día a día y cómo aplicarlo.
Checklist de revisión de albarán antes de aprobar la factura (PDF gratis)
Checklist de 12 puntos para revisar un albarán antes de aprobar el pago de la factura. Evita pagar errores y disputas con proveedores. Descargable gratis en PDF.