API de Facturación Electrónica

Qué tenemos hoy

Importante: generar archivos localmente no equivale a estar certificado. La aprobación sólo se confirma cuando el SII recibe y acepta los sets y las demás etapas exigidas al contribuyente.

CAF: el par privado/público y la pertenencia a TITA sí se verifican. La propiedad siiSignatureVerified permanece null porque todavía no se dispone de una llave pública oficial del SII confiable para validar FRMA/IDK 100. Nunca se informa falsamente como aprobada.

Arquitectura asíncrona y multitenant

Una sola EC2 ejecuta la API Express y cinco procesos worker independientes bajo PM2. No se usa ALB, Docker, PostgreSQL ni Redis. MongoDB conserva estado e idempotencia; SQS sólo transporta identificadores y referencias, nunca XML, CAF, PFX ni contraseñas.

Cada cola tiene su -dlq, cifrado y máximo de cinco recepciones. Todos los registros, consultas, CAF, folios, prefijos S3, API keys y URLs se acotan por tenantId. Una credencial de otro tenant obtiene 403 o 404, nunca el documento.

Compuerta SII: SII_UPLOAD_ENABLED=false impide tanto el envío como el seguimiento real. Sólo se cambia después de revisar este ambiente y contar con autorización explícita.

Flujo de una prueba de certificación

1. Validar
   Zod normaliza RUT, fechas, números y reglas condicionales.
2. Construir
   Se calculan neto, exento, IVA, descuentos, recargos y total.
3. Firmar
   CAF firma el TED y el certificado firma DTE y sobre.
4. Verificar
   Se verifican firmas y XSD antes de persistir artefactos en MongoDB.
5. Revisar
   Se inspeccionan XML, PDF y manifiestos generados.
6. Enviar
   El envío al SII es explícito; guarda Track ID y fecha del upload.

Inicio rápido

Para desarrollo local, cree su archivo privado una sola vez:

Copy-Item .env.example .env
npm ci
npm start

Invoke-WebRequest http://127.0.0.1:3000/docs
Invoke-RestMethod http://127.0.0.1:3000/health

Verificaciones seguras

npm run db:check
npm run sii:preflight
npm run sii:check-connectivity
npm run sii:full-test
npm run sii:preview-package
npm run sii:preview-simulation -- --after-package=./tmp/certification-preview-2026-08-26
npm run sii:prepare-samples -- --path=./tmp/certification-preview-2026-08-26 --simulation=./tmp/certification-simulation-preview-2026-08-26/SIM-20260826-TITA

db:check verifica MongoDB e índices. sii:preflight valida persistencia, configuración, PFX y CAF sin conectarse al SII. sii:check-connectivity solicita semilla/token, pero no envía DTE ni consume folios. Ningún comando realiza upload automáticamente.

En la EC2 se usa exclusivamente /opt/soytita-facturacion/.env con permiso 0600. El despliegue falla si ese archivo real no existe y nunca copia .env.example como configuración del servidor.

La documentación queda en GET /docs y los mismos catálogos, en formato JSON, están disponibles en GET /v1/meta.

Endpoints disponibles

Dominios: toda la API se consume exclusivamente desde https://api.soytita.cl. Los objetos privados no se exponen desde la API ni desde S3: después de comprobar tenant y propiedad, la API entrega enlaces temporales de https://documentos.soytita.cl firmados por CloudFront.

Autenticación: las rutas /v1/* requieren Authorization: Bearer <api-key> o X-API-Key. La clave se guarda sólo como hash SHA-256 en Secrets Manager y determina el tenant; no confíe en un X-Tenant-Id suministrado por el cliente.

Evidencia del upload: sets, libros y simulaciones guardan numeroEnvio con el Track ID exacto del SII, fechaEnvio en dd-mm-aaaa usando la hora de Chile, la marca ISO uploadedAt y la respuesta XML original.

Contrato JSON para generar un DTE

Ejemplo para POST /v1/dte/factura. La ruta fija automáticamente tipoDte: 33. Todas las operaciones que generan, importan, envían o producen acuses requieren el encabezado Idempotency-Key.

Idempotency-Key: factura-cliente-20260826-0001

{
  "folio": 1,
  "invoice": {
    "fechaEmision": "2026-08-26",
    "formaPago": 2,
    "receptor": {
      "rut": "<RUT_REAL_CLIENTE>",
      "razonSocial": "<RAZON_SOCIAL_REAL>",
      "giro": "<GIRO_REAL>",
      "direccion": "<DIRECCION_REAL>",
      "comuna": "<COMUNA_REAL>",
      "ciudad": "<CIUDAD_REAL>"
    },
    "items": [
      {
        "nombre": "SERVICIO DE PRUEBA",
        "cantidad": 1,
        "precioUnitario": 10000,
        "exento": false
      }
    ],
    "descuentosRecargosGlobales": [],
    "referencias": []
  }
}

Campos adicionales para Guía de Despacho 52

"invoice": {
  "tipoDte": 52,
  "indicadorTraslado": 1,
  "tipoDespacho": 2,
  "origen": {
    "direccion": "13 NORTE 853 871, DEPTO. 803",
    "comuna": "VIÑA DEL MAR"
  },
  "items": [{
    "nombre": "EQUIPO", "cantidad": 1,
    "unidadMedida": "UN", "precioUnitario": 10000
  }],
  "transporte": {
    "patente": "ABCD12",
    "rutTransportista": "<RUT_VALIDO>",
    "chofer": { "rut": "<RUT_VALIDO>", "nombre": "NOMBRE COMPLETO" },
    "destino": { "direccion": "DESTINO REAL", "comuna": "COMUNA" },
    "fechaSalida": "2026-08-26",
    "horaSalida": "15:30:00",
    "fechaLlegada": "2026-08-26"
  }
}

Reglas que Zod aplica antes de generar

• Objetos estrictos: los campos desconocidos se rechazan.
• RUT con dígito verificador válido y formato normalizado.
• Fechas reales en formato YYYY-MM-DD.
• Folios enteros positivos y tipos DTE limitados a 33|34|52|56|61.
• La Guía 52 exige traslado, cantidad/unidad, vehículo, transportista, chofer, destino, salida y llegada estimada; el set asignado a TITA continúa usando 33/34/56/61.
• Ítems con montoItem o con cantidad + precioUnitario.
• No permite informar simultáneamente descuento porcentual y descuento en monto; lo mismo para recargos.
• Todos los ítems de un DTE 34 deben tener exento: true.
• Las notas 56 y 61 deben incluir al menos una referencia.
• El set exige exactamente sus ocho folios; rechaza casos ajenos, faltantes y folios repetidos por tipo DTE.
• Cada factura 33/34 del set usa un receptor distinto; las notas deben conservar el RUT del documento referenciado.
• Decisiones comerciales y recibos rechazan identificadores DTE repetidos.

Contratos del set y libros

Generar set asignado

POST /v1/certification/generate-set
Idempotency-Key: set-basico-5037509-v1

{
  "setName": "setBasico",
  "issueDate": "2026-08-26",
  "receiver": { "...receptor real caso 5037509-1..." },
  "folios": {
    "5037509-1": 1, "5037509-2": 2,
    "5037509-3": 3, "5037509-4": 4,
    "5037509-5": 1, "5037509-6": 2,
    "5037509-7": 3, "5037509-8": 1
  },
  "caseOverrides": {
    "5037509-2": { "receptor": { "...cliente real distinto..." } },
    "5037509-3": { "receptor": { "...cliente real distinto..." } },
    "5037509-4": { "receptor": { "...cliente real distinto..." } }
  }
}

Los objetos abreviados con puntos deben reemplazarse por el contrato completo de receptor; no son JSON ejecutable. Los importes, ítems y referencias del set ya están normalizados desde los archivos asignados por el SII.

Generar libros IECV

POST /v1/certification/generate-books
Idempotency-Key: libros-202608-v1

{
  "salesSetAttentionNumber": 5037509,
  "purchaseIssueDate": "2026-08-26",
  "purchaseSupplier": {
    "rut": "<RUT_REAL_PROVEEDOR>",
    "razonSocial": "<RAZON_SOCIAL_REAL>"
  }
}

Generar simulación

POST /v1/certification/generate-simulation recibe un simulationId, una lista de tipos requeridos y entre 10 y 100 objetos con el mismo contrato de generación DTE. Zod exige folios únicos por tipo, presencia de todos los tipos requeridos y prohíbe referencias SET/CASO.

npm run sii:preview-simulation -- --date=2026-08-26 --id=SIM-20260826-TITA --after-package=./tmp/certification-preview-2026-08-26

El comando produce una plantilla técnica: antes del envío, confirme que clientes, conceptos y montos correspondan a operaciones representativas. El preview no reserva folios ni realiza upload.

Mapeo de datos: API → XML SII

El catálogo completo también es consultable en GET /v1/meta/data-map.

Set de certificación, libros e intercambio

Códigos originales y estados normalizados del SII

La API conserva siempre originalStatus, glosa y XML exacto, y agrega un estado normalizado para automatización. El catálogo JSON está en GET /v1/meta/sii-codes.

Las respuestas SOAP/upload se guardan sin normalizar junto a SHA-256 e historial. Después de firmar un XML nunca se vuelve a formatear ni modificar.

Contrato y catálogo de errores

Toda ruta devuelve el mismo formato. details contiene los problemas de Zod y requestId permite ubicar el evento en los logs.

{
  "code": "VALIDATION_ERROR",
  "type": "REQUEST_VALIDATION",
  "message": "Los datos enviados no cumplen el contrato de la API",
  "retryable": false,
  "action": "Corrija los campos informados en details y vuelva a enviar la solicitud.",
  "details": [
    { "field": "invoice.receptor.rut", "rule": "custom", "message": "El RUT y su dígito verificador no son válidos" }
  ],
  "requestId": "1df08b85-39cc-45a5-9f91-d13939a64ed9"
}

Tipos de error

REQUEST_VALIDATION y CONFIGURATION se corrigen antes de ejecutar; BUSINESS_RULE, CERTIFICATION_RULE, CAF y CONFLICT protegen las reglas tributarias y la unicidad; DATABASE clasifica fallas de persistencia; CERTIFICATE, XML_VALIDATION y SIGNATURE impiden producir artefactos no verificables; SII_AUTHENTICATION, SII_COMMUNICATION y SII_REJECTION representan respuestas o incertidumbre externa. INTERNAL nunca expone detalles sensibles.

Etapas externas restantes

La implementación local está preparada, pero faltan cinco etapas que requieren envío o aprobación del SII. El registro final como emisor ocurre después de completarlas.

1. Enviar y obtener aceptación sin rechazos ni reparos de los sets 5037509/5037512 y sus libros 5037510/5037511.
2. Enviar y aprobar una simulación de 10 a 100 DTE representativos. Consulte cada TrackID hasta estado terminal y revise GET /v1/certification/reconciliation.
3. Ejecutar y aprobar el intercambio con los XML asignados por el SII; antes se debe comprobar la recepción real de dte@soytita.cl en S3 y el canal de respuesta.
4. Ejecute npm run sii:prepare-samples. El preparador incluye todos los PDF de 5037509/5037512, una muestra por tipo de simulación, cedibles 33/34, una página por PDF, máximo 500 KB y lotes locales de hasta 20; la carga al portal es manual.
5. Complete los controles organizacionales y presente la declaración de cumplimiento. No declare mientras existan respaldos, responsables o aprobaciones pendientes.

En todos los envíos la igualdad esperada es INFORMADOS = ACEPTADOS + RECHAZADOS + REPAROS. Producción debe permanecer deshabilitada hasta que el SII registre formalmente el RUT como emisor electrónico.

El preview verificado contiene 29 muestras: 23 provenientes de los dos sets asignados y 6 seleccionadas de la simulación (tributarias 33/34/56/61 más cedibles 33/34). Mientras use la plantilla técnica queda marcado TECHNICAL_PREVIEW_NOT_FOR_UPLOAD.

Respaldo y restauración MongoDB

Detenga la API antes de respaldar. mongodump --archive --gzip se cifra directamente con AES-256-GCM y una clave derivada con scrypt. El manifiesto conserva hashes SHA-256 y conteos, sin URI ni credenciales.

# Cargar SII_BACKUP_PASSPHRASE sin escribirla en el historial
$secure = Read-Host 'Frase de respaldo' -AsSecureString
$env:SII_BACKUP_PASSPHRASE = [Net.NetworkCredential]::new('', $secure).Password

npm run db:backup -- --confirm-api-stopped
npm run db:backup:verify -- --backup=.\backups\<archivo>.archive.gz.enc
npm run db:backup:test-restore -- --backup=.\backups\<archivo>.archive.gz.enc

La verificación autentica el archivo antes de entregarlo a mongorestore y ejecuta un dryRun. La prueba real usa únicamente colecciones con prefijo aleatorio __sii_restore_test_*__, compara sus conteos y las elimina al finalizar. El procedimiento completo está en BACKUP_RUNBOOK.md.

El 26-08-2026 se aprobó una ejecución técnica real: ocho colecciones restauradas con conteos idénticos, dryRun correcto y cero colecciones temporales remanentes. Consulte BACKUP_VALIDATION_2026-08-26.md.

El respaldo local no completa por sí solo la declaración: respaldo y manifiesto deben copiarse fuera del host, la contraseña debe custodiarse por separado y el ejercicio de restauración debe quedar registrado.

Archivos y variables requeridos

Archivo real de la EC2

NODE_ENV=production
HOST=127.0.0.1
PORT=3200
SII_ENVIRONMENT=certification
SII_PRODUCTION_ENABLED=false
SII_UPLOAD_ENABLED=false
ASYNC_JOBS_ENABLED=true
API_AUTH_REQUIRED=true
API_KEY_SECRET_ARN=arn:aws:secretsmanager:...
PUBLIC_API_BASE_URL=https://api.soytita.cl
AWS_REGION=us-east-1
DTE_ARTIFACT_BUCKET=soytita-dte-artifacts-...
DTE_ARTIFACT_KMS_KEY_ARN=arn:aws:kms:...
TENANT_CERTIFICATE_SECRET_ARN=arn:aws:secretsmanager:...
TENANT_SIGNER_RUT=<RUT_FIRMANTE>
SQS_DTE_GENERATE_URL=https://sqs.../tita-dte-generate
SQS_DTE_SEND_SII_URL=https://sqs.../tita-dte-send-sii
SQS_DTE_STATUS_URL=https://sqs.../tita-dte-status
SQS_DTE_PDF_URL=https://sqs.../tita-dte-pdf
SQS_DTE_EMAIL_INBOUND_URL=https://sqs.../tita-dte-email-inbound
CLOUDFRONT_DOMAIN=documentos.soytita.cl
CLOUDFRONT_KEY_PAIR_ID=<PUBLIC_KEY_ID>
CLOUDFRONT_PRIVATE_KEY_SECRET_ARN=arn:aws:secretsmanager:...
MONGODB_URI=<URI_PRIVADA>
MONGODB_DATABASE=SOYTITA

Las variables SII_TEST_*_PATH pertenecen sólo a herramientas locales de certificación y carga inicial. En ejecución asíncrona, el PFX se obtiene desde Secrets Manager y los CAF desde el bucket S3 privado por referencia/versionId.

No subir secretos: CAF, PFX/P12, contraseña, tokens y datos privados deben permanecer fuera de Git. La API no acepta el PFX ni su contraseña en el cuerpo HTTP.

Operación AWS: la EC2 usa el rol runtime SOYTITA-Facturador-EC2 y asume SOYTITA-Infrastructure-Deployment sólo para cambios de infraestructura. No se guardan access keys estáticas en ~/.aws/credentials ni en el .env del servidor.

La API escucha sólo en 127.0.0.1 por defecto. No configure HOST=0.0.0.0 sin autenticación, HTTPS y controles de red.

Estado de datos para TITA

• Migración TypeScript completa: 179 fuentes .ts, cero fuentes .js en aplicación, scripts y tests; compilación y ejecución de dist/server.js comprobadas.
• PFX y contraseña: configurados, llave coherente y vigencia comprobada.
• RutEnvia confirmado: 15.805.965-7.
• CAF 33, 34, 56 y 61: configurados, emisor correcto y folios 1–50.
• CAF 52: no configurado; sólo se necesita si se decide probar Guía de Despacho.
• TED/CAF preservan ISO-8859-1 y el PDF417 usa compactación byte, nivel de corrección 5, proporción 3:1, zona muda mínima de 0,25 pulgadas y dimensiones físicas SII.
• Semilla/token del ambiente de certificación: comprobados correctamente.
• Confirmados en el portal SII: FchResol=2026-08-26, NroResol=0, Unidad VIÑA DEL MAR, actividad 620900, software SOYTITA y Mail Contacto Empresas dte@soytita.cl.
• Datos de contraparte completos: cuatro receptores para 5037509; DATCAPITAL, RUTTY MUÑOZ y HAPPY ME reutilizados en 5037512; DATCAPITAL como proveedor para 5037511.
• El MX de soytita.cl apunta a SES entrante en us-east-1; la entrega SES→S3→SQS usa la cola final tita-dte-email-inbound; el worker está desplegado y el procesamiento XML→MongoDB/S3→PDF está cubierto por integración. Falta la última comprobación operativa con un nuevo correo XML recibido desde fuera de AWS.
• Validación EC2 del 26-08-2026: factura 33 DATCAPITAL, folio 2, terminó READY_TO_SEND y PDF READY. XML, PDF tributario y cedible respondieron 200 mediante documentos.soytita.cl; el acceso sin firma fue rechazado con 403. No se generó TrackID y la cola de envío SII quedó vacía.

No se usa Docker, PostgreSQL, Redis ni SimpleAPI. MongoDB conserva perfiles, idempotencia, folios, manifiestos y respuestas SII. En la EC2, XML/PDF/CAF se guardan cifrados en S3 y el PFX/contraseña en Secrets Manager; las copias locales son sólo material de bootstrap y revisión, siempre fuera de Git.

Fuentes oficiales SII usadas

• Proceso de certificación
• Formato DTE vigente, versión 2.5
• Resolución Exenta SII N° 154/2025 sobre traslado de bienes
• Instructivo técnico de emisión
• Instrucciones del set de pruebas
• Manual de muestras impresas
• Esquemas XML oficiales

Las copias descargadas, sus hashes y la fecha de descarga están en docs/sii/manifest.json y docs/sii/FUENTES.md.