@devly-cl/sii-client 0.6.0 → 0.7.1
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 +96 -251
- package/dist/application/document-status.d.ts +13 -0
- package/dist/application/document-status.js +50 -0
- package/dist/application/invoice-queries.d.ts +11 -5
- package/dist/application/invoice-queries.js +13 -9
- package/dist/domain/company-info.d.ts +13 -0
- package/dist/domain/company-info.js +2 -0
- package/dist/domain/document-status.d.ts +93 -0
- package/dist/domain/document-status.js +69 -0
- package/dist/domain/document.d.ts +4 -0
- package/dist/domain/document.js +36 -3
- package/dist/domain/invoice-xml.d.ts +34 -1
- package/dist/domain/invoicing.d.ts +78 -5
- package/dist/domain/invoicing.js +143 -26
- package/dist/domain/rcv-document.d.ts +17 -0
- package/dist/domain/rcv-document.js +2 -0
- package/dist/index.d.ts +7 -4
- package/dist/index.js +2 -1
- package/dist/infrastructure/document-status-gateway.d.ts +13 -0
- package/dist/infrastructure/document-status-gateway.js +127 -0
- package/dist/infrastructure/document-status-parser.d.ts +12 -0
- package/dist/infrastructure/document-status-parser.js +258 -0
- package/dist/infrastructure/dte-xml.js +81 -6
- package/dist/infrastructure/facturador-gateway.d.ts +4 -1
- package/dist/infrastructure/facturador-gateway.js +113 -15
- package/dist/infrastructure/facturador.d.ts +3 -0
- package/dist/infrastructure/facturador.js +18 -1
- package/dist/infrastructure/rcv-gateway.d.ts +3 -0
- package/dist/infrastructure/rcv-gateway.js +9 -5
- package/dist/infrastructure/rcv-normalization.d.ts +7 -0
- package/dist/infrastructure/rcv-normalization.js +9 -1
- package/dist/infrastructure/sii-client.d.ts +10 -1
- package/dist/infrastructure/sii-client.js +29 -3
- package/dist/infrastructure/sii-http-session.d.ts +5 -1
- package/dist/infrastructure/sii-http-session.js +20 -5
- package/dist/sii-error.d.ts +3 -3
- package/dist/sii-error.js +10 -4
- package/package.json +45 -45
- package/dist/domain/sii-error.d.ts +0 -27
- package/dist/domain/sii-error.js +0 -82
package/README.md
CHANGED
|
@@ -1,251 +1,96 @@
|
|
|
1
|
-
# SII Client
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
```sh
|
|
12
|
-
npm
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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.
|
|
104
|
-
|
|
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.
|
|
106
|
-
|
|
107
|
-
Desde 0.4.2, `dispose()` bloquea nuevas solicitudes, espera las que estén en curso y llama al cierre oficial del SII con las cookies de esa instancia antes de borrarlas. También limpia logins parcialmente autenticados que luego fallen; repetir o invocar simultáneamente `dispose()` produce un único cierre. No utiliza cookies del navegador ni cierra sesiones de otros clientes/tenants. Sin sesión creada, no solicita logout.
|
|
108
|
-
|
|
109
|
-
El cierre remoto tiene el timeout configurado, no reintenta login ni sigue redirecciones. Si SII rechaza el cierre o falla la red, descarta secretos locales y emite la advertencia Node `SII_LOGOUT_FAILED`, sin datos privados y sin reemplazar el error de la operación. Los logs del backend permiten observarla. Una respuesta de sesión ya ausente se acepta. No puede recuperar ni cerrar sesiones antiguas cuyas cookies ya se descartaron; tampoco garantiza cierre tras una terminación forzada del proceso.
|
|
110
|
-
|
|
111
|
-
Estados de compra: `REGISTRO`, `PENDIENTE`, `NO_INCLUIR`, `RECLAMADO`. Venta admite `REGISTRO`. Periodos desde 2017, meses 01 a 12; SII determina su disponibilidad real.
|
|
112
|
-
|
|
113
|
-
## Facturas emitidas
|
|
114
|
-
|
|
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.
|
|
116
|
-
|
|
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.
|
|
118
|
-
|
|
119
|
-
Montos enteros seguros y no negativos; total obligatorio. Componentes ausentes/null permanecen `null`. No recalcula IVA ni exige que neto/exento/IVA sumen el total: éste puede incluir otros impuestos. Nombre o sucursal ausentes son `null`; código SII de sucursal `0` se conserva como `'0'`, sin mapearlo a una sucursal interna. No interpreta `detAnulado` como una decisión tributaria.
|
|
120
|
-
|
|
121
|
-
Identidad: `issuerRut + documentType + folio`, independiente del período y receptor. Duplicados normalizados idénticos se colapsan; valores distintos para esa identidad rechazan la respuesta con `SII_INVALID_RESPONSE`. Datos inválidos también rechazan la respuesta completa; el error no revela filas, identidades ni montos.
|
|
122
|
-
|
|
123
|
-
Cobertura completa exige cantidades únicas coincidentes con el resumen y cantidades esperadas dentro de `limiteDtes`. Si una cantidad supera el límite o no coincide, devuelve los registros válidos disponibles con `complete: false` y los tipos incompletos. Cero documentos reales devuelve `complete: true` y `data: []`. No inventa paginación ni descarga diferida; un resultado parcial no demuestra ausencia de otras facturas y no debe importarse como un período completo.
|
|
124
|
-
|
|
125
|
-
Por defecto envía el literal `t-o-k-e-n-web` usado por el servicio del portal observado; `tokenRecaptcha` permite un token explícito obtenido por el consumidor autorizado. Un CAPTCHA activo genera `CAPTCHA_INTERACTION_REQUIRED`: no hay solver, bypass ni reintento automático de esa respuesta. Código SII 99 es error de servicio, no resultado vacío.
|
|
126
|
-
|
|
127
|
-
## Facturas recibidas
|
|
128
|
-
|
|
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.
|
|
130
|
-
|
|
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.
|
|
132
|
-
|
|
133
|
-
Verificación real del SDK 0.4.0, 01-10-2026: septiembre devolvió tres facturas recibidas con cobertura completa; una descarga devolvió 6.606 bytes ISO-8859-1 y una línea, con proveedor, receptor, folio y total coincidentes. Esto acredita ese piloto, no disponibilidad universal de XML.
|
|
134
|
-
|
|
135
|
-
## XML de facturas emitidas y recibidas
|
|
136
|
-
|
|
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.
|
|
138
|
-
|
|
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.
|
|
140
|
-
|
|
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.
|
|
142
|
-
|
|
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.
|
|
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
|
-
|
|
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.
|
|
148
|
-
|
|
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.
|
|
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
|
-
|
|
191
|
-
## Errores y recuperación
|
|
192
|
-
|
|
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.
|
|
194
|
-
|
|
195
|
-
Desde 0.4.3, las fallas del proveedor incluyen `description` en español y `diagnostics` opcionales. `message` sigue siendo igual a `code`, compatible con consumidores anteriores. El diagnóstico identifica `stage`, nombre conocido de `endpoint` y `reason`; `traceId` es un UUID nuevo por instancia, útil para correlacionar los logs de una operación. Cuando hay evidencia, agrega `responseType`, MIME permitido sin parámetros, `httpStatus` del proveedor (también 200), `siiMessageCode` numérico oficial, `siiResponseCode` del JSON y `attempts` en fallas de transporte/HTTP. No incluye URL, query, cuerpo, HTML, XML, RUT, folio, clave ni cookies. `sanitizeSiiDiagnostics` permite aplicar la misma lista permitida en un adaptador.
|
|
196
|
-
|
|
197
|
-
La descarga distingue rechazo por demasiados documentos (`DOCUMENT_LIMIT_EXCEEDED`), respuesta vacía (`EMPTY_RESPONSE`), ausencia indicada explícitamente (`DOCUMENT_NOT_FOUND`), HTML genérico (`HTML_RESPONSE`), página de error (`PROVIDER_ERROR_PAGE`), PDF/ZIP inesperados, XML inválido y documento de identidad distinta. HTML genérico y una respuesta vacía no demuestran que el XML no exista. PDF/ZIP describen lo recibido en esa solicitud; no significan que ése sea el único formato que SII o el proveedor puedan entregar. No se guardan ni se convierten esos archivos. Una respuesta nueva/no reconocida conserva un motivo de formato genérico, sin inventar una causa.
|
|
198
|
-
|
|
199
|
-
```ts
|
|
200
|
-
import { SiiError } from '@devly-cl/sii-client';
|
|
201
|
-
|
|
202
|
-
try {
|
|
203
|
-
await sii.getReceivedInvoiceXml(consulta);
|
|
204
|
-
} catch (error) {
|
|
205
|
-
if (error instanceof SiiError) {
|
|
206
|
-
// Campos saneados; jamás registrar credenciales ni el cuerpo del proveedor.
|
|
207
|
-
logger.warn({ code: error.code, description: error.description, diagnostics: error.diagnostics });
|
|
208
|
-
}
|
|
209
|
-
throw error;
|
|
210
|
-
} finally {
|
|
211
|
-
await sii.dispose();
|
|
212
|
-
}
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
- `LOGIN_NOT_CONFIRMED`: no hubo cookie de sesión; HTTP 200 por sí solo no confirma login.
|
|
216
|
-
- `PERSONAL_SESSION_REQUIRED` / `SESSION_IDENTITY_MISMATCH`: sesión de representación o identidad distinta; acceso rechazado.
|
|
217
|
-
- `COMPANY_NOT_AUTHORIZED`: empresa fuera de las autorizaciones SII del usuario.
|
|
218
|
-
- `SESSION_REQUIRED` / `NEW_INSTANCE_REQUIRED`: falta login válido o instancia ya usada/cerrada.
|
|
219
|
-
- `SESSION_OR_INTERACTIVE_AUTH_REQUIRED`: redirección o HTML donde se esperaba JSON; resolver sesión/intervención y crear otra instancia.
|
|
220
|
-
- `SII_TRANSPORT_ERROR` / `SII_HTTP_ERROR`: transporte o estado HTTP fallido.
|
|
221
|
-
- `SII_RETRY_LATER`: `Retry-After` mayor a 5 segundos; el backend puede reprogramar la lectura.
|
|
222
|
-
- `SII_SERVICE_ERROR` / `SII_PROTOCOL_CHANGED`: respuesta SII fallida o formato inesperado. HTML durante un respaldo XML (incluida la página «Error al contribuyente») es `SII_SERVICE_ERROR`, incluso con HTTP 200; no confirma ausencia del XML.
|
|
223
|
-
- `SII_INVALID_RESPONSE`: identidad, fecha, monto, tipo, límite o cantidad de factura inválida; también conflicto de valores para una misma identidad.
|
|
224
|
-
- `CAPTCHA_INTERACTION_REQUIRED`: SII solicita intervención de CAPTCHA (código 98); resolver interacción fuera del SDK.
|
|
225
|
-
- `SII_XML_UNAVAILABLE`: el servicio no entregó un XML para esa factura.
|
|
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`).
|
|
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.
|
|
238
|
-
|
|
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.
|
|
240
|
-
|
|
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.
|
|
242
|
-
|
|
243
|
-
## Límites y responsabilidades del consumidor
|
|
244
|
-
|
|
245
|
-
El SDK valida RUT, sesión personal y autorización SII por empresa. Cada backend implementa RBAC, mapeo tenant → empresa, permisos por recurso/sucursal, auditoría persistente, notificaciones in-app/correo y almacenamiento. RCV agrega datos empresariales: no exponer el resumen completo a un actor autorizado sólo para una sucursal.
|
|
246
|
-
|
|
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.
|
|
248
|
-
|
|
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.
|
|
250
|
-
|
|
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.
|
|
1
|
+
# SII Client
|
|
2
|
+
|
|
3
|
+
Cliente HTTP TypeScript para SII Chile, independiente de framework. Consulta RCV, facturas, XML y PDF; prepara, firma y envía documentos mediante el facturador gratuito.
|
|
4
|
+
|
|
5
|
+
**Node.js >=22.13 · CommonJS y ESM · Tipos TypeScript incluidos**
|
|
6
|
+
|
|
7
|
+
Utiliza servicios internos del portal SII, sujetos a cambios. No es una API oficial ni una integración certificada.
|
|
8
|
+
|
|
9
|
+
## Instalación
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
npm install @devly-cl/sii-client
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Uso
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
import { SiiClient, type SiiCredentials } from '@devly-cl/sii-client';
|
|
19
|
+
|
|
20
|
+
async function getInvoices(
|
|
21
|
+
authorizedCompanyRut: string,
|
|
22
|
+
credentials: SiiCredentials,
|
|
23
|
+
periodo: string,
|
|
24
|
+
) {
|
|
25
|
+
// El backend ya autorizó actor, tenant, empresa, recurso y sucursal.
|
|
26
|
+
const client = new SiiClient({ empresaRut: authorizedCompanyRut });
|
|
27
|
+
try {
|
|
28
|
+
await client.login(credentials);
|
|
29
|
+
return await client.getIssuedInvoices({ periodo });
|
|
30
|
+
} finally {
|
|
31
|
+
await client.dispose();
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
`credentials`: `{ rut, clave }`. `periodo`: `YYYYMM`, por ejemplo `202609`.
|
|
37
|
+
|
|
38
|
+
## API
|
|
39
|
+
|
|
40
|
+
| Método | Función |
|
|
41
|
+
| --- | --- |
|
|
42
|
+
| `login` | Acceso personal y validación de autorización sobre la empresa. |
|
|
43
|
+
| `getAuthorizedCompanies` | Empresas autorizadas en SII. |
|
|
44
|
+
| `getCompanyInfo` | Razón social, direcciones, comunas y giros de un receptor por RUT. |
|
|
45
|
+
| `getSummary` | Resumen RCV por período, operación y estado. |
|
|
46
|
+
| `getIssuedInvoices` / `getReceivedInvoices` | Facturas 33/34 normalizadas, con cobertura del período. |
|
|
47
|
+
| `getIssuedDocuments` / `getReceivedDocuments` | Documentos RCV 33/34/61 normalizados, con cobertura por tipo. |
|
|
48
|
+
| `getIssuedInvoiceXml` / `getReceivedInvoiceXml` | XML original y detalle de facturas 33/34. |
|
|
49
|
+
| `getIssuedDocumentXml` / `getReceivedDocumentXml` | XML original y detalle de documentos emitidos/recibidos 33/34/61. |
|
|
50
|
+
| `getIssuedInvoicePdf` / `getReceivedInvoicePdf` | PDF original 33/34 como stream `Readable` de Node.js. |
|
|
51
|
+
| `getDocumentStatus` | Recepción, coincidencia de contenido y anulación reportada. |
|
|
52
|
+
| `getDocumentRecipientEvents` | Eventos de facturas 33/34 como emisor o receptor. |
|
|
53
|
+
| `prepareInvoice` | Preparación revisable de una factura afecta 33. |
|
|
54
|
+
| `prepareCancellationCreditNote` | Preparación de NC 61 para anulación total de una factura 33. |
|
|
55
|
+
| `signAndSend` | Firma y envío del contenido aprobado. |
|
|
56
|
+
| `dispose` | Cierre de sesión y liberación de recursos. |
|
|
57
|
+
|
|
58
|
+
Las consultas RCV reciben `{ periodo, tokenRecaptcha? }` y devuelven `{ data, complete, expectedCount, observedAt, incompleteDocumentTypes }`. El XML recibido requiere `{ issuerRut, documentType, folio }`; conserva las referencias del documento.
|
|
59
|
+
|
|
60
|
+
Los nombres anteriores en español siguen disponibles como aliases de compatibilidad. La tabla describe este repositorio; las nuevas consultas de documentos RCV, XML recibido 33/34/61, estado y eventos no están incluidas en npm `0.6.0`.
|
|
61
|
+
|
|
62
|
+
## Integración
|
|
63
|
+
|
|
64
|
+
- Crear una instancia por empresa, identidad y operación. Usar acceso personal y esperar `dispose()` en `finally`; no compartir clientes autenticados entre tenants.
|
|
65
|
+
- Pasar credenciales sólo por parámetros y mantenerlas en memoria. No persistir secretos ni registrar cuerpos HTTP.
|
|
66
|
+
- El backend gestiona RBAC, permisos por recurso/sucursal, auditoría, notificaciones e idempotencia. RCV contiene datos de toda la empresa: un permiso de sucursal no autoriza automáticamente su consulta completa.
|
|
67
|
+
- `complete`, `expectedCount` e `incompleteDocumentTypes` sólo cubren los tipos consultados: 33/34 en facturas, 33/34/61 en documentos. Comparar con `getSummary` para detectar otros tipos pendientes; no acreditan cobertura fiscal total. La identidad es `issuerRut + documentType + folio`.
|
|
68
|
+
- Consumir o destruir el stream PDF antes de cerrar el cliente. Ver [ejemplo HTTP](examples/consulta-pdf.ts).
|
|
69
|
+
|
|
70
|
+
## Emisión
|
|
71
|
+
|
|
72
|
+
Preparar → revisar y aprobar `contentHash` → firmar y enviar. `beforeSend` es obligatorio: debe confirmar almacenamiento duradero del XML firmado y su identidad antes del envío. Ver [ejemplo de integración](examples/facturacion.ts) y [campos opcionales](examples/factura-opcionales.ts).
|
|
73
|
+
|
|
74
|
+
Ante `SII_ISSUANCE_OUTCOME_UNKNOWN`, bloquear una nueva emisión y reconciliar con el documento respaldado. `ENVIADO` confirma el envío observado; no acredita aceptación fiscal. Las consultas de estado mantienen `fiscalVerdict: 'NOT_OBSERVED'`.
|
|
75
|
+
|
|
76
|
+
## Errores
|
|
77
|
+
|
|
78
|
+
Entradas inválidas generan `TypeError`. Fallos de sesión, proveedor o protocolo generan `SiiError` con `code`, `description` y `diagnostics` opcionales saneados.
|
|
79
|
+
|
|
80
|
+
Sólo lecturas conocidas admiten reintentos automáticos. Login, selección de empresa, preparación, firma y envío no se reintentan. CAPTCHA requiere intervención del consumidor.
|
|
81
|
+
|
|
82
|
+
## Referencias
|
|
83
|
+
|
|
84
|
+
- [Ejemplos de integración](examples/)
|
|
85
|
+
- [Protocolo y evidencia de verificación](docs/sii/)
|
|
86
|
+
- [Migración de nombres de API](docs/sii/QA-API-ENGLISH.md)
|
|
87
|
+
|
|
88
|
+
## Desarrollo
|
|
89
|
+
|
|
90
|
+
```sh
|
|
91
|
+
npm ci
|
|
92
|
+
npm run check
|
|
93
|
+
npm pack
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
`check` valida tipos, build, integración HTTP simulada, autorización y ejemplos. Licencia: `UNLICENSED`.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import { type BoundDocumentStatusQuery, type BoundRecipientEventsQuery, type DocumentQueryOptions, type DocumentStatusQuery, type DocumentStatusResult, type DocumentVerification, type RecipientEventsQuery, type RecipientEventsResult, type RecipientEventsObservation } from '../domain/document-status';
|
|
2
|
+
export interface DocumentReadPort {
|
|
3
|
+
readonly companyRut: string;
|
|
4
|
+
assertReady(): void;
|
|
5
|
+
status(query: BoundDocumentStatusQuery, options?: DocumentQueryOptions): Promise<DocumentVerification>;
|
|
6
|
+
recipientEvents(query: BoundRecipientEventsQuery, options?: DocumentQueryOptions): Promise<RecipientEventsObservation>;
|
|
7
|
+
}
|
|
8
|
+
export declare class DocumentQueries {
|
|
9
|
+
private readonly port;
|
|
10
|
+
constructor(port: DocumentReadPort);
|
|
11
|
+
getDocumentStatus(query: DocumentStatusQuery, options?: DocumentQueryOptions): Promise<DocumentStatusResult>;
|
|
12
|
+
getDocumentRecipientEvents(query: RecipientEventsQuery, options?: DocumentQueryOptions): Promise<RecipientEventsResult>;
|
|
13
|
+
}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.DocumentQueries = void 0;
|
|
4
|
+
const document_status_1 = require("../domain/document-status");
|
|
5
|
+
const rut_1 = require("../domain/rut");
|
|
6
|
+
class DocumentQueries {
|
|
7
|
+
port;
|
|
8
|
+
constructor(port) {
|
|
9
|
+
this.port = port;
|
|
10
|
+
}
|
|
11
|
+
async getDocumentStatus(query, options) {
|
|
12
|
+
this.port.assertReady();
|
|
13
|
+
const bound = (0, document_status_1.bindDocumentStatusQuery)(this.port.companyRut, query);
|
|
14
|
+
(0, document_status_1.assertDocumentQueryOptions)(options);
|
|
15
|
+
const result = await this.port.status(bound, options);
|
|
16
|
+
const verification = result.verification === 'RECEIVED_MATCH'
|
|
17
|
+
? { verification: result.verification, cancellation: result.cancellation }
|
|
18
|
+
: { verification: result.verification, cancellation: 'UNCONFIRMED' };
|
|
19
|
+
return {
|
|
20
|
+
...verification,
|
|
21
|
+
document: { issuerRut: bound.issuerRut, receiverRut: bound.receiverRut, documentType: bound.documentType, folio: bound.folio },
|
|
22
|
+
fiscalVerdict: 'NOT_OBSERVED', source: 'SII_CONTENT_QUERY', observedAt: new Date().toISOString(),
|
|
23
|
+
};
|
|
24
|
+
}
|
|
25
|
+
async getDocumentRecipientEvents(query, options) {
|
|
26
|
+
this.port.assertReady();
|
|
27
|
+
const bound = (0, document_status_1.bindRecipientEventsQuery)(this.port.companyRut, query);
|
|
28
|
+
(0, document_status_1.assertDocumentQueryOptions)(options);
|
|
29
|
+
const result = await this.port.recipientEvents(bound, options);
|
|
30
|
+
(0, document_status_1.assertRecipientEventsAccess)(bound, result);
|
|
31
|
+
return {
|
|
32
|
+
document: {
|
|
33
|
+
issuerRut: bound.issuerRut, receiverRut: bound.direction === 'RECEIVED' ? bound.companyRut : (0, rut_1.parseRut)(result.document.receiverRut).formatted,
|
|
34
|
+
documentType: bound.documentType, folio: bound.folio,
|
|
35
|
+
},
|
|
36
|
+
siiReceivedAtLocal: result.siiReceivedAtLocal, timeZone: null,
|
|
37
|
+
indicators: {
|
|
38
|
+
paidInCashReported: result.indicators.paidInCashReported,
|
|
39
|
+
claimsReported: result.indicators.claimsReported,
|
|
40
|
+
acknowledgementsReported: result.indicators.acknowledgementsReported,
|
|
41
|
+
},
|
|
42
|
+
events: result.events.map(event => ({
|
|
43
|
+
code: event.code, kind: event.kind, description: event.description,
|
|
44
|
+
occurredAtLocal: event.occurredAtLocal, responsibleRut: event.responsibleRut,
|
|
45
|
+
})),
|
|
46
|
+
source: 'SII_RECIPIENT_REGISTRY', observedAt: new Date().toISOString(),
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
exports.DocumentQueries = DocumentQueries;
|
|
@@ -1,17 +1,23 @@
|
|
|
1
1
|
import { type IssuedInvoice, type IssuedInvoicesQuery, type IssuedInvoicesResult, type InvoiceDocumentType } from '../domain/issued-invoice';
|
|
2
|
-
|
|
2
|
+
import type { RcvDocument, RcvDocumentType, RcvDocumentsQuery, RcvDocumentsResult } from '../domain/rcv-document';
|
|
3
|
+
export interface DocumentReadPort<D extends RcvDocumentType, T extends RcvDocument> {
|
|
3
4
|
initialLimit(): Promise<number>;
|
|
4
5
|
counts(): Promise<{
|
|
5
|
-
documentType:
|
|
6
|
+
documentType: D;
|
|
6
7
|
count: number;
|
|
7
8
|
}[]>;
|
|
8
|
-
details(type:
|
|
9
|
+
details(type: D, tokenRecaptcha: string): Promise<T[]>;
|
|
9
10
|
}
|
|
11
|
+
export type InvoiceReadPort<T extends IssuedInvoice> = DocumentReadPort<InvoiceDocumentType, T>;
|
|
10
12
|
export declare class InvoiceQueryError extends Error {
|
|
11
13
|
readonly section: 'SUMMARY' | 'DETAIL';
|
|
12
14
|
constructor(section: 'SUMMARY' | 'DETAIL');
|
|
13
15
|
}
|
|
14
|
-
|
|
15
|
-
export declare function readInvoices<T extends IssuedInvoice>(port: InvoiceReadPort<T>, { periodo, tokenRecaptcha }: IssuedInvoicesQuery): Promise<Omit<IssuedInvoicesResult, 'data'> & {
|
|
16
|
+
export declare function readInvoices<T extends IssuedInvoice>(port: InvoiceReadPort<T>, query: IssuedInvoicesQuery): Promise<Omit<IssuedInvoicesResult, 'data'> & {
|
|
16
17
|
data: T[];
|
|
17
18
|
}>;
|
|
19
|
+
/** Coverage and identity reconciliation operate on normalized documents, never provider rows. */
|
|
20
|
+
export declare function readDocuments<D extends RcvDocumentType, T extends RcvDocument>(port: DocumentReadPort<D, T>, { periodo, tokenRecaptcha }: RcvDocumentsQuery): Promise<Omit<RcvDocumentsResult, 'data' | 'incompleteDocumentTypes'> & {
|
|
21
|
+
data: T[];
|
|
22
|
+
incompleteDocumentTypes: D[];
|
|
23
|
+
}>;
|
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.InvoiceQueryError = void 0;
|
|
4
4
|
exports.readInvoices = readInvoices;
|
|
5
|
+
exports.readDocuments = readDocuments;
|
|
5
6
|
const issued_invoice_1 = require("../domain/issued-invoice");
|
|
6
7
|
class InvoiceQueryError extends Error {
|
|
7
8
|
section;
|
|
@@ -11,8 +12,11 @@ class InvoiceQueryError extends Error {
|
|
|
11
12
|
}
|
|
12
13
|
}
|
|
13
14
|
exports.InvoiceQueryError = InvoiceQueryError;
|
|
14
|
-
|
|
15
|
-
|
|
15
|
+
function readInvoices(port, query) {
|
|
16
|
+
return readDocuments(port, query);
|
|
17
|
+
}
|
|
18
|
+
/** Coverage and identity reconciliation operate on normalized documents, never provider rows. */
|
|
19
|
+
async function readDocuments(port, { periodo, tokenRecaptcha = 't-o-k-e-n-web' }) {
|
|
16
20
|
(0, issued_invoice_1.assertPeriod)(periodo);
|
|
17
21
|
if (typeof tokenRecaptcha !== 'string' || !tokenRecaptcha.trim())
|
|
18
22
|
throw new TypeError('tokenRecaptcha inválido');
|
|
@@ -28,24 +32,24 @@ async function readInvoices(port, { periodo, tokenRecaptcha = 't-o-k-e-n-web' })
|
|
|
28
32
|
throw new InvoiceQueryError('SUMMARY');
|
|
29
33
|
expected.set(type, count);
|
|
30
34
|
}
|
|
31
|
-
const
|
|
35
|
+
const documents = new Map();
|
|
32
36
|
const incompleteDocumentTypes = [];
|
|
33
37
|
for (const [type, count] of expected) {
|
|
34
38
|
if (count === 0)
|
|
35
39
|
continue;
|
|
36
40
|
let uniqueCount = 0;
|
|
37
|
-
for (const
|
|
38
|
-
const key = `${
|
|
39
|
-
const previous =
|
|
40
|
-
if (previous && JSON.stringify(previous) !== JSON.stringify(
|
|
41
|
+
for (const document of await port.details(type, tokenRecaptcha)) {
|
|
42
|
+
const key = `${document.issuerRut}:${document.documentType}:${document.folio}`;
|
|
43
|
+
const previous = documents.get(key);
|
|
44
|
+
if (previous && JSON.stringify(previous) !== JSON.stringify(document))
|
|
41
45
|
throw new InvoiceQueryError('DETAIL');
|
|
42
46
|
if (!previous) {
|
|
43
|
-
|
|
47
|
+
documents.set(key, document);
|
|
44
48
|
uniqueCount++;
|
|
45
49
|
}
|
|
46
50
|
}
|
|
47
51
|
if (count > limit || uniqueCount !== count)
|
|
48
52
|
incompleteDocumentTypes.push(type);
|
|
49
53
|
}
|
|
50
|
-
return { data: [...
|
|
54
|
+
return { data: [...documents.values()], complete: incompleteDocumentTypes.length === 0, expectedCount, observedAt: new Date().toISOString(), incompleteDocumentTypes };
|
|
51
55
|
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/** Datos observados al consultar un receptor en el facturador gratuito. */
|
|
2
|
+
export interface CompanyInfo {
|
|
3
|
+
rut: string;
|
|
4
|
+
legalName: string;
|
|
5
|
+
addresses: {
|
|
6
|
+
address: string;
|
|
7
|
+
commune: string;
|
|
8
|
+
}[];
|
|
9
|
+
/** Descripciones de giro; no se infieren códigos de actividad económica. */
|
|
10
|
+
businessActivities: string[];
|
|
11
|
+
source: 'SII_FACTURADOR';
|
|
12
|
+
observedAt: string;
|
|
13
|
+
}
|