11. Integraciones

Conectores robustos con colas, idempotencia y monitorización.

RobustezColas

CalidadIdempotencia

OperativaMonitor

Visión del módulo

Conectores externos: AEAT, TGSS, bancos y ERPs. Deben ser robustos (colas, reintentos, idempotencia) y monitorizables.

Objetivos

Automatizar entrada de datos (facturas, bancos) y salida (presentaciones).
Evitar caídas por picos: colas y reintentos controlados.
Aportar visibilidad: monitor, logs y trazas por cliente.

Alcance

Conectores por proveedor (banco, ERP) con adaptadores.
Webhooks para recibir eventos externos.
Colas de importación/procesamiento.
Monitor de integraciones (errores/reintentos).

Personas y roles

Rol	Necesidad / uso principal
Admin	Configurar claves, scopes, rotación y monitorizar fallos.
Gestor	Ver estado y reintentar sin llamar a IT.
Sistema externo	API estable con idempotencia y rate limits.

Diseño funcional

Flujos principales

Importación bancaria programada

Diaria.

Scheduler encola job por cuenta bancaria.
Conector descarga movimientos y guarda raw.
Proceso normaliza y deduplica.
Se lanza reconciliación asistida y se generan tareas si hay excepciones.

Salida: Bancos al día y conciliación acelerada.

Webhook de documentos

ERP del cliente envía facturas/abonos.

Webhook recibe payload, valida firma y idempotencia.
Guarda documento y encola OCR/clasificación.
Vincula a checklist/periodo y notifica al gestor.

Salida: Entrada automática de documentos con trazabilidad.

Pantallas (UI)

Panel integraciones
Logs y reintentos
Correlación por cliente/periodo

Diseño técnico

Entidades y modelo de datos (mínimo)

Entidad	Campos principales / notas
Integration	id, provider, credentials_ref, scopes, status, last_ok_at
WebhookEvent	id, provider, idempotency_key, payload_ref, processed_at, status
ConnectorLog	id, integration_id, level, message, correlation_id, created_at

Permisos y seguridad (RBAC)

Solo admin gestiona credenciales; gestor solo ve estado y reintenta jobs permitidos.

Validaciones y reglas

Firmas de webhook, rate limiting, allowlist IP opcional.
Idempotencia por evento y por presentación.

APIs sugeridas (API-first)

GET /api/v1/integrations POST /api/v1/integrations PATCH /api/v1/integrations/{id} POST /api/v1/webhooks/{provider} # entrada eventos GET /api/v1/integrations/logs?integration_id=... POST /api/v1/integrations/jobs/retry/{id}

Eventos y auditoría

webhook.received
integration.failed
integration.recovered

Impacto de negocio

Beneficio para la gestoría

Menos tareas manuales; entradas automáticas y consistentes; menos soporte.

Beneficio para el cliente

Menos fricción en entrega de información; mayor puntualidad.

Riesgos / puntos críticos

Sin monitor y reintentos, integraciones se vuelven un infierno operativo.

11. 集成

具有队列、幂等性和监控的稳健连接器。

稳健性队列

质量幂等性

运营监控

模块愿景

外部连接器：AEAT、TGSS、银行和ERP。必须稳健（队列、重试、幂等性）且可监控。

目标

自动化数据输入（发票、银行）和输出（提交）。
避免因峰值而崩溃：队列和受控重试。
提供可见性：按客户的监控、日志和跟踪。

范围

按提供商的连接器（银行、ERP）带适配器。
用于接收外部事件的Webhooks。
导入/处理队列。
集成监控（错误/重试）。

人员和角色

角色	需求 / 主要用途
管理员	配置密钥、范围、轮换和监控故障。
经理	查看状态并重试，无需致电IT。
外部系统	具有幂等性和速率限制的稳定API。

功能设计

主要流程

计划银行导入

每日。

调度器按银行账户将作业加入队列。
连接器下载交易并保存原始数据。
进程标准化和去重。
启动辅助对账，如果有异常则生成任务。

输出：银行最新且对账加速。

文档Webhook

客户ERP发送发票/贷项通知单。

Webhook接收有效负载，验证签名和幂等性。
保存文档并将OCR/分类加入队列。
链接到清单/期间并通知经理。

输出：具有可追溯性的自动文档输入。

屏幕（UI）

集成面板
日志和重试
按客户/期间的相关性

技术设计

实体和数据模型（最小）

实体	主要字段 / 注释
Integration	id, provider, credentials_ref, scopes, status, last_ok_at
WebhookEvent	id, provider, idempotency_key, payload_ref, processed_at, status
ConnectorLog	id, integration_id, level, message, correlation_id, created_at

权限和安全性（RBAC）

只有管理员管理凭据；经理只能查看状态并重试允许的作业。

验证和规则

Webhook签名、速率限制、可选的IP白名单。
按事件和按提交的幂等性。

建议的API（API优先）

事件和审计

webhook.received
integration.failed
integration.recovered

业务影响

对管理办公室的好处

更少的手动任务；自动和一致的输入；更少的支持。

对客户的好处

信息交付的摩擦更少；更好的准时性。

风险 / 关键点

没有监控和重试，集成将成为运营噩梦。

11. Integrations

Robust connectors with queues, idempotency and monitoring.

RobustnessQueues

QualityIdempotency

OperationsMonitor

Module Vision

External connectors: AEAT, TGSS, banks and ERPs. Must be robust (queues, retries, idempotency) and monitorable.

Objectives

Automate data entry (invoices, banks) and output (filings).
Avoid crashes from peaks: queues and controlled retries.
Provide visibility: monitor, logs and traces per client.

Scope

Connectors per provider (bank, ERP) with adapters.
Webhooks to receive external events.
Import/processing queues.
Integration monitor (errors/retries).

People and roles

Role	Need / main use
Admin	Configure keys, scopes, rotation and monitor failures.
Manager	See status and retry without calling IT.
External system	Stable API with idempotency and rate limits.

Functional Design

Main flows

Scheduled bank import

Daily.

Scheduler queues job per bank account.
Connector downloads movements and saves raw.
Process normalizes and deduplicates.
Launches assisted reconciliation and generates tasks if exceptions.

Output: Banks up to date and accelerated reconciliation.

Document webhook

Client ERP sends invoices/credit notes.

Webhook receives payload, validates signature and idempotency.
Saves document and queues OCR/classification.
Links to checklist/period and notifies manager.

Output: Automatic document entry with traceability.

Screens (UI)

Integrations panel
Logs and retries
Correlation per client/period

Technical Design

Entities and data model (minimum)

Entity	Main fields / notes
Integration	id, provider, credentials_ref, scopes, status, last_ok_at
WebhookEvent	id, provider, idempotency_key, payload_ref, processed_at, status
ConnectorLog	id, integration_id, level, message, correlation_id, created_at

Permissions and security (RBAC)

Only admin manages credentials; manager only sees status and retries allowed jobs.

Validations and rules

Webhook signatures, rate limiting, optional IP allowlist.
Idempotency per event and per filing.

Suggested APIs (API-first)

Events and audit

webhook.received
integration.failed
integration.recovered

Business Impact

Benefit for the office

Fewer manual tasks; automatic and consistent entries; less support.

Benefit for the client

Less friction in information delivery; better punctuality.

Risks / critical points

Without monitor and retries, integrations become operational hell.