API del portal (dte-sdk/portal)

import { createPortalClient, openPortalSession, queryFolioQuota } from 'dte-sdk/portal'

// Qué significa cada rechazo y qué hacer, en español, para el operador.
const PORTAL_REJECTIONS: Readonly<Record<PortalRejection, string>>
 
// El mensaje en español de un rechazo.
function portalRejectionMessage(rejection: PortalRejection): string

// Valida y completa las opciones en un `PortalClient` congelado.
function createPortalClient(options: PortalClientOptions): PortalClient
 
// Política de reintentos del portal: 4 intentos a los 2, 4 y 8 s, sin jitter, repitiendo lo que
// acepta `isRetryablePortalError`.
const DEFAULT_PORTAL_RETRY_POLICY: RetryPolicy
 
// True para lo que conviene repetir en el portal: fallas de transporte, timeouts, HTTP
// 502/503/504, y las fallas TLS que el SII produce de forma intermitente con certificado cliente
// (`EPROTO … rsa_pss`), que no indican un certificado malo.
function isRetryablePortalError(error: unknown): boolean

// Exclusión mutua por clave dentro de un proceso.
function createMemoryPortalLock(): PortalLock

// Abre una sesión de forma explícita, reutilizando una en caché que siga viva, según lo dice la
// página de empresa del ambiente del cliente (`ad_empresa1`). Las demás operaciones no lo
// necesitan: inician sesión a pedido.
function openPortalSession(
  portal: PortalClient,
  overrides?: CallOverrides,
): Promise<PortalSessionInfo>
 
// Cierra la sesión para devolver su cupo y siempre borra la sesión en caché. Un cierre fallido
// solo se registra: de todos modos el SII vence la sesión por su cuenta.
function closePortalSession(portal: PortalClient, overrides?: CallOverrides): Promise<void>

// Lee la resolución de una empresa. Es por ambiente: certificación y producción responden fechas y
// números distintos para un mismo RUT, y el par equivocado hace que se rechace un envío con "Error
// en Carátula".
function fetchCompanyResolution(
  portal: PortalClient,
  input?: { readonly companyRut?: string; readonly environment?: Environment; },
  overrides?: CallOverrides,
): Promise<CompanyResolution>
 
// Lee los datos del contribuyente: nombre, domicilio separado en sus partes, actividades y
// sucursales.
function fetchTaxpayerData(
  portal: PortalClient,
  input?: { readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<TaxpayerData>
 
// Lee la resolución y los datos del contribuyente en secuencia y los combina. En paralelo, una
// respuesta pisa la cookie del balanceador que la otra necesita y `ad_empresa2` responde vacío.
function fetchIssuerProfile(
  portal: PortalClient,
  input?: { readonly companyRut?: string; readonly environment?: Environment; },
  overrides?: CallOverrides,
): Promise<IssuerProfile>

// Lee el estado de cada set de pruebas y libro, en el host de certificación. Solo lee: declarar
// avance es `declareProgress`.
function queryCertificationSets(
  portal: PortalClient,
  input?: { readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<CertificationSets>

// Lista los tipos de documento que el portal ofrece para timbraje con esta empresa. Una página de
// error no es "sin tipos": una página sin selector y sin rechazo declarado lanza.
function listStampableTypes(
  portal: PortalClient,
  input?: { readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<readonly StampableType[]>
 
// Lee cuántos folios autoriza el SII para un tipo, deteniéndose en el formulario que lo muestra:
// no se timbra nada y el cupo no se mueve. `MAX_AUTOR` y `FOLIOS_DISP` aparecen solo mientras el
// SII raciona el tipo. El formulario es el que tiene el tipo elegido en su selector: la página de la
// empresa, sin tipo elegido, se recarga con él, y una última página que no es ese formulario lanza
// `SII_PORTAL_SESSION_EXPIRED` o `SII_PORTAL_UNEXPECTED_PAGE` en vez de leerse como un tipo sin racionar.
function queryFolioQuota(
  portal: PortalClient,
  input: { readonly type: DocumentType; readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<FolioQuota>
 
// Solicita un rango de folios y descarga su CAF por los cinco pasos del portal. Un rechazo puede
// llegar en cualquier paso. Si se excede el máximo efectivo y no hay `minQuantity`, pide una vez
// más por un folio. Si el SII responde la solicitud con el formulario de solicitud otra vez, no se
// envía nada de nuevo: lanza `SII_PORTAL_REJECTED` con `stampingUncertain`, porque los folios pudieron
// otorgarse, y `listReobtainableRanges` dice si se otorgaron.
function requestCaf(
  portal: PortalClient,
  input: CafRequestInput,
  overrides?: CallOverrides,
): Promise<ObtainedCaf>

// Lista los rangos sin usar de un tipo de documento, siguiendo las páginas del listado. No cambia
// nada.
function listFolioRanges(
  portal: PortalClient,
  input: { readonly type: DocumentType; readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<FolioRanges>
 
// Anula folios sin usar: hasta cuatro pasadas por el listado, por rango y folio por folio cuando
// parte del rango ya se anuló o se recibió, deteniendo una pasada tras dos negativas reales
// seguidas. Un folio solo conserva la respuesta del SII. Cuando el SII ya respondió por algunos
// folios, un `DteError` que termina el recorrido (una sesión vencida, un bloqueo, la cancelación de
// quien llama, un listado posterior rechazado o ilegible) vuelve en `failure`, con lo hecho hasta
// entonces; un rango que nunca llegó (`transport`) no es respuesta, y antes de cualquier respuesta
// el error se lanza. Un rango respondido folio por folio vuelve en tan pocas piezas como lo
// permitan sus respuestas, y un recorrido cortado en un folio conserva los folios respondidos antes.
function annulFolios(
  portal: PortalClient,
  input: AnnulFoliosInput,
  overrides?: CallOverrides,
): Promise<AnnulmentResult>

// Lista los rangos autorizados que el SII deja volver a descargar. Los rangos anulados aparecen
// sin marcar, así que saber cuáles lo son cuesta una petición por rango. Al trámite se entra como a
// los demás, con login a pedido y la pantalla de representación. Solo un listado da una lista, vacía
// si no tiene rangos: una página que declara un rechazo lanza `SII_PORTAL_REJECTED`, una de ingreso
// `SII_PORTAL_SESSION_EXPIRED` y cualquier otra `SII_PORTAL_UNEXPECTED_PAGE`.
function listReobtainableRanges(
  portal: PortalClient,
  input: { readonly type: DocumentType; readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<readonly ReobtainableRange[]>
 
// Descarga el CAF de un rango ya autorizado. No gasta cupo. Primero se entra al trámite, como entra
// `listReobtainableRanges`, con login a pedido, así que una sesión en caché que venció después del
// listado inicia sesión de nuevo en vez de enviar el rango con ella. Una página que declara un
// rechazo en la entrada lanza `SII_PORTAL_REJECTED` y cualquier otra que no es el trámite
// `SII_PORTAL_UNEXPECTED_PAGE`, antes de enviar nada; una página de ingreso en cualquier paso lanza
// `SII_PORTAL_SESSION_EXPIRED`, nunca el rechazo de un paso.
function reobtainCaf(
  portal: PortalClient,
  input: { readonly type: DocumentType; readonly range: ReobtainableRange; },
  overrides?: CallOverrides,
): Promise<ObtainedCaf>

// Solicita un CAF que cubra toda la cantidad; bajo ella no se timbra nada. Con `allowAnnul`, una
// vez que el SII respondió la anulación, un `DteError` que la corta, o uno de la solicitud que se
// repite después, termina el flujo con `rejection: null`, el cupo de la primera solicitud, la falla
// en `failure` y lo anulado en `knownAnnulled`; tras una anulación cortada no se vuelve a pedir.
// Antes de la primera respuesta de la anulación, lanza.
function requestCafExact(
  portal: PortalClient,
  input: RequestCafExactInput,
  overrides?: CallOverrides,
): Promise<RequestCafExactResult>
 
// Cubre una cantidad con varios CAF, para cuando `FOLIOS_DISP` es 0 y `MAX_AUTOR` es chico: el SII
// raciona por historial, no hay nada que anular ni reobtener, y esperar no lo mueve. Un rechazo
// vuelve con su propio tipo y `portalMessage`, en el primer viaje o en uno posterior; después de una
// entrega, solo un folio por sobre el máximo (`quotaExceeded`) se lee como `quotaCapReached`. Con un
// CAF ya en la mano, un viaje posterior que falla con un `DteError`
// que no es un rechazo (una falla de transporte, un tiempo agotado, una sesión vencida, un bloqueo,
// `CAF_INVALID`, la cancelación de quien llama) termina el flujo con los CAF obtenidos, el último
// cupo visto y la falla en `failure`; sin un CAF en la mano, lanza. `quantity` debe ser un entero
// de al menos 1, o lanza `INVALID_OPTION` antes de que salga nada.
function requestCafInBatches(
  portal: PortalClient,
  input: RequestCafInBatchesInput,
  overrides?: CallOverrides,
): Promise<FolioFlowResult>
 
// Cubre una cantidad con rangos autorizados sin gastar cupo, partiendo por el folio más antiguo.
// Es lo que levanta un bloqueo de timbraje, porque el SII pide emitir folios. El listado inicia
// sesión a pedido, y cualquier fallo al listar (un rechazo, una sesión vencida, una página que no es
// el listado) se lee como sin rangos, con el fallo en `reason`: no lanza. Una descarga rechazada se
// registra y se sigue. Con un CAF ya en la mano, una descarga que falla con cualquier otro
// `DteError` (una falla de transporte, un tiempo agotado, una sesión vencida, un bloqueo, la
// cancelación de quien llama) termina el recorrido con los CAF descargados, el mensaje de la falla
// en `reason` y la falla en `failure`; sin un CAF en la mano, lanza. Una página de ingreso en
// respuesta al rango o al archivo es una sesión vencida, no una descarga rechazada.
function reobtainFolios(
  portal: PortalClient,
  input: ReobtainFoliosInput,
  overrides?: CallOverrides,
): Promise<ReobtainResult>

// Cambia el tipo de compra de un documento. En producción esto cambia el registro real.
function changePurchaseType(
  portal: PortalClient,
  input: ChangePurchaseTypeInput,
  overrides?: CallOverrides,
): Promise<void>
 
// Una compra tal como la tiene el registro, incluido su tipo de compra vigente.
function fetchPurchaseDocument(
  portal: PortalClient,
  key: PurchaseDocumentKey,
  overrides?: CallOverrides,
): Promise<PurchaseDocument | null>
 
// Los totales oficiales de un período por tipo de documento y estado contable, incluido lo que el
// SII agrega, como las boletas. No se miran los códigos de respuesta, así que un mes que el SII se
// niega a mostrar se lee como uno vacío.
function fetchRegisterSummary(
  portal: PortalClient,
  input: RegisterSummaryInput,
  overrides?: CallOverrides,
): Promise<RegisterSummary>
 
// Todos los documentos de un período, sin XML: el resumen por tipo y luego una llamada de detalle
// por fila, al mismo tiempo. Este no es el registro oficial. No se miran los códigos de respuesta,
// así que un mes que el SII se niega a mostrar se lee como uno vacío.
function listPeriodDocuments(
  portal: PortalClient,
  input: ListPeriodDocumentsInput,
  overrides?: CallOverrides,
): Promise<PeriodDocuments>
 
// Los tipos de compra que el SII permite darle a un documento.
function listPurchaseTypes(
  portal: PortalClient,
  overrides?: CallOverrides,
): Promise<readonly PurchaseType[]>
 
// Mueve el IVA de un documento de recuperable a uso común. En producción esto cambia el registro
// real.
function moveVatToCommonUse(
  portal: PortalClient,
  input: MoveVatInput,
  overrides?: CallOverrides,
): Promise<void>
 
// Mueve el IVA de un documento de uso común de vuelta a recuperable: lo inverso de
// `moveVatToCommonUse`, con las mismas reglas. Al devolver todo, `commonUseVat` queda en 0 y
// `recoverableVat` lleva el total.
function moveVatToRecoverable(
  portal: PortalClient,
  input: MoveVatInput,
  overrides?: CallOverrides,
): Promise<void>

import { REGISTER_ACCOUNTING_STATUSES, REGISTER_DOCUMENT_CODES, registerDocumentCode } from 'dte-sdk/portal'
 
registerDocumentCode(61)?.sign // -1: una nota de crédito resta de los totales
registerDocumentCode(52)?.inRegister // false: las guías de despacho nunca llegan al registro
registerDocumentCode(71) // undefined: no es uno de los 49 códigos
REGISTER_DOCUMENT_CODES.length // 49
REGISTER_ACCOUNTING_STATUSES.sale // ['registered']

// Los 49 códigos de documento del registro de compras y ventas, ordenados por código.
const REGISTER_DOCUMENT_CODES: readonly RegisterDocumentCode[]
 
// Lo que el registro hace con un código de documento, o `undefined` si el código no es uno de los 49.
function registerDocumentCode(code: number): RegisterDocumentCode | undefined
 
// Los estados contables que puede tener cada lado del registro: los cuatro en compras, solo
// `registered` en ventas, porque ninguna fuente del SII describe otros estados de una venta.
const REGISTER_ACCOUNTING_STATUSES: Readonly<Record<RegisterOperation, readonly AccountingStatus[]>>

// Descarga desde el respaldo MIPYME el XML de los documentos emitidos o recibidos de un rango de
// fechas, partiendo el rango hasta que cada tramo quepa en los 20 documentos por descarga que
// permite el SII.
function downloadMipymeBackup(
  portal: PortalClient,
  input: MipymeBackupInput,
  overrides?: CallOverrides,
): Promise<MipymeBackup>

import { listAccreditationDocuments, unstable_fetchActivityVerification } from 'dte-sdk/portal'
 
const { requests, messages } = await unstable_fetchActivityVerification(portal)
requests.length // 0 si la empresa nunca pidió la verificación
requests[0]?.status // 'PAC', descrito como 'PENDIENTE DE ACREDITACIÓN'
requests[0]?.preliminaryResult // 'CONDICIONADA'
requests[0]?.finalResult // null mientras no lo hay
requests[0]?.requestedOn // 'AAAA-MM-DD'
messages.filter((message) => message.blocking) // los mensajes en que se detiene la página del propio SII
 
const documents = await listAccreditationDocuments(portal)
documents[0] // { category: 'general', code: 1, description: '…' }

// Inestable: su forma puede cambiar en cualquier versión, incluso un patch. La verificación de
// actividades de la empresa, la "Consulta estado de verificación y acreditación" del SII. Envía el
// RUT de la empresa, no el de la sesión, y una solicitud de otro RUT lanza en vez de pasar como de
// la empresa. Lee producción sea cual sea el ambiente del cliente. Los funcionarios, los
// comentarios y el domicilio nunca salen.
function unstable_fetchActivityVerification(
  portal: PortalClient,
  input?: ActivityVerificationInput,
  overrides?: CallOverrides,
): Promise<ActivityVerification>
 
// Los tipos de documento que el SII acepta para acreditar una actividad, en el orden del SII: una
// lista general y una específica, cuyos códigos se repiten. Lee producción sea cual sea el ambiente
// del cliente.
function listAccreditationDocuments(
  portal: PortalClient,
  overrides?: CallOverrides,
): Promise<readonly AccreditationDocument[]>

// Primeros 12 caracteres hexadecimales del SHA-256 de un archivo CAF, para distinguir dos archivos
// de un mismo rango.
function cafFingerprint(xml: string): string
 
// Un registro sobre un almacén. Las llamadas corren una tras otra dentro de este proceso, cada una
// leyendo el libro de nuevo; varios procesos necesitan un almacén o un registro propio que se haga
// cargo.
function createFolioRegistry(store: FolioLedgerStore, now?: () => Date): FolioRegistry
 
// Un registro que vive en memoria: para tests y corridas cortas.
function createMemoryFolioRegistry(now?: () => Date): FolioRegistry

// Tipos de set que puede traer el texto del set de pruebas del SII, por su nombre en inglés.
const TEST_SET_KINDS: {
  readonly basic: "basic"
  readonly exempt: "exempt"
  readonly guide: "guide"
  readonly purchase: "purchase"
  readonly export: "export"
  readonly settlement: "settlement"
  readonly salesBook: "salesBook"
  readonly purchaseBook: "purchaseBook"
  readonly exemptPurchaseBook: "exemptPurchaseBook"
  readonly guideBook: "guideBook"
  readonly other: "other"
}
 
// Nombres de los sets y libros tal como los lista el portal de certificación (`pe_avance2`).
const TEST_SET_PORTAL_NAMES: Readonly<Partial<Record<TestSetKind, string>>>
 
// `TpoDocRef` — El tipo de documento de referencia que lleva cada documento del set en su primera
// referencia: `SET`.
const TEST_SET_REFERENCE_TYPE = 'SET'
 
// La contraparte de cada línea de los libros de compras de certificación: el RUT del propio SII y
// un nombre de relleno. El SII lo acepta, existe como contribuyente y no es dato personal de
// nadie.
const CERTIFICATION_COUNTERPARTY: { readonly rut: "60803000-K"; readonly name: "Razon Social" }

// Parsea el texto del set de pruebas del SII: sets, sus casos con ítems y referencias, los
// documentos de proveedor de los sets de libro de compras y el factor de proporcionalidad.
function parseTestSetText(text: string): readonly TestSet[]

// Los casos que emite cada set, con los folios que necesita cada tipo de documento, a partir de
// los sets parseados. Por cada tipo gana el último set del texto.
function planCertificationSets(sets: readonly TestSet[]): CertificationPlan

// Una fuente de folios sobre uno o varios CAF: un contador por CAF, gana el primer CAF del tipo
// con folio libre, un folio nunca se entrega dos veces, y el CAF devuelto es el que contiene el
// folio en su rango, así timbra con su propia llave.
function createFolioAllocator(cafs: readonly Caf[], options?: FolioAllocatorOptions): FolioSource

// Emite cada documento del plan de un set y firma su sobre.
function issueTestSet(plan: IssuableSetPlan, options: IssueSetOptions): Promise<IssuedSet>
 
// `SetDTE/@ID` de cada sobre de certificación.
const TEST_SET_ENVELOPE_ID = 'DTE_SetDoc'

// Reemite cada caso de los cuatro planes con folios nuevos, en el orden básico, exento, guías y
// compra, y firma un solo sobre con todos.
function issueSimulation(
  plan: CertificationPlan,
  options: IssueSetOptions,
): Promise<IssuedSimulation>

// El libro de ventas de la certificación: solo las facturas y notas del set básico, con fecha 15
// del período, el cliente como contraparte, todo monto presente (0 si falta) y la tasa de IVA en
// cada línea.
function createCertificationSalesBook(
  set: IssuedSet | SalesBookSource,
  input: CertificationSalesBookInput,
): SignedPurchaseSalesBook
 
// Un libro de compras de la certificación desde un set de libro de compras: una línea por
// documento de proveedor con la contraparte de relleno del SII, el IVA al 19 % del afecto, IVA de
// uso común, IVA no recuperable en entregas gratuitas, la retención de una factura de compra, el
// folio referido de una nota tomado de su observación y, en el libro para exentos, IVA no
// recuperable en toda línea afecta, la factura exenta en papel como tipo 32 y notas que heredan
// los montos del documento que refieren.
function createCertificationPurchaseBook(
  plan: PurchaseBookPlan,
  input: CertificationBookInput,
): SignedPurchaseSalesBook
 
// El libro de guías de la certificación: solo las guías del set de guías, con su tipo de traslado
// y fecha de emisión; por posición la segunda lleva `Operacion` 1 y la tercera va anulada
// (`Anulado` 2, total 0 y nada más), salvo que `caseFlags` diga otra cosa; una venta lleva el
// cliente, el neto, la tasa y el IVA; toda guía su total.
function createCertificationGuideBook(
  set: IssuedSet | GuideBookSource,
  input: CertificationGuideBookInput,
): SignedGuideBook

// Los sets en el orden en que se envían.
const SET_KEYS: readonly SetKey[] = ['basic', 'guide', 'exempt', 'purchase']
 
// Los libros en el orden en que se envían.
const BOOK_KEYS: readonly BookKey[] = ['purchaseBook', 'salesBook', 'guideBook', 'exemptPurchaseBook']
 
// Los libros que toda certificación debe tener aprobados.
const MANDATORY_BOOK_KEYS: readonly BookKey[] = ['purchaseBook', 'salesBook', 'guideBook']
 
// `FILE` — El nombre de archivo con que viaja cada libro en el envío, como lo espera el SII.
const BOOK_FILE_NAMES: Readonly<Record<BookKey, string>> = {
  salesBook: 'LibroCV.xml',
  purchaseBook: 'LibroCV.xml',
  exemptPurchaseBook: 'LibroCVExentos.xml',
  guideBook: 'LibroGuia.xml',
}
 
// El nombre de artefacto de cada libro.
const BOOK_ARTEFACT_NAMES: Readonly<Record<BookKey, string>> = {
  salesBook: 'libro-ventas.xml',
  purchaseBook: 'libro-compras.xml',
  exemptPurchaseBook: 'libro-compras-exentos.xml',
  guideBook: 'libro-guias.xml',
}
 
// El nombre de artefacto del sobre de cada set.
const SET_ARTEFACT_NAMES: Readonly<Record<SetKey, string>>
 
// `SETnn` — Los sets opcionales marcados al descargar el set de pruebas: guías (03), facturas
// exentas (06), los libros de ventas (07), compras (08) y guías (09), el libro de compras para
// exentos (15) y el set de factura de compra (72).
const DEFAULT_OPTIONAL_SETS: readonly string[] = ['SET03', 'SET06', 'SET07', 'SET08', 'SET09', 'SET15', 'SET72']
 
// Las etapas de una certificación, en orden, como las lleva el ejecutor.
const CERTIFICATION_STAGES: readonly [
  "testSets", "books", "simulation", "exchange", "printedSamples", "compliance", "done"
]
 
// Las palabras con que el portal nombra una etapa (`pe_avance6`, "paso <b>…</b>"), de la última
// hacia atrás. Cualquier texto posterior al intercambio cae en `printedSamples`: la declaración de
// cumplimiento dice si las muestras ya están aprobadas.
const PORTAL_STAGE_WORDS: readonly { readonly stage: CertificationStage; readonly words: readonly string[] }[]
 
// Los nombres de los eventos de progreso que emiten los pasos.
const CERTIFICATION_STEPS: readonly [
  "SETS_DOWNLOADING", "SETS_LOADED", "SETS_REGENERATED", "CAF_REQUESTING", "CAF_OK", "SET_START",
  "SET_OK", "SET_ERROR", "SETS_DECLARING", "SETS_DECLARED", "POLLING", "SETS_APPROVED",
  "SETS_REJECTED", "BOOKS_START", "BOOK_SKIPPED", "BOOK_SENDING", "BOOK_OK", "BOOK_ERROR",
  "BOOK_PERIOD_RETRY", "BOOKS_DECLARING", "BOOKS_DONE", "ADVANCE_WAITING", "ADVANCE_DONE",
  "SIM_START", "SIM_SENDING", "SIM_OK", "SIM_DECLARING", "SIM_DONE", "INTERCAMBIO_START",
  "INTERCAMBIO_DESCARGADO", "INTERCAMBIO_DONE", "MUESTRAS_UPLOADING", "MUESTRAS_DONE", "CERT_DONE",
  "CERT_ERROR"
]

// Descarga el set de pruebas desde `pe_generar`. Sin sesión en la caché se lee primero la página
// de avance, lo que inicia sesión y deja que el SII refresque la postulación; responda lo que
// responda esa lectura, la descarga sigue.
function downloadTestSet(
  portal: PortalClient,
  input?: DownloadTestSetInput,
  overrides?: CallOverrides,
): Promise<DownloadedTestSet>
 
// Declara el track id y la fecha de envíos en `pe_avance2`, enviado a `pe_avance3`. Del formulario
// se leen los campos ocultos y el índice del campo de cada fila, buscada por su etiqueta (los
// índices se mueven al aprobarse sets).
function declareProgress(
  portal: PortalClient,
  input: DeclareProgressInput,
  overrides?: CallOverrides,
): Promise<DeclarationResult>
 
// Lee la página de avance: la secuencia de entrada, `pe_avance5` y luego `pe_avance6` con la
// empresa. En ninguna página del camino se busca un rechazo, y una página que no nombra etapa ni
// estado sigue siendo una respuesta.
function readProgress(
  portal: PortalClient,
  input?: { readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<ProgressReport>
 
// Pide al portal pasar la postulación a su siguiente etapa: `pe_avance4` con `TOTREG` y `PASO` tal
// como los trae `pe_avance2` (`PASO` cambia con la etapa; un valor fijo hace que el SII responda
// "ya se encuentra en el paso"), con `pe_avance2` de referer.
function advanceStage(
  portal: PortalClient,
  input?: { readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<AdvanceResult>
 
// Lista los libros que el SII tiene para un año (`QEstLibro`, después de que `DTEauth?7` liga la
// sesión a ese CGI). Todo período listado está ocupado para un nuevo envío total.
function listBookHistory(
  portal: PortalClient,
  input: { readonly year: number; readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<BookHistory>
 
// La declaración de cumplimiento: `pe_avance7`, `pe_avance8` con la empresa, una vez más con todos
// los inputs de la página cuando el portal pide continuar (`OK_MSG`), y luego el formulario de
// `pe_avance9` con todos los inputs de la página, salvo `Salir`, cada `OPCn` en `S` y `CONFIRMAR`,
// ambos envíos con `pe_avance8` de referer.
function declareCompliance(
  portal: PortalClient,
  input?: { readonly companyRut?: string; },
  overrides?: CallOverrides,
): Promise<ComplianceResult>

// Un estado nuevo para una empresa.
function createCertificationState(companyRut: string, now?: Date): CertificationState
 
// Un almacén en memoria: para tests y corridas cortas.
function createMemoryCertificationStore(): CertificationStore
 
// Lanza salvo que el nombre sea una ruta relativa de segmentos seguros: sin segmento vacío, sin
// `.`, sin `..`, sin ruta absoluta, nada fuera de `[A-Za-z0-9._-]`.
function assertArtefactName(name: string): void
 
// Un almacén en un directorio: `state.json` escrito de forma atómica (archivo temporal y
// renombre), los artefactos como archivos, una `/` en un nombre como subdirectorio.
function createDirectoryCertificationStore(
  options: DirectoryCertificationStoreOptions,
): CertificationStore

// Lo que la corrida completa en un emisor que lo omite: el giro, el código de actividad, la comuna
// y la ciudad. El RUT, la razón social y la dirección no tienen valor por defecto.
const DEFAULT_CERTIFICATION_ISSUER: Readonly<{ businessActivity: "ACTIVIDADES DE PROGRAMACION INFORMATICA"; activityCode: 620200...
 
// El receptor de prueba que usa la corrida cuando no se le da uno.
const DEFAULT_CERTIFICATION_RECEIVER: ReceiverInput

// Descarga el set de pruebas, lo parsea, planifica los sets y guarda el texto y el plan como
// artefactos. Descargar genera el set de nuevo en el SII, así que una corrida que ya tenía plan
// parte de cero: todo lo enviado queda sin efecto.
function obtainTestSet(
  deps: CertificationDependencies,
  state: CertificationState,
  options?: { readonly optionalSets?: readonly string[]; },
): Promise<StepResult<"loaded" | "regenerated">>
 
// Envía un set de pruebas: lo emite con los folios de los CAF del estado a través del registro,
// guarda el sobre y cada documento como artefactos, lo sube, marca los folios enviados pase lo que
// pase, y registra el track id y la fecha de Chile del envío.
function sendTestSet(
  deps: CertificationDependencies,
  state: CertificationState,
  options: { readonly kind: SetKey; },
): Promise<StepResult<"sent">>
 
// Declara los sets enviados hasta ahora con la fecha de hoy, con el ciclo de declaración; el
// resultado y cualquier diagnóstico van al estado.
function declareTestSets(
  deps: CertificationDependencies,
  state: CertificationState,
): Promise<DeclarationStepResult>
 
// Espera la aprobación de los sets enviados: 5 intentos cada 10 s, durmiendo primero, leyendo la
// página de avance. Una lectura que falla solo gasta su intento.
function waitForTestSetsApproval(
  deps: CertificationDependencies,
  state: CertificationState,
): Promise<StepResult<"approved" | "rejected" | "timedOut">>
 
// Pide al portal la etapa siguiente después de los libros: se lee la página de avance, hasta 30
// veces cada 10 s mientras no se pueda leer; con la primera página que se lee se pide el avance de
// inmediato, diga lo que diga la página de los libros (decide el portal); luego se lee de nuevo la
// página para saber la etapa, y la etapa del estado pasa a la del portal cuando esa es posterior.
function advanceToNextStage(
  deps: CertificationDependencies,
  state: CertificationState,
): Promise<StepResult<"advanced" | "unchanged" | "failed" | "timedOut">>
 
// Envía la simulación: CAF nuevos para un folio por caso (nunca los CAF de los sets), cada caso de
// los cuatro sets reemitido en un sobre, el sobre y los documentos guardados como artefactos, el
// envío, los folios marcados enviados pase lo que pase, y el track id con la fecha de Chile del
// envío.
function sendSimulation(
  deps: CertificationDependencies,
  state: CertificationState,
): Promise<StepResult<"sent">>
 
// Declara la simulación, salvo que la página de avance nombre el intercambio como el paso en que
// está la postulación: un paso posterior se declara como cualquier otro, y también una página que
// no se puede leer.
function declareSimulation(
  deps: CertificationDependencies,
  state: CertificationState,
): Promise<DeclarationStepResult<DeclarationOutcome | "skipped">>
 
// Espera la simulación: 30 consultas cada 10 s a la página de avance, consultando primero. Una
// lectura que falla solo gasta su intento.
function waitForSimulationApproval(
  deps: CertificationDependencies,
  state: CertificationState,
): Promise<StepResult<"done" | "confirmed" | "rejected" | "timedOut">>
 
// El cierre de la certificación: una petición más para avanzar la etapa, luego la declaración de
// cumplimiento.
function declareComplianceFinal(
  deps: CertificationDependencies,
  state: CertificationState,
): Promise<StepResult<"declared" | "blocked">>

// Asegura que la corrida tenga los folios que necesita cada tipo. Primero los CAF en mano: uno
// vencido se omite, los folios de esta corrida que el SII nunca recibió se devuelven, y los que el
// SII ya recibió se marcan como usados para saltarlos. Cada CAF obtenido se guarda en el estado de
// inmediato. Si aún falta, lanza `FOLIO_OUT_OF_RANGE` o, cuando las tandas se detuvieron por una
// falla y no por la respuesta del SII, el código de esa falla. Una reobtención o una anulación
// cortadas por una falla terminan el paso también con el código de esa falla, una vez que lo que
// trajo y se conservó, o lo que anuló, está en el estado. Solo un rechazo de racionamiento lleva a
// anular: una tanda posterior rechazada por la empresa, la opción o la persona conserva su tipo, y
// un bloqueo de la persona se levanta primero reobteniendo.
function prepareFolios(
  deps: CertificationDependencies,
  state: CertificationState,
  options?: PrepareFoliosOptions,
): Promise<PrepareFoliosResult>
 
// Los folios que necesita cada tipo para los sets aún no enviados: la suma de los `folios` de cada
// plan de set, nunca más, porque folios autorizados sin usar hacen que el SII racione la próxima
// solicitud.
function setFolioNeeds(
  plan: CertificationPlan,
  sent: readonly string[],
): Readonly<Record<number, number>>
 
// Los folios que necesita la simulación: uno por caso, por tipo.
function simulationFolioNeeds(plan: CertificationPlan): Readonly<Record<number, number>>

// La fase de libros.
function runBooks(
  deps: CertificationDependencies,
  state: CertificationState,
): Promise<StepResult<BooksOutcome>>
 
// El mes anterior a un período `AAAA-MM`.
function previousPeriod(period: string): string
 
// El primer período en o bajo `period` que el SII no tiene, bajando mes a mes, a lo más 400 veces.
function nextFreePeriod(period: string, occupied: ReadonlySet<string>): string

// El portal de intercambio (`pfeInternet`): ahí se descarga el set de intercambio de la
// certificación y se suben sus respuestas.
const EXCHANGE_PORTAL: GwtPortal
 
// El portal de muestras impresas (`pdfdteInternet`), el validador automático del SII de los
// documentos impresos.
const SAMPLES_PORTAL: GwtPortal
 
// Los nombres de archivo de las respuestas del intercambio, como los nombran las subidas del
// portal: la respuesta de recepción, los recibos y la aprobación comercial.
const EXCHANGE_ANSWER_FILES: Readonly<Record<ExchangeAnswerKey, string>> = {
  reception: 'respuesta-recepcion-envio.xml',
  receipts: 'envio-recibos.xml',
  approval: 'respuesta-aprobacion-comercial.xml',
}
 
// Las respuestas del intercambio en orden de subida.
const EXCHANGE_ANSWER_KEYS: readonly ExchangeAnswerKey[] = ['reception', 'receipts', 'approval']

// El cuerpo de petición de una llamada: `7|0|N|` + la tabla de strings + el cuerpo, cada ítem
// seguido de `|`.
function gwtBody(call: GwtCall): string
 
// Lee una respuesta: `//OK`, la tabla de strings, el mensaje, los tokens Long.
function gwtAnswer(body: string): GwtAnswer
 
// Un número en el alfabeto base 64 de GWT, el dígito más significativo primero (`264872` es
// `BAqo`).
function encodeGwtLong(value: number): string
 
// El número que contiene un token base 64 de GWT, o null si un carácter no está en el alfabeto.
function decodeGwtLong(token: string): number | null
 
// Los hashes de un portal GWT: el par del llamador si lo da; si no, se lee el `nocache.js` del
// módulo (los strings de 32 hexadecimales entre `=`, `'` o `,`): el par conocido vale si su
// permutación está listada, si no, la primera listada es la permutación y su `cache.html` da la
// política, el primer string de 32 hexadecimales entre comillas que no sea ella; cualquier falla,
// página vacía o candidato ausente deja el par conocido.
function discoverGwtHashes(context: PortalContext, input: GwtDiscoveryInput): Promise<GwtHashes>

// Descarga el set de intercambio del portal de intercambio: el calentamiento y luego
// `downloadFile` con la empresa en la query y un cuerpo multipart vacío. La descarga no cambia la
// postulación.
function downloadExchangeSet(
  portal: PortalClient,
  input?: ExchangeCompanyInput,
  overrides?: CallOverrides,
): Promise<ExchangeSetDownload>
 
// Valida al usuario en el portal de intercambio: el calentamiento y luego `validarUsuario` con la
// empresa y el titular del certificado, sobre los hashes conocidos. La respuesta dice si la
// empresa está en la etapa de intercambio; no se exige `//OK`.
function validateExchangeUser(
  portal: PortalClient,
  input?: ExchangeGwtInput,
  overrides?: CallOverrides,
): Promise<ExchangeUserValidation>
 
// Sube las tres respuestas del intercambio, en el orden del portal: la respuesta de recepción a
// `uploadFile1`, los recibos a `uploadFile2`, la aprobación comercial a `uploadFile3`, cada una
// como una sola parte `uploadFormElement`.
function uploadExchangeAnswers(
  portal: PortalClient,
  input: UploadExchangeAnswersInput,
  overrides?: CallOverrides,
): Promise<ExchangeUploadResult>
 
// Confirma el intercambio en el portal: `validarSetContriPostSeguimiento` con la empresa (su
// respuesta se guarda, no se juzga) y luego `updatePostulacionSeguimiento` para los ids de
// seguimiento 40, 41 y 43, uno por respuesta subida, cada uno de los cuales debe responder `//OK`.
function confirmExchange(
  portal: PortalClient,
  input?: ExchangeGwtInput,
  overrides?: CallOverrides,
): Promise<ExchangeConfirmation>
 
// Ejecuta `run` en una etapa del portal de intercambio: la sesión asegurada, un calentamiento, y
// cada llamada que recibe la etapa enviada una vez sobre ella. La subida, la validación del
// usuario y la confirmación comparten una etapa.
function withExchangeStage<T>(
  portal: PortalClient,
  operation: string,
  overrides: CallOverrides | undefined,
  run: (stage: GwtStage) => Promise<T>,
  sessionChecked?: boolean,
): Promise<T>

// Lee la revisión de muestras impresas de la empresa: `leeImpreso` con el RUT de la empresa. El
// portal responde HTTP 200 con un estado, o con una frase cuando la postulación no está en la
// etapa de muestras impresas (antes de ella, y también después).
function readSamplesReview(
  portal: PortalClient,
  input?: ReadSamplesReviewInput,
  overrides?: CallOverrides,
): Promise<SamplesReview>
 
// Crea una revisión de muestras impresas: `creaLista` con la empresa como remitente y proveedor.
// El portal solo crea una cuando la revisión actual está `RECHAZADO` o `APROBADO`, o no hay
// ninguna; una revisión en `INGRESO` se retoma.
function createSamplesReview(
  portal: PortalClient,
  input?: SamplesCompanyInput,
  overrides?: CallOverrides,
): Promise<SamplesReviewCreated>
 
// Sube un PDF a una revisión: `POST upload` con las partes `Filedata` (el archivo), `id` (el id de
// la revisión en decimal) y `ambiente` (`false`), el referer el `cache.html` de la permutación.
// HTTP 200 es éxito.
function uploadSample(
  portal: PortalClient,
  input: UploadSampleInput,
  overrides?: CallOverrides,
): Promise<SampleUploaded>
 
// Envía una revisión al SII: `solicitaRevisionSII` con el token de la revisión. La respuesta es
// `//OK[0,[],0,7]` tanto si el SII acepta como si rechaza las muestras: el estado se lee de nuevo
// después.
function submitSamplesReview(
  portal: PortalClient,
  input: SamplesReviewInput,
  overrides?: CallOverrides,
): Promise<{ readonly body: string; }>
 
// Lee cómo clasificó el SII cada PDF de una revisión rechazada: `muestraMail` con el token de la
// revisión. Una falla se registra y entrega un detalle vacío: el rechazo se mantiene sin él.
function readSamplesDetail(
  portal: PortalClient,
  input: SamplesReviewInput,
  overrides?: CallOverrides,
): Promise<SamplesDetail>
 
// Ejecuta `run` en una etapa del portal de muestras: la sesión asegurada, un calentamiento, los
// hashes buscados una vez, y cada llamada que recibe la etapa enviada una vez sobre ella.
function withSamplesStage<T>(
  portal: PortalClient,
  operation: string,
  overrides: CallOverrides | undefined,
  run: (stage: GwtStage) => Promise<T>,
): Promise<T>

// Arma y firma las tres respuestas a un set de intercambio, como las espera la certificación: la
// respuesta de recepción (el sobre recibido, cada documento recibido cuando su receptor es la
// empresa, si no "error en RUT receptor"), los recibos de la Ley 19.983 (uno por documento,
// firmados por el titular del certificado) y la aprobación comercial (aceptado cuando el receptor
// es la empresa, si no rechazado con `CodRchDsc` -1).
function createExchangeAnswers(setXml: string, input: CreateExchangeAnswersInput): ExchangeAnswers
 
// Lee el set de intercambio como lo lee el lector de campo, con tolerancia: no se comprueba que el
// XML esté bien formado y sus etiquetas se leen por su nombre completo, así que un sobre con
// prefijo no es un sobre; la raíz es `EnvioDTE`, `EnvioDTEB`, `EnvioDTETraslado` o `EnvioBOLETA`;
// el id del set (el atributo `ID`, si no un hijo `ID`, si no `SetDTE`), los RUT de la carátula y,
// por documento, su tipo (`TipoDTE` o `TpoDoc`), folio, fecha de emisión, emisor y receptor (los
// de la carátula cuando el documento no los nombra) y total.
function parseExchangeSet(setXml: string): ExchangeSet

// La etapa de intercambio: el set (dado, guardado de una corrida anterior, o descargado), las tres
// respuestas generadas y guardadas como artefactos, el usuario validado en el portal, las
// respuestas subidas y el intercambio confirmado, que mueve la postulación a las muestras
// impresas.
function runExchange(
  deps: CertificationDependencies,
  state: CertificationState,
  input?: RunExchangeInput,
): Promise<StepResult<ExchangeOutcome>>
 
// El artefacto que guarda el set de intercambio; el llamador lo llena a mano cuando falla la
// descarga.
const EXCHANGE_SET_ARTEFACT: "intercambio/set-intercambio.xml"
 
// La etapa de muestras impresas: la revisión leída (un bloqueo o una revisión ya enviada terminan
// aquí), retomada cuando está en `INGRESO` con un id legible o creada si no, cada PDF subido en
// orden (cada nombre guardado sobre la marcha), la revisión enviada, y su estado leído de nuevo
// (una lectura fallida se advierte y deja el estado desconocido): `RECHAZADO` trae el detalle y su
// resumen.
function uploadPrintedSamples(
  deps: CertificationDependencies,
  state: CertificationState,
  input: UploadPrintedSamplesInput,
): Promise<StepResult<SamplesOutcome>>

// El lado HTML de la certificación, en el orden de las etapas, retomado desde el estado guardado:
// el set de pruebas (descargado una vez), los folios, cada set aún no enviado, su declaración y
// aprobación; los libros; el avance; la simulación enviada, declarada y confirmada; el set de
// intercambio respondido, subido y confirmado; las muestras impresas subidas y enviadas cuando la
// opción `samples` las da (si no, se detiene ahí); y luego declara cumplimiento, solo con
// `declareCompliance: true`, porque esa declaración no se puede deshacer.
function runCertification(
  dependencies: CertificationDependencies,
  options?: RunCertificationOptions,
): Promise<RunCertificationResult>

// El portal de boletas (`certBolElectDteInternet`), donde corre la certificación de boletas
// electrónicas. Sus hashes no se descubren: `moduleName` es lo que sugiere su interfaz, no un dato
// registrado.
const RECEIPTS_PORTAL: GwtPortal
 
// Parsea el set de pruebas de boletas que entrega el portal de boletas, un texto plano.
function parseReceiptsTestSet(text: string): readonly ReceiptsTestCase[]

// Emite el set de pruebas de boletas: una boleta tipo 39 por caso, en orden, cada una con el
// siguiente folio de la fuente, el consumidor final como receptor, los precios del set tomados con
// IVA incluido, la exención de un ítem exento, la unidad de medida que nombra una observación en
// su primer ítem, y una referencia con el código `SET` y la razón `CASO-<n>`; luego firma el
// `EnvioBOLETA` que las lleva, con el titular del certificado como enviador (el emisor cuando el
// certificado no nombra ninguno) y el SII como receptor.
function issueReceiptsSet(
  cases: readonly ReceiptsTestCase[],
  options: IssueReceiptsSetOptions,
): Promise<IssuedReceiptsSet>

// Envía el set de boletas: sube el sobre y lee la respuesta (`STATUS` 0 con track id es enviado;
// `STATUS` 7 con track id también se toma como enviado, y sin él es un duplicado que salta al
// reporte sin track id; `STATUS` 99 y cualquier otra respuesta es una falla y lanza), espera 20 s
// y lee una vez el estado de un sobre enviado (un rechazo termina aquí; una consulta que nunca
// llegó se registra, y una respuesta sin estado, o con uno desconocido, no bloquea nada), y luego
// envía el reporte de consumo de folios armado desde el sobre, con la secuencia `sequence` más el
// intento, hasta diez intentos: un `STATUS` 7 sin track id es un duplicado y tres seguidos
// significan que el reporte de hoy ya se aceptó; un `STATUS` 99 u otro rechazo lo termina como
// `consumptionFailed`; a un reporte subido se le dan 30 s y se lee su estado una vez: un éxito o
// un estado intermedio (también un código de error de la consulta o `0`) lo acepta, una consulta
// que nunca llegó lo acepta, y cualquier otra cosa (un rechazo, ningún estado, un estado
// desconocido) prueba la secuencia siguiente, salvo que su glosa hable de autorización o firma.
function sendReceiptsSet(
  sii: SiiClient,
  issued: { readonly envelope: SignedEnvelope; },
  options?: SendReceiptsSetOptions,
): Promise<ReceiptsSendResult>
 
// Arma de nuevo el reporte de consumo de folios desde un sobre de boletas ya enviado y lo sube una
// vez, con la secuencia dada.
function resendReceiptsConsumption(
  sii: SiiClient,
  input: ResendReceiptsConsumptionInput,
): Promise<{ readonly sequence: number; readonly xml: string; readonly trackId: string; readonly duplicate: boolean; }>