# 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`](../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.