Escribir un conector nuevo

Un conector es un módulo en core/aiuda_core/connectors/ que cumple tres reglas:

El contrato

1. Lee y normaliza. Expone funciones que devuelven datos en los tipos del core (facturas con folio, cliente, monto, fechas). El agente nunca ve el formato crudo del sistema externo.
2. Declara procedencia. Todo lo que importa lleva source="<tu-conector>" y el estado de verificación correcto: verificada solo si viene de un sistema de registro, sin_verificar si es un archivo del usuario.
3. Devuelve lo que registra (write-back). Si aiuda confirma un pago o registra una gestión, el conector lo escribe de regreso al sistema fuente vía el patrón outbox (OutboxEntry): encolado transaccional, reintentos, sin verdad duplicada.

Esqueleto

core/aiuda_core/connectors/mi_sistema.py

class MiSistemaConnector:
    def __init__(self, credenciales): ...

    def fetch_open_invoices(self) -> list[...]:
        """Lee y normaliza. source='mi_sistema', verified según corresponda."""

    def write_back(self, action: str, payload: dict) -> None:
        """Procesa una OutboxEntry: registra en el sistema fuente."""

Buenos ejemplos para copiar: evolution.py (canal con webhook + idempotencia), odoo.py (lectura + write-back), smart_import.py (archivo del usuario + IA).

Antes de abrir el PR

• Tests con el sistema externo mockeado (mira core/tests/test_evolution.py).
• Sin credenciales en código: configuración por tenant o .env.
• Si tu conector trae datos: ¿de dónde salen y cómo se verifica? Si la respuesta no es clara, el diseño no está listo.

¿Qué sigue?

• Arquitectura
• Contribuir