@devly-cl/sii-client 0.4.4 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +118 -26
- package/dist/application/invoice-queries.d.ts +17 -0
- package/dist/application/invoice-queries.js +51 -0
- package/dist/application/issuance.d.ts +40 -0
- package/dist/application/issuance.js +79 -0
- package/dist/contracts.d.ts +66 -0
- package/dist/contracts.js +2 -0
- package/dist/domain/document.d.ts +47 -0
- package/dist/domain/document.js +38 -0
- package/dist/domain/invoice-xml.d.ts +58 -11
- package/dist/domain/invoice-xml.js +0 -138
- package/dist/domain/invoicing.d.ts +52 -0
- package/dist/domain/invoicing.js +157 -0
- package/dist/domain/issued-invoice.d.ts +16 -9
- package/dist/domain/issued-invoice.js +4 -43
- package/dist/domain/received-invoice.d.ts +11 -7
- package/dist/domain/received-invoice.js +0 -10
- package/dist/domain/sii-error.d.ts +3 -3
- package/dist/domain/sii-error.js +10 -4
- package/dist/index.d.ts +13 -3
- package/dist/index.js +12 -3
- package/dist/infrastructure/dte-xml.d.ts +11 -0
- package/dist/infrastructure/dte-xml.js +173 -0
- package/dist/infrastructure/facturador-gateway.d.ts +28 -0
- package/dist/infrastructure/facturador-gateway.js +411 -0
- package/dist/infrastructure/facturador.d.ts +18 -0
- package/dist/infrastructure/facturador.js +231 -0
- package/dist/infrastructure/invoice-pdf.d.ts +9 -0
- package/dist/infrastructure/invoice-pdf.js +171 -0
- package/dist/infrastructure/rcv-gateway.d.ts +17 -0
- package/dist/infrastructure/rcv-gateway.js +105 -0
- package/dist/infrastructure/rcv-normalization.d.ts +6 -0
- package/dist/infrastructure/rcv-normalization.js +55 -0
- package/dist/infrastructure/sii-client.d.ts +52 -54
- package/dist/infrastructure/sii-client.js +66 -487
- package/dist/infrastructure/sii-http-session.d.ts +25 -0
- package/dist/infrastructure/sii-http-session.js +344 -0
- package/dist/sii-error.d.ts +27 -0
- package/dist/sii-error.js +86 -0
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# SII Client
|
|
2
2
|
|
|
3
|
-
`@devly-cl/sii-client` es una biblioteca TypeScript independiente de framework. Inicia sesión personal en SII, comprueba autorización sobre una empresa y consulta resúmenes del Registro de Compras y Ventas y facturas emitidas y recibidas 33/34 mediante HTTP/JSON. Credenciales por parámetros; sin variables de entorno para login.
|
|
3
|
+
`@devly-cl/sii-client` es una biblioteca TypeScript independiente de framework. Inicia sesión personal en SII, comprueba autorización sobre una empresa y consulta resúmenes del Registro de Compras y Ventas y facturas emitidas y recibidas 33/34 mediante HTTP/JSON. La ampliación de este repositorio incorpora PDF originales por streaming y preparación, firma y envío de facturas 33 y notas de crédito 61 de anulación total mediante el facturador gratuito. Credenciales por parámetros; sin variables de entorno para login o firma.
|
|
4
4
|
|
|
5
|
-
Basado en los servicios internos observados del portal. No es una API pública oficial ni una integración certificada.
|
|
5
|
+
Basado en los servicios internos observados del portal. No es una API pública oficial ni una integración certificada. La versión 0.6.0 agrega PDF por streaming y conserva emisión, XML y aliases; la publicación se verifica por separado de las pruebas fiscales reales. La prueba real del prototipo de lectura se realizó el 30-09-2026; el análisis, contrato observado y evidencia HTTP están en `docs/sii/` del repositorio, fuera del paquete npm.
|
|
6
6
|
|
|
7
7
|
## Desarrollo
|
|
8
8
|
|
|
@@ -16,6 +16,14 @@ npm pack
|
|
|
16
16
|
|
|
17
17
|
`check` verifica tipos, genera `dist`, ejecuta checks de integración HTTP simulada/autorización y facturas emitidas, y compila el ejemplo. `npm pack` vuelve a validar antes de crear el tarball. `dist` y `node_modules` no se versionan. El paquete contiene sólo `dist` y este README.
|
|
18
18
|
|
|
19
|
+
## Arquitectura y límites de lectura
|
|
20
|
+
|
|
21
|
+
`SiiClient` conserva la API pública y compone sesión/transporte, RCV y facturador. `domain` contiene modelos y políticas fiscales; `application` controla cobertura, aprobación y envío mediante puertos tipados; `infrastructure` implementa HTTP, normalización del proveedor, HTML y XML. Las políticas y casos de uso se prueban también sin servidor ni parsers externos. Los adaptadores internos no forman una API adicional del paquete.
|
|
22
|
+
|
|
23
|
+
Las lecturas JSON/XML permanecen activas hasta consumir y procesar su body. Si `dispose()` comienza durante una de estas lecturas, espera su finalización y rechaza su resultado con `CLIENT_CLOSED` antes del logout. También espera escrituras activas; la limpieza queda fuera del trabajo que espera para evitar bloqueos. Los PDF pendientes se cancelan y se espera el cierre de su origen antes del logout, incluso si el consumidor todavía no leyó el stream. Repetir el cierre mantiene un único logout.
|
|
24
|
+
|
|
25
|
+
JSON tiene un límite interno de 16 MiB medido durante la lectura, independiente de `Content-Length`. Al excederlo, cancela el stream y devuelve `SII_PROTOCOL_CHANGED` con diagnóstico `RESPONSE_TOO_LARGE`, sin reintentar ni devolver datos parciales. XML y respuestas HTTP del portal mantienen su límite de 1 MiB. Una falla del stream devuelve `SII_TRANSPORT_ERROR`; JSON malformado mantiene `SII_PROTOCOL_CHANGED`.
|
|
26
|
+
|
|
19
27
|
## Integración NestJS u otro backend
|
|
20
28
|
|
|
21
29
|
Instalar desde npm:
|
|
@@ -27,25 +35,25 @@ npm install @devly-cl/sii-client
|
|
|
27
35
|
Para probar cambios locales, crear el tarball con `npm pack` e instalarlo con `npm install <ruta-al-tarball>`. La licencia se mantiene como `UNLICENSED`.
|
|
28
36
|
|
|
29
37
|
```ts
|
|
30
|
-
import { SiiClient, type
|
|
38
|
+
import { SiiClient, type IssuedInvoicesQuery, type SiiCredentials } from '@devly-cl/sii-client';
|
|
31
39
|
|
|
32
|
-
async function
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
40
|
+
async function getAuthorizedIssuedInvoices(
|
|
41
|
+
authorizedCompanyRut: string,
|
|
42
|
+
credentials: SiiCredentials,
|
|
43
|
+
query: IssuedInvoicesQuery,
|
|
36
44
|
) {
|
|
37
45
|
// El caso de uso ya autorizó actor, tenant, empresa, recurso y sucursal.
|
|
38
|
-
const sii = new SiiClient({ empresaRut:
|
|
46
|
+
const sii = new SiiClient({ empresaRut: authorizedCompanyRut });
|
|
39
47
|
try {
|
|
40
|
-
await sii.login(
|
|
41
|
-
return await sii.
|
|
48
|
+
await sii.login(credentials);
|
|
49
|
+
return await sii.getIssuedInvoices(query);
|
|
42
50
|
} finally {
|
|
43
51
|
await sii.dispose();
|
|
44
52
|
}
|
|
45
53
|
}
|
|
46
54
|
```
|
|
47
55
|
|
|
48
|
-
`
|
|
56
|
+
`credentials` recibe `{ rut, clave }`; `query` de facturas recibe `{ periodo: 'YYYYMM', tokenRecaptcha? }`. Los resúmenes conservan `{ periodo: 'YYYYMM', operacion: 'COMPRA' | 'VENTA', estado? }`. El repositorio incluye el ejemplo compilable `examples/consulta-rcv.ts`. CommonJS también admite `const { SiiClient } = require('@devly-cl/sii-client')`; las declaraciones TypeScript se generan desde el mismo código.
|
|
49
57
|
|
|
50
58
|
No registrar un cliente autenticado como singleton NestJS. Puede inyectarse un servicio sin estado que cree y descarte una instancia por operación autorizada. La empresa debe salir de un recurso autorizado del backend, no de un RUT libre enviado por el usuario.
|
|
51
59
|
|
|
@@ -54,13 +62,45 @@ No registrar un cliente autenticado como singleton NestJS. Puede inyectarse un s
|
|
|
54
62
|
| Método | Resultado |
|
|
55
63
|
| --- | --- |
|
|
56
64
|
| `login({ rut, clave })` | Confirma identidad personal y autorización sobre la empresa fijada. Sin representación electrónica. |
|
|
57
|
-
| `
|
|
58
|
-
| `
|
|
59
|
-
| `
|
|
60
|
-
| `
|
|
61
|
-
| `
|
|
62
|
-
| `
|
|
63
|
-
| `
|
|
65
|
+
| `getAuthorizedCompanies()` | Devuelve autorizaciones del usuario en SII; el backend controla quién puede consultarlas. |
|
|
66
|
+
| `getSummary({ periodo, operacion, estado })` | Devuelve JSON del SII sin reinterpretar montos; elimina `metaData.conversationId` y normaliza el resumen vacío observado (`codRespuesta: 3`, `data: null`, sin errores) a `data: []`. |
|
|
67
|
+
| `getIssuedInvoices({ periodo, tokenRecaptcha? })` | Facturas 33/34 normalizadas y cobertura explícita del período RCV. Sin metadatos crudos ni secretos. |
|
|
68
|
+
| `getReceivedInvoices({ periodo, tokenRecaptcha? })` | Facturas 33/34 del registro de compras, con proveedor como emisor, empresa como receptor y cobertura explícita. |
|
|
69
|
+
| `getIssuedInvoiceXml({ documentType, folio })` | Bytes originales y detalle normalizado de un DTE emitido en el facturador gratuito del SII. |
|
|
70
|
+
| `getReceivedInvoiceXml({ issuerRut, documentType, folio })` | Original del DTE recibido; valida proveedor y receptor contra la empresa autorizada. |
|
|
71
|
+
| `getIssuedInvoicePdf({ documentType, folio }, { signal }?)` | PDF original emitido 33/34 como `Readable`, sin persistirlo ni acumular el documento completo. |
|
|
72
|
+
| `getReceivedInvoicePdf({ documentType, folio, issuerRut }, { signal }?)` | PDF original recibido 33/34; resuelve tipo, folio y proveedor en el historial de recibidos. |
|
|
73
|
+
| `getIssuedDocumentXml({ documentType, folio })` | Respaldo y detalle de documentos emitidos 33/34/61; conserva los métodos de XML de facturas existentes. |
|
|
74
|
+
| `prepareInvoice(input)` | Contenido fiscal revisable, huella SHA256, identificador opaco y vencimiento; todavía no firma ni envía. |
|
|
75
|
+
| `prepareCancellationCreditNote({ factura, issuedDate })` | Prepara una NC 61 contra una factura 33 resuelta en el historial; mismos receptor y montos, referencia única `CodRef=1`. |
|
|
76
|
+
| `signAndSend({ preparacionId, approvedHash, claveFirma, beforeSend })` | Firma el contenido aprobado, exige guardar XML e identidad antes del envío y devuelve `status: 'ENVIADO'` cuando observa confirmación del portal. |
|
|
77
|
+
| `dispose()` | Cancela PDF pendientes, espera su cierre y el trabajo JSON/XML/escrituras, cierra la sesión propia con `autTermino.cgi`, descarta cookies y bloquea reutilización. Esperar siempre en `finally`. |
|
|
78
|
+
|
|
79
|
+
## Nombres canónicos y migración
|
|
80
|
+
|
|
81
|
+
Los métodos, funciones y tipos públicos nuevos usan inglés. Los nombres anteriores siguen disponibles como aliases de compatibilidad marcados `@deprecated`; reemplazarlos no cambia el protocolo, la identidad del documento ni las reglas de autorización o envío.
|
|
82
|
+
|
|
83
|
+
| Nombre anterior | Nombre canónico |
|
|
84
|
+
| --- | --- |
|
|
85
|
+
| `getEmpresasAutorizadas` | `getAuthorizedCompanies` |
|
|
86
|
+
| `getResumen` | `getSummary` |
|
|
87
|
+
| `getFacturasEmitidas` | `getIssuedInvoices` |
|
|
88
|
+
| `getFacturasRecibidas` | `getReceivedInvoices` |
|
|
89
|
+
| `getXmlFacturaEmitida` | `getIssuedInvoiceXml` |
|
|
90
|
+
| `getXmlFacturaRecibida` | `getReceivedInvoiceXml` |
|
|
91
|
+
| `getXmlDocumentoEmitido` | `getIssuedDocumentXml` |
|
|
92
|
+
| `prepararFactura` | `prepareInvoice` |
|
|
93
|
+
| `prepararNotaCreditoAnulacion` | `prepareCancellationCreditNote` |
|
|
94
|
+
| `firmarYEnviar` | `signAndSend` |
|
|
95
|
+
| `validarFactura` | `validateInvoice` |
|
|
96
|
+
| `calcularTotalesFactura` | `calculateInvoiceTotals` |
|
|
97
|
+
| `hashContenido` | `hashContent` |
|
|
98
|
+
|
|
99
|
+
Los tipos siguen la misma migración: `CredencialesSii` → `SiiCredentials`, `ConsultaResumen` → `SummaryQuery`, `ConsultaFacturasEmitidas` → `IssuedInvoicesQuery`, `EntradaFactura` → `InvoiceInput`, `DocumentoPreparado` → `PreparedDocument`, `DocumentoFirmado` → `SignedDocument`, `DocumentoEnviado` → `SentDocument` y `FirmaDocumento` → `SignDocumentInput`. Los aliases anteriores mantienen la misma estructura.
|
|
100
|
+
|
|
101
|
+
Esta migración normaliza nombres del SDK. Las propiedades existentes del contrato permanecen iguales: `empresaRut`, `clave`, `periodo`, `operacion`, `estado`, `preparacionId`, `claveFirma` y `factura`; también permanecen los valores `COMPRA`, `VENTA` y `ENVIADO`. No traducir campos HTTP/JSON del SII, parámetros CGI, valores fiscales ni XML. `SiiClient`, `login`, `dispose`, `parseRut`, `parseDteXml` y `parseDteDocumentXml` conservan sus nombres.
|
|
102
|
+
|
|
103
|
+
`examples/facturacion.ts` usa `IssuanceRecord` con métodos en inglés para mostrar persistencia, aprobación y recuperación del consumidor. La [guía de migración](docs/sii/QA-API-ENGLISH.md) detalla verificaciones locales; no ejecuta login, firma ni envío reales.
|
|
64
104
|
|
|
65
105
|
Una instancia permite un único login. Cada instancia tiene su propio CookieJar. La clase no guarda la clave como propiedad ni escribe cookies en disco. JavaScript no garantiza borrado físico inmediato de strings en memoria.
|
|
66
106
|
|
|
@@ -72,7 +112,7 @@ Estados de compra: `REGISTRO`, `PENDIENTE`, `NO_INCLUIR`, `RECLAMADO`. Venta adm
|
|
|
72
112
|
|
|
73
113
|
## Facturas emitidas
|
|
74
114
|
|
|
75
|
-
`
|
|
115
|
+
`IssuedInvoicesResult` contiene `data: IssuedInvoice[]`, `complete`, `expectedCount`, `observedAt` ISO e `incompleteDocumentTypes: (33 | 34)[]`. `expectedCount` suma sólo los tipos 33/34 presentes en el resumen de ventas del período. Consulta `getDatosInicio` para obtener `limiteDtes` y pide `getDetalleVenta` sólo para tipos presentes con cantidad positiva; cero comprobado no necesita pedir un detalle inexistente.
|
|
76
116
|
|
|
77
117
|
Cada factura contiene `issuerRut`, `documentType`, `folio`, `issuedDate`, `receiverRut`, `receiverName`, `netAmount`, `exemptAmount`, `vatAmount`, `totalAmount`, `siiBranchCode` y `rcvPeriod`. Emisor fijado por instancia; `detRutDoc` es el receptor. RUT con DV validado y normalizado; folio numérico seguro convertido a string; fecha de calendario `YYYY-MM-DD`, aceptando `dd/mm/yyyy` o `YYYY-MM-DD` del proveedor, sin conversión de zona horaria. `rcvPeriod` es el período consultado y puede diferir del mes de emisión.
|
|
78
118
|
|
|
@@ -86,7 +126,7 @@ Por defecto envía el literal `t-o-k-e-n-web` usado por el servicio del portal o
|
|
|
86
126
|
|
|
87
127
|
## Facturas recibidas
|
|
88
128
|
|
|
89
|
-
`
|
|
129
|
+
`getReceivedInvoices({ periodo: '202609' })` devuelve `ReceivedInvoicesResult` con los mismos campos de cobertura que emitidas. Usa `COMPRA`, estado `REGISTRO` y `getDetalleCompra`, sólo para tipos 33/34 presentes en el resumen. No acepta, reclama ni modifica documentos. Cada `ReceivedInvoice` conserva `issuerRut` e `issuerName` del proveedor, y `receiverRut` de la empresa fijada; `receiverName` es `null` si el RCV no lo informa. Folios iguales de distintos proveedores son documentos distintos.
|
|
90
130
|
|
|
91
131
|
En compras, `detTipoDoc` puede ser `null`: se usa el tipo de la consulta que devolvió esa fila y se rechaza un tipo explícito contradictorio. `vatAmount` conserva el IVA recuperable informado por RCV, que puede diferir del IVA total del XML. No se recalcula ni se reemplaza por el impuesto del DTE. Sólo se consulta registro; pendientes, reclamados, excluidos y notas de crédito/débito quedan fuera de este listado.
|
|
92
132
|
|
|
@@ -94,18 +134,60 @@ Verificación real del SDK 0.4.0, 01-10-2026: septiembre devolvió tres facturas
|
|
|
94
134
|
|
|
95
135
|
## XML de facturas emitidas y recibidas
|
|
96
136
|
|
|
97
|
-
Después de `login`, llamar `
|
|
137
|
+
Después de `login`, llamar `getIssuedInvoiceXml({ documentType: 33, folio: folioAutorizado })`. Devuelve `{ xml: Uint8Array, encoding, detail }`; no convierte el original a UTF-8 ni reescribe firmas. `parseDteXml(bytes, { issuerRut, documentType, folio })` permite interpretar un documento ya obtenido, validando su identidad.
|
|
98
138
|
|
|
99
|
-
Para recibidas, llamar `
|
|
139
|
+
Para recibidas, llamar `getReceivedInvoiceXml({ issuerRut: proveedorRut, documentType: 33, folio })`. La empresa de la instancia sigue siendo la empresa receptora autorizada. La descarga utiliza `ORIGEN=RCP` y `RUT_EMI` del proveedor, y valida ambos participantes en el XML. `parseDteXml` también acepta `receiverRut` como validación adicional. El respaldo de recibidos está descrito en la [guía del SII](https://www.sii.cl/portales/mipyme/administracion/Guia_Respaldo_DTEs_recibidos.html); su disponibilidad depende del documento y del servicio del facturador gratuito.
|
|
100
140
|
|
|
101
141
|
`detail` incluye emisor, tipo, folio, fecha civil, receptor, neto/exento/IVA/tasa/total, líneas, impuestos adicionales, descuentos/recargos globales y referencias. Cada línea contiene nombre, descripción, códigos, cantidad, unidad, precio unitario, descuentos/recargos, indicador de exención y monto. Cantidad, precio, porcentajes y valores globales permanecen como strings decimales; los montos CLP son enteros seguros. No recalcula impuestos ni verifica criptográficamente firmas: conserva la evidencia original para ese procesamiento posterior.
|
|
102
142
|
|
|
103
143
|
Admite `DTE`, `SetDTE` y `EnvioDTE`, con exactamente un documento 33/34, namespaces SII y codificación UTF-8 o ISO-8859-1. Límite 1 MiB, 10.000 nodos y 32 niveles. Rechaza DTD, entidades externas, documentos múltiples, identidad distinta, valores inválidos y XML mal formado. No consulta URLs incluidas en el documento.
|
|
104
144
|
|
|
145
|
+
`getIssuedInvoiceXml`, `getReceivedInvoiceXml` y `parseDteXml` conservan el detalle histórico de facturas 33/34, sin exigir cabecera ampliada ni agregar metadatos de emisión. `getIssuedDocumentXml` y `parseDteDocumentXml` admiten 33/34/61 y agregan `hasSignature`, `hasTransport` y `fiscalHeader`; éste incluye `noDebitReduction` y `unapprovedFiscalFields`. Las lecturas genéricas preservan esos indicadores y nombres de campos para revisión; no aplican por sí solas las restricciones de escritura del comando de emisión. `hasSignature` es presencia estructural, no verificación criptográfica; un bloque `Transporte` vacío no cuenta como contenido de transporte.
|
|
146
|
+
|
|
105
147
|
La descarga usa HTTP del facturador gratuito; no scrapea filas ni usa un navegador. Desde 0.4.4, si SII presenta el formulario de selección de empresas, envía un único POST a `mipeSelEmpresa.cgi` con `RUT_EMP` igual a `empresaRut` y el destino observado `DESDE_DONDE_URL=OPCION=2&TIPO=4`. No toma la primera empresa ni ejecuta JavaScript; valida el formulario HTML con un parser inerte, acotado a 1 MiB, y rechaza destinos distintos, empresas ausentes/deshabilitadas y selecciones ambiguas. El POST no se reintenta. Comprueba las cookies de empresa antes de descargar y los participantes dentro del XML. CAPTCHA o una selección no confirmada siguen produciendo un error explícito. El RCV también contiene facturas emitidas por otros sistemas; no garantiza que sus XML estén disponibles en este servicio. Prueba real del SDK 0.3.0: 01-10-2026, login personal nuevo y descarga de 5.938 bytes ISO-8859-1, raíz `SetDTE`, una línea con cantidad/precio. La evidencia está en `docs/QA.md` del repositorio.
|
|
106
148
|
|
|
107
149
|
El consumidor debe cotejar además receptor, fecha y total con su referencia autorizada antes de guardar; almacenar el original, hash y fecha de obtención; y reutilizar lo guardado ante reintentos. No iniciar descargas desde SSR ni desde usuarios con permiso sólo de lectura.
|
|
108
150
|
|
|
151
|
+
## PDF de facturas por streaming
|
|
152
|
+
|
|
153
|
+
`getIssuedInvoicePdf` y `getReceivedInvoicePdf` devuelven `Promise<InvoicePdfResult>` con `{ stream: Readable, contentType: 'application/pdf', filename }`. Se exportan `IssuedInvoicePdfQuery`, `ReceivedInvoicePdfQuery`, `PdfDownloadOptions` e `InvoicePdfResult`. El nombre es `factura-<tipo>-<folio>.pdf`, derivado de la identidad validada, sin nombres ni URLs del proveedor. Sólo se admiten facturas 33/34.
|
|
154
|
+
|
|
155
|
+
Se consulta el historial del facturador con `OPCION=2` para emitidas y `OPCION=1` para recibidas. El tipo y folio deben coincidir con una única fila; en recibidas también se verifica el RUT del proveedor. Se confirma la empresa en la sesión antes y después del historial y al abrir el PDF. El código interno se resuelve desde enlaces conocidos del SII: no forma parte de los argumentos públicos, no se aceptan URLs del consumidor ni se ejecuta JavaScript. La identidad se confirma mediante historial y sesión; el SDK no interpreta campos fiscales dentro del PDF ni genera una representación desde el XML.
|
|
156
|
+
|
|
157
|
+
Se exige MIME `application/pdf` o `application/octet-stream` y firma binaria exacta `%PDF-`, incluso fragmentada. Todos los bytes originales se conservan. El stream usa backpressure y `highWaterMark` de 64 KiB; el límite interno de 20 MiB se mide durante la transferencia, aunque falte `Content-Length` o declare menos bytes. No utiliza base64, archivos temporales, caché ni un buffer del documento completo. Los GET conocidos pueden reintentarse antes de entregar el stream; login, POST de selección y transferencias parciales no se reintentan.
|
|
158
|
+
|
|
159
|
+
`timeoutMs` también limita la operación PDF completa, desde apertura del historial hasta cierre de la transferencia. `{ signal }` permite cancelar antes de abrir o durante la lectura. Fin, error, `destroy()`, abort, timeout y `dispose()` cancelan o cierran el origen y liberan lectores, listeners y seguimiento del SDK. Consumir o destruir siempre el stream; mantener la instancia hasta que termine `await pipeline(...)` y después ejecutar `await dispose()` en `finally`. Devolver el stream desde un `try` cuyo `finally` cierra inmediatamente el cliente lo cancelaría antes de que el consumidor pueda leerlo.
|
|
160
|
+
|
|
161
|
+
El [ejemplo HTTP](examples/consulta-pdf.ts) recibe una factura ya autorizada por el backend, inicia sesión y transmite con `Content-Disposition: inline` y `Cache-Control: private, no-store`. Desconectar la respuesta cancela la descarga; una falla después de enviar headers cierra la respuesta sin anexar JSON al PDF. El backend mantiene autorización por actor, tenant, empresa, recurso y sucursal.
|
|
162
|
+
|
|
163
|
+
Liberar estos recursos permite al GC recuperar memoria; no garantiza borrado inmediato de bytes ni elimina referencias o buffers conservados por el consumidor. La [evidencia de QA](docs/sii/QA-PDF-STREAMING.md) distingue pruebas locales de la verificación HTTP real del 09-10-2026: PDF emitido y recibido 33, ejemplo HTTP y cancelación/cierre sin consumir. Tipo 34 sigue pendiente de una muestra real. El botón de Devly Management y los PDF de notas de crédito quedan fuera de este cambio.
|
|
164
|
+
|
|
165
|
+
## Emisión y anulación total
|
|
166
|
+
|
|
167
|
+
Esta ampliación usa HTTP contra el facturador gratuito, con certificado digital centralizado del usuario. No utiliza navegador, CAF propios ni un certificado local. `credenciales: { rut, clave }` y `claveFirma` llegan por argumentos y permanecen en memoria; no escribirlas en configuración, historial de comandos, variables de entorno, registros de operación ni logs.
|
|
168
|
+
|
|
169
|
+
`prepareInvoice` entra por `mipeSelEmpresa.cgi?DESDE_DONDE_URL=OPCION%3D33%26TIPO%3D4`. Con una sola empresa admite el acceso directo; si aparece el selector, envía un único POST con `RUT_EMP` igual a `empresaRut` y `DESDE_DONDE_URL=OPCION=33&TIPO=4`. Nunca usa la primera opción como fallback. Comparte las validaciones del selector de XML, cuyo destino sigue siendo `OPCION=2&TIPO=4`: empresa autorizada, formulario/destino correctos, cookies de empresa confirmadas y ausencia de reintentos del POST. No requiere una opción adicional del consumidor para detectar estos casos.
|
|
170
|
+
|
|
171
|
+
`prepareCancellationCreditNote` admite los mismos caminos directo/selector. Entra por el historial (`OPCION=2&TIPO=4`) al obtener el XML de la factura original; confirma que pertenece a `empresaRut`, resuelve su código interno y prepara la anulación tipo 61 con referencia única a esa factura y `CodRef=1`. Reutiliza el contexto de empresa ya confirmado, también después de preparar una factura. Este método anula una factura del portal; no abre la nota en blanco (`OPCION=61`) para documentos externos. Preparación y firma/envío permanecen separadas; el POST de selección no se reintenta.
|
|
172
|
+
|
|
173
|
+
`InvoiceInput` exige `issuedDate` como fecha civil `YYYY-MM-DD`, `issuer: { address, commune, city, activityCode }`, `receiver: { rut, legalName, address, commune, city, businessActivity, contact? }`, `paymentForm: 1 | 2`, `saleType: 1 | 2`, `purchaseType: 1 | 2 | 3 | 4 | 5 | 6 | 7` e `items: { name, description?, quantity, unitNetPriceClp, unit? }[]`. Direcciones, actividad y datos del receptor deben coincidir con las opciones autorizadas devueltas por el portal; la empresa continúa fijada por instancia. Contacto no confirma entrega de correo.
|
|
174
|
+
|
|
175
|
+
Alcance: factura afecta 33, IVA 19%, una a diez líneas, sin descuentos, exenciones, otros impuestos ni transporte. Cantidad y precio son strings decimales positivos con punto, hasta dos decimales, diez dígitos enteros y doce caracteres. Se redondea cada línea a CLP y luego el IVA con aritmética entera exacta; cada línea debe resultar en al menos $1 CLP y el total no puede exceder $9.999.999.999. Campos desconocidos y opciones fuera del alcance se rechazan. Fechas reales desde 2017; el SII determina si acepta la fecha solicitada.
|
|
176
|
+
|
|
177
|
+
Antes del envío, el XML de factura debe conservar exactamente las opciones aprobadas: se rechazan códigos adicionales de ítems (`CdgItem`) y contenido o atributos efectivos de transporte, aunque un contenedor `Transporte` vacío puede estar presente. Tanto factura como NC rechazan `IndNoRebaja` presente, incluso con valor cero, y cualquier campo de `IdDoc` fuera de `TipoDTE`, `Folio`, `FchEmis`, `FmaPago`, `TpoTranVenta` y `TpoTranCompra`. Esos controles se aplican al XML generado y firmado; la lectura genérica mantiene los indicadores para inspección sin tratarlos como opciones aprobadas.
|
|
178
|
+
|
|
179
|
+
Límites de texto: nombre de línea 25, descripción 999, unidad 4, razón social del receptor 100, dirección 70, comuna 20, ciudad 15, giro del receptor 40 y contacto 80 caracteres. La descripción se acota conservadoramente en el SDK. Código de actividad: seis dígitos. Se recortan espacios externos y se rechazan caracteres de control y texto que no pueda serializarse en la codificación del portal. El comando validado se copia y congela; no conserva referencias mutables del llamador ni admite líneas dispersas o campos fiscales desconocidos.
|
|
180
|
+
|
|
181
|
+
`PreparedDocument` incluye `preparacionId`, `contentHash`, `expiresAt`, identidad de los participantes, tipo, fecha y montos; también el comando normalizado o la factura original y su referencia. Para facturas incluye razón social, giro y `issuerBranchCode` de la dirección emisora seleccionada. Ese código SII se contrasta con el XML y no es un identificador de sucursal interna del backend. Los formularios y tokens quedan dentro de la instancia. Preparaciones vencen a los cinco minutos, pertenecen a esa instancia y se consumen al iniciar la firma. La aprobación debe conservar la huella del contenido efectivamente revisado, no copiar automáticamente la huella para simular aprobación. El SDK rechaza una huella distinta y escrituras simultáneas.
|
|
182
|
+
|
|
183
|
+
El consumidor crea una operación persistente con clave única y aplica autorización antes de preparar. Guarda preparación y aprobación; `beforeSend` es obligatorio y debe confirmar almacenamiento duradero del XML firmado, tipo, folio candidato, participantes, montos y huella, junto con un estado de envío pendiente. Si falla ese respaldo, el SDK no inicia el envío. Después guarda el resultado y audita/notifica desde el backend. El ejemplo compilable `examples/facturacion.ts` muestra estos puntos de integración sin una persistencia simulada.
|
|
184
|
+
|
|
185
|
+
`signAndSend` no reintenta pasos fiscales y cierra su sesión después del intento; mantener igualmente `await dispose()` en `finally`. `ENVIADO` acredita la confirmación de envío observada, no aceptación fiscal ni entrega del documento al receptor. La presencia de una firma en el XML se comprueba estructuralmente; no se verifica criptográficamente su cadena de confianza.
|
|
186
|
+
|
|
187
|
+
Si aparece `SII_ISSUANCE_OUTCOME_UNKNOWN`, el envío comenzó y su resultado no se confirmó. El error saneado no lleva el XML ni el folio: recuperarlos del registro duradero creado en `beforeSend`. También hay que reconciliar si el proceso termina después de ese respaldo o falla al guardar el resultado final. Bloquear cualquier nueva emisión para la misma operación y consultar `getIssuedDocumentXml` en una instancia nueva; cotejar identidad y contenido fiscal contra el candidato guardado. XML ausente, respuesta vacía o falla temporal no demuestran que el envío fracasó ni autorizan repetirlo.
|
|
188
|
+
|
|
189
|
+
La NC del alcance es una anulación total de una factura 33, preparada con `{ factura: { documentType: 33, folio }, issuedDate }`. Usar el folio confirmado de la factura que se desea anular, una operación independiente y una aprobación nueva. La preparación conserva receptor, montos y referencia única al documento original con `CodRef=1`; no admite correcciones parciales ni de texto. El XML 61 puede omitir forma de pago y tipos de transacción de `IdDoc`; si están presentes, deben coincidir con la factura original. Cantidades y precios se comparan como decimales equivalentes, manteniendo el XML original intacto. Conservar ambos XML y su relación. Preparar o enviar una NC no demuestra por sí solo su aceptación fiscal ni la anulación aceptada por el SII.
|
|
190
|
+
|
|
109
191
|
## Errores y recuperación
|
|
110
192
|
|
|
111
193
|
Errores de parámetros generan `TypeError`. Proveedor/protocolo/sesión generan `SiiError` con `code` y, cuando corresponde, `httpStatus`. Mensajes no incluyen cuerpos HTTP ni secretos.
|
|
@@ -118,7 +200,7 @@ La descarga distingue rechazo por demasiados documentos (`DOCUMENT_LIMIT_EXCEEDE
|
|
|
118
200
|
import { SiiError } from '@devly-cl/sii-client';
|
|
119
201
|
|
|
120
202
|
try {
|
|
121
|
-
await sii.
|
|
203
|
+
await sii.getReceivedInvoiceXml(consulta);
|
|
122
204
|
} catch (error) {
|
|
123
205
|
if (error instanceof SiiError) {
|
|
124
206
|
// Campos saneados; jamás registrar credenciales ni el cuerpo del proveedor.
|
|
@@ -143,10 +225,20 @@ try {
|
|
|
143
225
|
- `SII_XML_UNAVAILABLE`: el servicio no entregó un XML para esa factura.
|
|
144
226
|
- `SII_XML_COMPANY_SELECTION_REQUIRED`: selección del facturador no confirmada. `diagnostics.reason` distingue empresa ausente/no autorizada (`COMPANY_NOT_AUTHORIZED`), formulario inválido (`INVALID_RESPONSE`) o falta de confirmación/cookies incorrectas (`COMPANY_SELECTION_REQUIRED`).
|
|
145
227
|
- `SII_XML_INVALID` / `SII_XML_IDENTITY_MISMATCH`: XML inseguro/incorrecto o identidad distinta; no guardar.
|
|
228
|
+
- `SII_PDF_UNAVAILABLE`: el historial indica explícitamente que no encontró el documento.
|
|
229
|
+
- `SII_PDF_INVALID`: MIME, firma binaria o tamaño del PDF inválido; puede aparecer durante la lectura del stream.
|
|
230
|
+
- `SII_PDF_IDENTITY_MISMATCH`: tipo, folio o proveedor distintos, enlace no permitido o historial ambiguo; no descargar.
|
|
231
|
+
- `SII_OPERATION_ABORTED`: el consumidor canceló una operación PDF. Timeout conserva `SII_TRANSPORT_ERROR` con motivo `TIMEOUT`; cierre de instancia conserva `CLIENT_CLOSED`.
|
|
232
|
+
- `SII_OPERATION_IN_PROGRESS` / `SII_PREPARATION_UNAVAILABLE`: otra escritura en curso o preparación ausente, consumida o vencida; no reutilizar ni duplicar una operación ya enviada.
|
|
233
|
+
- `SII_APPROVAL_MISMATCH` / `SII_DOCUMENT_CONTENT_MISMATCH`: huella no aprobada o contenido fiscal distinto del esperado; detener el envío y revisar.
|
|
234
|
+
- `SII_DOCUMENT_VALIDATION_REJECTED`: el portal rechazó la vista previa, incluso con HTTP 200 y una redirección por script; no continuar a firma. El diagnóstico conserva etapa y motivo sin revelar el texto privado del proveedor.
|
|
235
|
+
- `SII_CERTIFICATE_UNAVAILABLE` / `SII_SIGNATURE_INVALID`: certificado no resoluble o firma inválida; el diagnóstico distingue motivos observados como clave incorrecta, expiración o revocación.
|
|
236
|
+
- `SII_DOCUMENT_RECOVERY_FAILED`: no fue posible resolver inequívocamente el documento original para la anulación; no sustituirlo por otro folio.
|
|
237
|
+
- `SII_ISSUANCE_OUTCOME_UNKNOWN`: envío iniciado sin confirmación; reconciliar con el candidato respaldado antes de cualquier decisión posterior.
|
|
146
238
|
|
|
147
|
-
Timeout por solicitud: 15 segundos por defecto, rango 1 a 30 segundos. Login nunca se reintenta automáticamente. Lecturas conocidas admiten 0 a 2 reintentos por transporte o HTTP 429/502/503/504; por defecto, uno. TLS conserva validación normal.
|
|
239
|
+
Timeout por solicitud: 15 segundos por defecto, rango 1 a 30 segundos; PDF aplica también ese límite a toda la operación. Login nunca se reintenta automáticamente. Lecturas conocidas admiten 0 a 2 reintentos por transporte o HTTP 429/502/503/504; por defecto, uno. TLS conserva validación normal. La entrada al facturador sigue sólo redirecciones HTTPS a selección, lanzamiento y la ruta conocida correspondiente de `www1.sii.cl`, hasta cinco solicitudes; otras redirecciones se rechazan. La descarga del PDF no sigue redirecciones.
|
|
148
240
|
|
|
149
|
-
El contrato observado exige `conversationId` igual a la cookie secreta `TOKEN` y `Accept: application/json, text/plain, */*`. Ambos tienen checks de regresión. No se implementa resolución de CAPTCHA
|
|
241
|
+
El contrato observado del RCV exige `conversationId` igual a la cookie secreta `TOKEN` y `Accept: application/json, text/plain, */*`. Ambos tienen checks de regresión. No se implementa resolución de CAPTCHA. Login, selección de empresa, preparación, firma y envío no se reintentan automáticamente.
|
|
150
242
|
|
|
151
243
|
## Límites y responsabilidades del consumidor
|
|
152
244
|
|
|
@@ -154,6 +246,6 @@ El SDK valida RUT, sesión personal y autorización SII por empresa. Cada backen
|
|
|
154
246
|
|
|
155
247
|
Auditar actor interno, tenant, empresa autorizada, operación, periodo, resultado y correlación del backend. Nunca registrar clave, cookies, TOKEN, conversationId, tokens CAPTCHA, cuerpo del login ni respuesta financiera completa. Para importar facturas emitidas, usar clave única por emisor/tipo/folio; período y receptor no son parte de la identidad. El consumidor mantiene consultas indexadas, listados paginados e idempotencia para tolerar reintentos.
|
|
156
248
|
|
|
157
|
-
Otros documentos, documentos observados, descargas diferidas, grandes volúmenes, CAPTCHA activo y expiración real siguen pendientes. El SDK
|
|
249
|
+
Otros documentos, documentos observados, descargas diferidas, grandes volúmenes, CAPTCHA activo y expiración real siguen pendientes. El SDK tiene pruebas históricas reales de lectura: login personal, resúmenes, listado 33 y XML del facturador gratuito. El 08-10-2026 se confirmó por HTTP el envío de una factura nueva 33 y de una NC 61 de anulación total, con recuperación de ambos XML y referencia/montos cotejados; los identificadores y respaldos permanecen privados. Preparaciones anteriores detenidas antes del POST de envío no se presentan como documentos enviados. Esto no acredita aceptación fiscal, anulación aceptada, entrega de correo ni validez criptográfica. Casos de borde, alteraciones, documentos incompletos y errores se validan con proveedor sintético; los checks no certifican disponibilidad general productiva del SII.
|
|
158
250
|
|
|
159
251
|
`scripts/live-check.mjs` permite verificar SII real recibiendo una línea JSON por stdin con `empresaRut`, `rut`, `clave`, `periodo` y opcional `tokenRecaptcha`. Usar un programa que escriba stdin; nunca guardar credenciales o tokens en comandos, archivos, argumentos o variables de entorno. Su salida contiene sólo confirmación, cantidades por tipo documental y cobertura; no imprime facturas individuales. La ampliación del script no constituye una prueba real ejecutada.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { type IssuedInvoice, type IssuedInvoicesQuery, type IssuedInvoicesResult, type InvoiceDocumentType } from '../domain/issued-invoice';
|
|
2
|
+
export interface InvoiceReadPort<T extends IssuedInvoice> {
|
|
3
|
+
initialLimit(): Promise<number>;
|
|
4
|
+
counts(): Promise<{
|
|
5
|
+
documentType: InvoiceDocumentType;
|
|
6
|
+
count: number;
|
|
7
|
+
}[]>;
|
|
8
|
+
details(type: InvoiceDocumentType, tokenRecaptcha: string): Promise<T[]>;
|
|
9
|
+
}
|
|
10
|
+
export declare class InvoiceQueryError extends Error {
|
|
11
|
+
readonly section: 'SUMMARY' | 'DETAIL';
|
|
12
|
+
constructor(section: 'SUMMARY' | 'DETAIL');
|
|
13
|
+
}
|
|
14
|
+
/** Coverage and identity reconciliation operate on normalized invoices, never provider rows. */
|
|
15
|
+
export declare function readInvoices<T extends IssuedInvoice>(port: InvoiceReadPort<T>, { periodo, tokenRecaptcha }: IssuedInvoicesQuery): Promise<Omit<IssuedInvoicesResult, 'data'> & {
|
|
16
|
+
data: T[];
|
|
17
|
+
}>;
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.InvoiceQueryError = void 0;
|
|
4
|
+
exports.readInvoices = readInvoices;
|
|
5
|
+
const issued_invoice_1 = require("../domain/issued-invoice");
|
|
6
|
+
class InvoiceQueryError extends Error {
|
|
7
|
+
section;
|
|
8
|
+
constructor(section) {
|
|
9
|
+
super('SII_INVALID_RESPONSE');
|
|
10
|
+
this.section = section;
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
exports.InvoiceQueryError = InvoiceQueryError;
|
|
14
|
+
/** Coverage and identity reconciliation operate on normalized invoices, never provider rows. */
|
|
15
|
+
async function readInvoices(port, { periodo, tokenRecaptcha = 't-o-k-e-n-web' }) {
|
|
16
|
+
(0, issued_invoice_1.assertPeriod)(periodo);
|
|
17
|
+
if (typeof tokenRecaptcha !== 'string' || !tokenRecaptcha.trim())
|
|
18
|
+
throw new TypeError('tokenRecaptcha inválido');
|
|
19
|
+
const limit = await port.initialLimit();
|
|
20
|
+
const expected = new Map();
|
|
21
|
+
let expectedCount = 0;
|
|
22
|
+
for (const { documentType: type, count } of await port.counts()) {
|
|
23
|
+
if (expected.has(type) && expected.get(type) !== count)
|
|
24
|
+
throw new InvoiceQueryError('SUMMARY');
|
|
25
|
+
if (!expected.has(type))
|
|
26
|
+
expectedCount += count;
|
|
27
|
+
if (!Number.isSafeInteger(expectedCount))
|
|
28
|
+
throw new InvoiceQueryError('SUMMARY');
|
|
29
|
+
expected.set(type, count);
|
|
30
|
+
}
|
|
31
|
+
const invoices = new Map();
|
|
32
|
+
const incompleteDocumentTypes = [];
|
|
33
|
+
for (const [type, count] of expected) {
|
|
34
|
+
if (count === 0)
|
|
35
|
+
continue;
|
|
36
|
+
let uniqueCount = 0;
|
|
37
|
+
for (const invoice of await port.details(type, tokenRecaptcha)) {
|
|
38
|
+
const key = `${invoice.issuerRut}:${invoice.documentType}:${invoice.folio}`;
|
|
39
|
+
const previous = invoices.get(key);
|
|
40
|
+
if (previous && JSON.stringify(previous) !== JSON.stringify(invoice))
|
|
41
|
+
throw new InvoiceQueryError('DETAIL');
|
|
42
|
+
if (!previous) {
|
|
43
|
+
invoices.set(key, invoice);
|
|
44
|
+
uniqueCount++;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
if (count > limit || uniqueCount !== count)
|
|
48
|
+
incompleteDocumentTypes.push(type);
|
|
49
|
+
}
|
|
50
|
+
return { data: [...invoices.values()], complete: incompleteDocumentTypes.length === 0, expectedCount, observedAt: new Date().toISOString(), incompleteDocumentTypes };
|
|
51
|
+
}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import { type InvoiceInput } from '../domain/invoicing';
|
|
2
|
+
import { type PreparedDocument, type DocumentContent, type SignedDocument, type SentDocument } from '../domain/document';
|
|
3
|
+
import type { IssuedInvoiceXmlQuery, IssuedDocumentXmlResult } from '../domain/invoice-xml';
|
|
4
|
+
export interface SignDocumentInput {
|
|
5
|
+
preparacionId: string;
|
|
6
|
+
approvedHash: string;
|
|
7
|
+
claveFirma: string;
|
|
8
|
+
/** Persistir XML e identidad antes del envío. Si falla, no se envía. Sin guardar secretos. */
|
|
9
|
+
beforeSend: (document: SignedDocument) => Promise<void>;
|
|
10
|
+
}
|
|
11
|
+
/** @deprecated Use SignDocumentInput. */
|
|
12
|
+
export type FirmaDocumento = SignDocumentInput;
|
|
13
|
+
export interface CancellationInput {
|
|
14
|
+
factura: IssuedInvoiceXmlQuery;
|
|
15
|
+
issuedDate: string;
|
|
16
|
+
}
|
|
17
|
+
export interface InvoicingPort {
|
|
18
|
+
assertReady(): void;
|
|
19
|
+
prepareInvoice(input: InvoiceInput): Promise<DocumentContent>;
|
|
20
|
+
prepareCancellationCreditNote(input: CancellationInput): Promise<DocumentContent>;
|
|
21
|
+
unsignedDocument(approved: PreparedDocument): Promise<IssuedDocumentXmlResult>;
|
|
22
|
+
signDocument(approved: PreparedDocument, password: string): Promise<SignedDocument>;
|
|
23
|
+
sendDocument(document: SignedDocument, password: string): Promise<void>;
|
|
24
|
+
close(): Promise<void>;
|
|
25
|
+
}
|
|
26
|
+
export declare class IssuanceError extends Error {
|
|
27
|
+
readonly code: string;
|
|
28
|
+
constructor(code: string);
|
|
29
|
+
}
|
|
30
|
+
/** Approval, single use and durable pre-send persistence are independent of SII's wire protocol. */
|
|
31
|
+
export declare class DocumentIssuance {
|
|
32
|
+
#private;
|
|
33
|
+
private readonly port;
|
|
34
|
+
constructor(port: InvoicingPort);
|
|
35
|
+
get pendingWrite(): Promise<unknown> | undefined;
|
|
36
|
+
clearPreparation(): void;
|
|
37
|
+
prepareInvoice(input: InvoiceInput): Promise<PreparedDocument>;
|
|
38
|
+
prepareCancellationCreditNote(input: CancellationInput): Promise<PreparedDocument>;
|
|
39
|
+
signAndSend(input: SignDocumentInput): Promise<SentDocument>;
|
|
40
|
+
}
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.DocumentIssuance = exports.IssuanceError = void 0;
|
|
4
|
+
const node_crypto_1 = require("node:crypto");
|
|
5
|
+
const invoicing_1 = require("../domain/invoicing");
|
|
6
|
+
const document_1 = require("../domain/document");
|
|
7
|
+
class IssuanceError extends Error {
|
|
8
|
+
code;
|
|
9
|
+
constructor(code) {
|
|
10
|
+
super(code);
|
|
11
|
+
this.code = code;
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
exports.IssuanceError = IssuanceError;
|
|
15
|
+
/** Approval, single use and durable pre-send persistence are independent of SII's wire protocol. */
|
|
16
|
+
class DocumentIssuance {
|
|
17
|
+
port;
|
|
18
|
+
#write;
|
|
19
|
+
#prepared;
|
|
20
|
+
constructor(port) {
|
|
21
|
+
this.port = port;
|
|
22
|
+
}
|
|
23
|
+
get pendingWrite() { return this.#write; }
|
|
24
|
+
clearPreparation() { this.#prepared = undefined; }
|
|
25
|
+
async prepareInvoice(input) {
|
|
26
|
+
this.port.assertReady();
|
|
27
|
+
const invoice = (0, invoicing_1.validateInvoice)(input);
|
|
28
|
+
return this.#writeOperation(async () => this.#keepPreparation(await this.port.prepareInvoice(invoice)));
|
|
29
|
+
}
|
|
30
|
+
async prepareCancellationCreditNote(input) {
|
|
31
|
+
this.port.assertReady();
|
|
32
|
+
const { factura, issuedDate } = input;
|
|
33
|
+
if (factura.documentType !== 33 || !/^[1-9]\d{0,19}$/.test(factura.folio) || !/^\d{4}-\d{2}-\d{2}$/.test(issuedDate) || new Date(`${issuedDate}T00:00:00Z`).toISOString().slice(0, 10) !== issuedDate)
|
|
34
|
+
throw new TypeError('Referencia o fecha de anulación inválida');
|
|
35
|
+
return this.#writeOperation(async () => this.#keepPreparation(await this.port.prepareCancellationCreditNote(input)));
|
|
36
|
+
}
|
|
37
|
+
signAndSend(input) {
|
|
38
|
+
if (this.#write)
|
|
39
|
+
return Promise.reject(new IssuanceError('SII_OPERATION_IN_PROGRESS'));
|
|
40
|
+
const prepared = this.#prepared;
|
|
41
|
+
if (!prepared || input.preparacionId !== prepared.preparacionId || Date.now() >= Date.parse(prepared.expiresAt))
|
|
42
|
+
return Promise.reject(new IssuanceError('SII_PREPARATION_UNAVAILABLE'));
|
|
43
|
+
if (input.approvedHash !== prepared.contentHash)
|
|
44
|
+
return Promise.reject(new IssuanceError('SII_APPROVAL_MISMATCH'));
|
|
45
|
+
if (typeof input.claveFirma !== 'string' || !input.claveFirma || input.claveFirma.length > 256 || typeof input.beforeSend !== 'function')
|
|
46
|
+
return Promise.reject(new TypeError('Clave de firma o persistencia previa inválida'));
|
|
47
|
+
this.port.assertReady();
|
|
48
|
+
return this.#writeOperation(async () => {
|
|
49
|
+
this.#prepared = undefined;
|
|
50
|
+
const unsigned = await this.port.unsignedDocument(prepared);
|
|
51
|
+
(0, document_1.assertApprovedDocument)(unsigned, prepared);
|
|
52
|
+
const document = await this.port.signDocument(prepared, input.claveFirma);
|
|
53
|
+
(0, document_1.assertApprovedDocument)(document, prepared);
|
|
54
|
+
await input.beforeSend(structuredClone(document));
|
|
55
|
+
await this.port.sendDocument(document, input.claveFirma);
|
|
56
|
+
return { ...document, status: 'ENVIADO' };
|
|
57
|
+
}).finally(() => this.port.close());
|
|
58
|
+
}
|
|
59
|
+
#writeOperation(action) {
|
|
60
|
+
if (this.#write)
|
|
61
|
+
return Promise.reject(new IssuanceError('SII_OPERATION_IN_PROGRESS'));
|
|
62
|
+
const promise = action();
|
|
63
|
+
this.#write = promise;
|
|
64
|
+
void promise.then(() => { this.#write = undefined; }, () => { this.#write = undefined; });
|
|
65
|
+
return promise;
|
|
66
|
+
}
|
|
67
|
+
#keepPreparation(content) {
|
|
68
|
+
const result = Object.freeze({ ...content, preparacionId: (0, node_crypto_1.randomUUID)(), contentHash: (0, invoicing_1.hashContent)(content), expiresAt: new Date(Date.now() + 300_000).toISOString() });
|
|
69
|
+
const freeze = (value) => { if (value && typeof value === 'object') {
|
|
70
|
+
for (const child of Object.values(value))
|
|
71
|
+
freeze(child);
|
|
72
|
+
Object.freeze(value);
|
|
73
|
+
} };
|
|
74
|
+
freeze(result);
|
|
75
|
+
this.#prepared = result;
|
|
76
|
+
return result;
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
exports.DocumentIssuance = DocumentIssuance;
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
import type { Readable } from 'node:stream';
|
|
2
|
+
import type { IssuedInvoiceXmlQuery, ReceivedInvoiceXmlQuery } from './domain/invoice-xml';
|
|
3
|
+
export type IssuedInvoicePdfQuery = IssuedInvoiceXmlQuery;
|
|
4
|
+
export type ReceivedInvoicePdfQuery = ReceivedInvoiceXmlQuery;
|
|
5
|
+
export interface PdfDownloadOptions {
|
|
6
|
+
signal?: AbortSignal;
|
|
7
|
+
}
|
|
8
|
+
export interface InvoicePdfResult {
|
|
9
|
+
stream: Readable;
|
|
10
|
+
contentType: 'application/pdf';
|
|
11
|
+
filename: string;
|
|
12
|
+
}
|
|
13
|
+
export type Operation = 'COMPRA' | 'VENTA';
|
|
14
|
+
export type PurchaseStatus = 'REGISTRO' | 'PENDIENTE' | 'NO_INCLUIR' | 'RECLAMADO';
|
|
15
|
+
export type SiiRecord = Record<string, unknown>;
|
|
16
|
+
export interface SiiResponse<T = SiiRecord> {
|
|
17
|
+
data: T[];
|
|
18
|
+
metaData: Record<string, unknown>;
|
|
19
|
+
respEstado: {
|
|
20
|
+
codRespuesta: number;
|
|
21
|
+
msgeRespuesta: string | null;
|
|
22
|
+
codError: unknown;
|
|
23
|
+
};
|
|
24
|
+
[key: string]: unknown;
|
|
25
|
+
}
|
|
26
|
+
export interface AuthorizedCompany extends SiiRecord {
|
|
27
|
+
usrEmpRut: number;
|
|
28
|
+
usrEmpDv: string;
|
|
29
|
+
usrEmpRutDv: string;
|
|
30
|
+
}
|
|
31
|
+
export interface SiiClientOptions {
|
|
32
|
+
empresaRut: string;
|
|
33
|
+
timeoutMs?: number;
|
|
34
|
+
retries?: number;
|
|
35
|
+
fetchImpl?: typeof globalThis.fetch;
|
|
36
|
+
}
|
|
37
|
+
export interface SiiCredentials {
|
|
38
|
+
rut: string;
|
|
39
|
+
clave: string;
|
|
40
|
+
}
|
|
41
|
+
export interface SummaryQuery {
|
|
42
|
+
periodo: string;
|
|
43
|
+
operacion: Operation;
|
|
44
|
+
estado?: PurchaseStatus;
|
|
45
|
+
}
|
|
46
|
+
export interface SiiSession {
|
|
47
|
+
usuarioRut: string;
|
|
48
|
+
empresaRut: string;
|
|
49
|
+
representacion: false;
|
|
50
|
+
}
|
|
51
|
+
/** @deprecated Use Operation. */
|
|
52
|
+
export type Operacion = Operation;
|
|
53
|
+
/** @deprecated Use PurchaseStatus. */
|
|
54
|
+
export type EstadoCompra = PurchaseStatus;
|
|
55
|
+
/** @deprecated Use SiiRecord. */
|
|
56
|
+
export type RegistroSii = SiiRecord;
|
|
57
|
+
/** @deprecated Use SiiResponse. */
|
|
58
|
+
export type RespuestaSii<T = SiiRecord> = SiiResponse<T>;
|
|
59
|
+
/** @deprecated Use AuthorizedCompany. */
|
|
60
|
+
export type EmpresaAutorizada = AuthorizedCompany;
|
|
61
|
+
/** @deprecated Use SiiCredentials. */
|
|
62
|
+
export type CredencialesSii = SiiCredentials;
|
|
63
|
+
/** @deprecated Use SummaryQuery. */
|
|
64
|
+
export type ConsultaResumen = SummaryQuery;
|
|
65
|
+
/** @deprecated Use SiiSession. */
|
|
66
|
+
export type SesionSii = SiiSession;
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { type InvoiceInput } from './invoicing';
|
|
2
|
+
import type { IssuedDocumentXmlResult } from './invoice-xml';
|
|
3
|
+
export interface PreparedDocument {
|
|
4
|
+
readonly preparacionId: string;
|
|
5
|
+
readonly contentHash: string;
|
|
6
|
+
readonly expiresAt: string;
|
|
7
|
+
readonly issuerRut: string;
|
|
8
|
+
readonly receiverRut: string;
|
|
9
|
+
readonly documentType: 33 | 61;
|
|
10
|
+
readonly issuedDate: string;
|
|
11
|
+
readonly netAmount: number;
|
|
12
|
+
readonly vatAmount: number;
|
|
13
|
+
readonly totalAmount: number;
|
|
14
|
+
readonly invoice?: InvoiceInput;
|
|
15
|
+
readonly issuerLegalName?: string;
|
|
16
|
+
readonly issuerBusinessActivity?: string;
|
|
17
|
+
readonly issuerBranchCode?: string;
|
|
18
|
+
readonly originalInvoice?: IssuedDocumentXmlResult['detail'];
|
|
19
|
+
readonly reference?: {
|
|
20
|
+
readonly documentType: 33;
|
|
21
|
+
readonly folio: string;
|
|
22
|
+
readonly issuedDate: string;
|
|
23
|
+
readonly code: 1;
|
|
24
|
+
};
|
|
25
|
+
}
|
|
26
|
+
export interface SignedDocument extends IssuedDocumentXmlResult {
|
|
27
|
+
readonly issuerRut: string;
|
|
28
|
+
readonly receiverRut: string;
|
|
29
|
+
readonly documentType: 33 | 61;
|
|
30
|
+
readonly folio: string;
|
|
31
|
+
readonly issuedDate: string;
|
|
32
|
+
readonly contentHash: string;
|
|
33
|
+
}
|
|
34
|
+
export interface SentDocument extends SignedDocument {
|
|
35
|
+
readonly status: 'ENVIADO';
|
|
36
|
+
}
|
|
37
|
+
export type DocumentContent = Omit<PreparedDocument, 'preparacionId' | 'contentHash' | 'expiresAt'>;
|
|
38
|
+
export declare class DocumentContentMismatchError extends Error {
|
|
39
|
+
constructor();
|
|
40
|
+
}
|
|
41
|
+
export declare function assertApprovedDocument(document: IssuedDocumentXmlResult, approved: PreparedDocument): void;
|
|
42
|
+
/** @deprecated Use PreparedDocument. */
|
|
43
|
+
export type DocumentoPreparado = PreparedDocument;
|
|
44
|
+
/** @deprecated Use SignedDocument. */
|
|
45
|
+
export type DocumentoFirmado = SignedDocument;
|
|
46
|
+
/** @deprecated Use SentDocument. */
|
|
47
|
+
export type DocumentoEnviado = SentDocument;
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.DocumentContentMismatchError = void 0;
|
|
4
|
+
exports.assertApprovedDocument = assertApprovedDocument;
|
|
5
|
+
const invoicing_1 = require("./invoicing");
|
|
6
|
+
class DocumentContentMismatchError extends Error {
|
|
7
|
+
constructor() { super('SII_DOCUMENT_CONTENT_MISMATCH'); }
|
|
8
|
+
}
|
|
9
|
+
exports.DocumentContentMismatchError = DocumentContentMismatchError;
|
|
10
|
+
function assertApprovedDocument(document, approved) {
|
|
11
|
+
const d = document.detail;
|
|
12
|
+
const decimal = (value) => value == null ? null : value.replace(/^0+(?=\d)/, '').replace(/(\.\d*?)0+$/, '$1').replace(/\.$/, '');
|
|
13
|
+
if (d.issuedDate !== approved.issuedDate || d.netAmount !== approved.netAmount || d.vatAmount !== approved.vatAmount || d.totalAmount !== approved.totalAmount || Number(d.vatRate) !== 19 || d.taxes.length || d.adjustments.length || d.exemptAmount || d.fiscalHeader?.noDebitReduction != null || d.fiscalHeader?.unapprovedFiscalFields.length)
|
|
14
|
+
throw new DocumentContentMismatchError();
|
|
15
|
+
if (approved.invoice) {
|
|
16
|
+
const items = approved.invoice.items;
|
|
17
|
+
const header = d.fiscalHeader;
|
|
18
|
+
const i = approved.invoice;
|
|
19
|
+
const branch = (value) => (value ?? '').replace(/^0+(?=\d)/, '');
|
|
20
|
+
if (branch(header?.issuer.branchCode) !== branch(approved.issuerBranchCode))
|
|
21
|
+
throw new DocumentContentMismatchError();
|
|
22
|
+
if (!header || header.issuer.legalName !== approved.issuerLegalName || header.issuer.businessActivity !== approved.issuerBusinessActivity || header.issuer.address !== i.issuer.address || header.issuer.commune !== i.issuer.commune || header.issuer.city !== i.issuer.city || header.issuer.activityCode !== i.issuer.activityCode || header.receiver.legalName !== i.receiver.legalName || header.receiver.businessActivity !== i.receiver.businessActivity || header.receiver.address !== i.receiver.address || header.receiver.commune !== i.receiver.commune || header.receiver.city !== i.receiver.city || (header.receiver.contact ?? '') !== (i.receiver.contact ?? '') || header.paymentForm !== i.paymentForm || header.saleType !== i.saleType || header.purchaseType !== i.purchaseType)
|
|
23
|
+
throw new DocumentContentMismatchError();
|
|
24
|
+
if (d.hasTransport || d.lines.length !== items.length || d.references.length || d.lines.some((line, i) => line.codes.length || line.name !== items[i]?.name || (line.description ?? '') !== (items[i]?.description ?? '') || decimal(line.quantity) !== decimal(items[i]?.quantity ?? null) || decimal(line.unitPrice) !== decimal(items[i]?.unitNetPriceClp ?? null) || (line.unit ?? '') !== (items[i]?.unit ?? '') || line.amount !== (0, invoicing_1.calculateInvoiceTotals)([items[i]]).netAmount || line.discountAmount || line.surchargeAmount || line.discountPercent && Number(line.discountPercent) || line.surchargePercent && Number(line.surchargePercent) || line.exemptIndicator))
|
|
25
|
+
throw new DocumentContentMismatchError();
|
|
26
|
+
}
|
|
27
|
+
else {
|
|
28
|
+
const ref = d.references[0];
|
|
29
|
+
if (!approved.reference || d.references.length !== 1 || ref?.documentType !== '33' || ref.folio !== approved.reference.folio || ref.date !== approved.reference.issuedDate || ref.code !== 1)
|
|
30
|
+
throw new DocumentContentMismatchError();
|
|
31
|
+
const original = approved.originalInvoice;
|
|
32
|
+
const header = d.fiscalHeader;
|
|
33
|
+
const originalHeader = original?.fiscalHeader;
|
|
34
|
+
const lines = (values) => values.map(line => ({ ...line, quantity: decimal(line.quantity), unitPrice: decimal(line.unitPrice), discountPercent: decimal(line.discountPercent), surchargePercent: decimal(line.surchargePercent) }));
|
|
35
|
+
if (!original || !header || !originalHeader || (0, invoicing_1.hashContent)(lines(d.lines)) !== (0, invoicing_1.hashContent)(lines(original.lines)) || (0, invoicing_1.hashContent)(header.issuer) !== (0, invoicing_1.hashContent)(originalHeader.issuer) || (0, invoicing_1.hashContent)(header.receiver) !== (0, invoicing_1.hashContent)(originalHeader.receiver) || ['paymentForm', 'saleType', 'purchaseType'].some(field => header[field] !== null && header[field] !== originalHeader[field]))
|
|
36
|
+
throw new DocumentContentMismatchError();
|
|
37
|
+
}
|
|
38
|
+
}
|