balam/planeacion/Hallazgos-y-decisiones-Etapa0.md

Etapa 0 — Hallazgos y decisiones de arquitectura

Proyecto: Plataforma de Automatización Financiera · Balam Estado: borrador para cerrar con la validación del prototipo Última actualización: 2026-07-15

1. Resultado del Discovery

El flujo operativo confirmado es:

Jira ITSM → cotización en BIND → prefactura → validación humana → CFDI → envío según reglas del cliente → cobranza

Reglas de negocio principales:

• Toda factura debe partir de una cotización en BIND.
• La prefactura es obligatoria antes de timbrar.
• PPD es el método predeterminado; PUE requiere una decisión consciente.
• IVA esperado: 16 % en operación nacional y 0 % para operación extranjera sin efectos fiscales, sujeto a las excepciones fiscales que confirme Balam.
• El alta de un cliente nuevo es un flujo separado y requiere definición final de Arturo.
• Los recordatorios se desean para todos los clientes; los correos automáticos externos permanecen fuera del MVP original (Anexo B) hasta confirmar alcance.
• La cobranza se controla por factura y folio. Debe tolerar diferencias por comisiones/fees conforme a la regla que confirme Arturo.

2. Resultado de la validación de BIND

La prueba del 6-jul realizó 117 solicitudes exclusivamente GET contra la cuenta real, sin persistir datos de Balam.

Confirmado:

• Saldo por factura viable con Total - Payments - CreditNotes.
• Cotizaciones, prefacturas, facturas, clientes, impuestos, PPD/PUE, vencimientos y PDF son consultables.
• Aging y alertas internas son viables sin consultar pagos individuales.
• El volumen proyectado de sincronización consume aproximadamente 5 % del límite de 20,000 solicitudes diarias.

Restricciones:

• No se encontró endpoint de pagos individuales ni complementos de pago (REP).
• BIND no expone el vínculo cotización→factura; la plataforma deberá conservarlo.
• Algunos campos clave solo aparecen en el detalle de cada factura.
• No hay webhooks confirmados; el diseño base usará sincronización incremental por polling.
• El token está acotado a una sola empresa.
• La cuenta actual es de producción y puede tener privilegios elevados; no se autoriza escritura todavía.

Detalle técnico: ../bind-api-sandbox/VALIDACION-API.md.

3. Decisiones de arquitectura

ADR-001 · Lectura primero y escritura controlada

Decisión: operar inicialmente en modo solo lectura. Toda escritura futura requiere autorización expresa, dry-run, confirmación humana y feature flag desactivado por defecto.

Motivo: Balam no cuenta con sandbox y una operación incorrecta puede tener efecto fiscal.

ADR-002 · Sincronización incremental

Decisión: persistir en PostgreSQL el último punto de sincronización y consultar únicamente registros nuevos o modificados. Paginar siempre con lotes de hasta 100.

Motivo: BIND no ofrece conteos ni nextLink; PPD/PUE y días de crédito requieren consultas de detalle.

ADR-003 · Trazabilidad propia

Decisión: almacenar las relaciones ticket Jira → cotización BIND → factura BIND en la base de datos de la plataforma.

Motivo: la API de BIND no expone de forma confiable el vínculo cotización→factura.

ADR-004 · Detección de pagos

Decisión: para el MVP, detectar pagos mediante cambios de estatus y saldo residual. Registrar la fecha de detección, no presentarla como fecha valor.

Motivo: no se encontró un recurso de pagos/REP. La fecha contable real requerirá información adicional o una ampliación.

ADR-005 · Separación por empresa

Decisión: el MVP opera únicamente con la empresa Balam asociada al token. Multiempresa queda fuera del alcance.

Motivo: cada empresa requiere su propia cuenta/token de BIND.

ADR-006 · Integración Jira→BIND pendiente de alcance

Decisión: diseñar el modelo para conservar el identificador del ticket, pero no comprometer todavía la automatización que crea cotizaciones desde Jira.

Motivo: el Discovery confirmó a Jira como entrada del proceso, pero la integración automática no estaba incluida explícitamente en el MVP. Antes de desarrollarla se requiere:

• Confirmación de alcance.
• Cuenta técnica y acceso API/OAuth a Jira.
• Webhook o regla de automatización.
• Mapeo de campos y estatus disparador.
• Acceso controlado de escritura a BIND.

4. Preguntas que deben cerrarse

Con Arturo / CEO — sesión del 22-jul

1. Flujo definitivo de alta de cliente nuevo.
2. Tratamiento en BIND de diferencias por comisión/fee.
3. Particularidades de envío por cliente.
4. Estatus de Jira que autoriza crear una cotización.
5. Campos obligatorios y manejo de tickets incompletos.

Con Pedro / Noé

1. Endpoint de pagos individuales o REP.
2. Mapeo interno de CFDIUse a clave SAT.
3. Formato de respuesta de /{id}/xml.
4. Disponibilidad de webhooks en BIND.
5. Token utilizado por Power BI y decisión sobre usuario de solo lectura.
6. Permisos e identidad técnica para Jira, si se aprueba la integración.

5. Dependencias de infraestructura

Dependencia	Estado al 15-jul	Impacto
Token BIND	Entregado; uso solo lectura	Desbloquea consultas y cliente BIND
Repositorio privado GitHub	Autorizado por Noé; invitación pendiente	Necesario para publicar backend/frontend
Azure	Programado para semana del 21-jul	No bloquea desarrollo local
CI/CD y secretos	Actividad separada para 24-jul	Depende de repo y Azure
Jira técnico	No solicitado todavía	Solo bloquea integración automática Jira→BIND

6. Criterio de cierre de Etapa 0

La Etapa 0 se cierra cuando:

• Balam valida el prototipo o registra ajustes.
• Se incorporan las decisiones de la sesión del 22-jul.
• Se valida el prototipo en la sesión del 23-jul.
• Este documento se actualiza con las respuestas finales.
• Se emite un plan refinado con alcance explícito para Jira, recordatorios externos y escritura en BIND.