# Matriz de cumplimiento del objetivo SUNAT

Revisión técnica: 10-09-2026. Esta matriz relaciona los 64 puntos del objetivo original con evidencia verificable del repositorio. No reemplaza la validación tributaria ni administrativa que debe realizar cada empresa antes de activar SUNAT Producción.

## Evidencia ejecutada

- `npm test`: 70 pruebas aprobadas, 0 fallidas.
- `npm run sunat:test:mock`: factura, boleta y Resumen Diario completos; XML, firma, XSD, ZIP, CDR y hashes generados.
- `npm audit --omit=dev`: 0 vulnerabilidades conocidas.
- SUNAT BETA: factura con detracción `F001-3`, nota de crédito `FC01-1` y nota de débito `FD01-1`, aceptadas con CDR código `0` el 10-09-2026.
- Historial BETA adicional: factura, boleta, notas de factura/boleta, Resumen Diario y Comunicación de Baja conservados bajo `test/.generated/beta*`.
- Despliegue BETA: `https://facturador-peru.bheed.net`, TLS, Nginx con rate limit y PM2 sobre Node.js 22.

## Requisitos 1–16: base técnica y UBL

| Nº | Estado | Evidencia |
|---:|---|---|
| 1 | Cumplido | Node.js ESM, Express, Mongoose, Zod, Decimal, xmlbuilder2, xml-crypto, forge, ZIP y fetch declarados en `package.json`. |
| 2 | Cumplido | Fuentes oficiales DOC-01 a DOC-20 inventariadas en `docs/FUENTES.md`; XSD/XSL/WSDL/reglas versionados en `resources/sunat`. |
| 3 | Cumplido | Ambientes `mock`, `beta` y `production`, con `tributaryValidity` aislado por ambiente. |
| 4 | Cumplido | Transporte BETA real, ejecución explícita y sin carga; CDR BETA conservadas. |
| 5 | Cumplido | Endpoint y credenciales por tenant, bloqueo `SUNAT_ALLOW_REAL_EMISSION`, prohibición de MODDATOS/RUC demo en producción. |
| 6 | Cumplido | Requisitos administrativos y técnicos separados en `docs/PRODUCCION.md`. |
| 7 | Cumplido | Capas independientes de dominio, catálogos, UBL, firma, XSD, ZIP, SOAP, CDR, persistencia, servicios y rutas. |
| 8 | Cumplido | El body se convierte primero a esquema Zod y modelo canónico; ningún builder consume `req.body`. |
| 9 | Cumplido | Cálculos con `decimal.js` y redondeo explícito; pruebas gravada, mixta, gratuita, descuentos y monedas. |
| 10 | Cumplido | Invoice/CreditNote/DebitNote UBL 2.1 con namespaces centralizados y XSD oficial. |
| 11 | Cumplido | Factura PEN/USD; gravada, exonerada, inafecta, gratuita, descuentos, cargos, crédito, vencimiento y detracción general. Para detracción USD se exige tipo de cambio venta SBS y el monto se expresa en PEN. |
| 12 | Cumplido | Correlativo por tenant/tipo/serie con operación atómica e índice único; prueba concurrente. |
| 13 | Cumplido | `buildSunatFilename` y ZIP/XML con basename oficial. |
| 14 | Cumplido | XMLDSig RSA-SHA256, certificado X.509, verificación local y detección de XML alterado. |
| 15 | Cumplido | PFX/P12/PEM/CRT, vigencias, correspondencia de clave y validación de RUC en producción. |
| 16 | Cumplido | ZIP en memoria, un único XML y prueba de integridad de bytes. |

## Requisitos 17–32: transporte, estados y persistencia

| Nº | Estado | Evidencia |
|---:|---|---|
| 17 | Cumplido | SOAP/WS-Security explícito con `RUC + usuario SOL`; secretos excluidos de metadata y logs. |
| 18 | Cumplido | `sendBill` persiste artefactos, transmisión, CDR y estado normalizado. |
| 19 | Cumplido | Parser CDR distingue aceptado, observado y rechazado; HTTP 200 no define aceptación. |
| 20 | Cumplido | Boletas y notas de boleta quedan `PENDING_SUMMARY` y usan Resumen Diario. |
| 21 | Cumplido | `sendSummary` guarda ticket y permite polling acotado o recuperación durable. |
| 22 | Cumplido | `getStatus` mapea códigos `0`, `98`, `99` y desconocidos. |
| 23 | Cumplido | Nota de crédito 07, referencia obligatoria y catálogo de motivos centralizado. |
| 24 | Cumplido | Nota de débito 08, referencia obligatoria y catálogo de motivos centralizado. |
| 25 | Cumplido | Comunicación de Baja RA con firma, ZIP, ticket, CDR y restricciones por tipo documental. |
| 26 | Cumplido | Consulta `getStatusCdr` separada para producción y endpoint de reconciliación. |
| 27 | Cumplido | `Idempotency-Key`, hash canónico del body e índices únicos por tenant. |
| 28 | Cumplido | Máquina de estados e historial durable sin borrar transiciones. |
| 29 | Cumplido conservador | No reenvía rechazos ni resultados ambiguos; primero reconcilia. Tickets RC/RA usan backoff y lease durable. |
| 30 | Cumplido | Colecciones de documentos, secuencias, transmisiones, resúmenes, certificados, tenants, borradores, accesos y API keys. |
| 31 | Cumplido | Toda lectura/escritura se filtra por tenant; configuración fiscal y series pertenecen al tenant. |
| 32 | Cumplido | `SecretProvider` local/AWS; producción exige referencias seguras y no guarda claves privadas/Clave SOL en documentos. |

## Requisitos 33–48: observabilidad, API y pruebas

| Nº | Estado | Evidencia |
|---:|---|---|
| 33 | Cumplido | Logs JSON sanitizados, RUC enmascarado y errores internos HTTP ocultos. |
| 34 | Cumplido | Auditoría de creación, emisión, generación, firma, envío, CDR, intentos, hashes e historial. |
| 35 | Cumplido | Catálogos centralizados para documento, identidad, moneda, unidad, IGV, notas y detracciones. |
| 36 | Cumplido | `SUNAT_RULESET` registra versión, fecha, URL y SHA-256 de reglas 30.07.2026. |
| 37 | Cumplido | XSD oficiales versionados; validación final después de firma, decisión explicada en arquitectura. |
| 38 | Cumplido | Namespaces centralizados en `src/ubl/namespaces.js`. |
| 39 | Cumplido | Zod y reglas de negocio devuelven `field`, `code` y `message`; certificado/firma/XSD se verifican antes de transmitir. |
| 40 | Cumplido | Endpoints JSON para factura, boleta, notas, consulta, XML, CDR, PDF, envío y reconciliación. |
| 41 | Cumplido | `createSunatService({ tenantId })` ofrece API de aplicación desacoplada de HTTP/SOAP. |
| 42 | Cumplido | Orquestación completa en `IssueDocumentService` con persistencia por etapa. |
| 43 | Cumplido | Jerarquía de errores SUNAT tipada y respuesta HTTP normalizada. |
| 44 | Cumplido | SOAP Fault se parsea como `SUNAT_SOAP_FAULT` sin exponer credenciales. |
| 45 | Cumplido | PDF usa el mismo dominio canónico, QR con DigestValue y marca MOCK/BETA. |
| 46 | Cumplido | Portal por token aleatorio hasheado, ligado a tenant/documento/receptor, revocable y con expiración. |
| 47 | Cumplido | Pruebas unitarias de generación, impuestos, firma, ZIP, CDR, notas, PDF y detracción. |
| 48 | Cumplido | Prueba de concurrencia demuestra correlativos únicos. |

## Requisitos 49–64: integración, operación y entrega

| Nº | Estado | Evidencia |
|---:|---|---|
| 49 | Cumplido | `npm run sunat:test:mock` ejecuta el pipeline sin secretos ni red. |
| 50 | Cumplido | Scripts BETA requieren `SUNAT_RUN_BETA_TESTS=true` y no forman parte de CI ordinario. |
| 51 | Cumplido | Tests ordinarios no pueden emitir en producción; se requiere opt-in explícito. |
| 52 | Cumplido | Fixture semántico equivalente a la guía oficial de factura UBL 2.1. |
| 53 | Cumplido | `ArtifactStorage` local/S3 conserva dominio, XML, ZIP y CDR. |
| 54 | Cumplido | SHA-256 de XML, ZIP y CDR persistidos. |
| 55 | Cumplido | Fechas tributarias usan `America/Lima`; pruebas controlan plazos. |
| 56 | Cumplido | Métricas Prometheus de generación, envío, aceptación, rechazo, transporte, latencia y procesamiento. |
| 57 | Cumplido | Health valida configuración, certificado y generación UBL real en memoria sin emitir. |
| 58 | Cumplido | Consulta autenticada de documento expone estado, CDR normalizada, intentos, auditoría, historial y artefactos suficientes para backoffice. |
| 59 | Cumplido para el alcance definido | Fases 1–5 y PDF/portal/detracción general de fase 6 implementados. Percepciones y casos SPOT 1002/1004 quedan como extensiones no bloqueantes indicadas por el propio objetivo. |
| 60 | Cumplido | JSON→dominio→Decimal→UBL→firma→XSD→ZIP→SOAP→CDR demostrado en MOCK y BETA. |
| 61 | Cumplido | `README.md` y `docs/peru-sunat.md` cubren operación, ambientes, secretos, pruebas y producción. |
| 62 | Cumplido | Motor directo no importa PSE/OSE; secretos, floats, endpoints del cliente, duplicados y pruebas productivas están bloqueados. |
| 63 | Cumplido | API pública recibe JSON y el SDK expone servicios por tenant; dependencia tributaria directa: SUNAT. |
| 64 | Cumplido | Repositorio, fuentes, incompatibilidades, arquitectura, MOCK, factura y transporte BETA inspeccionados e implementados. |

## Límite del cierre técnico

El código está preparado para producción, pero activar efectos tributarios depende de completar el checklist externo por cada tenant: RUC/condición SUNAT, alta como emisor SEE, Clave SOL, certificado real, series autorizadas, S3, Secrets Manager, respaldos, alertas y aprobación contable. Mientras esas condiciones no existan, el despliegue debe permanecer en `SUNAT_ENV=beta` y `SUNAT_ALLOW_REAL_EMISSION=false`.