<!-- source_url: https://docs.mynexusapi.com/v1/guias/sdk-node | last_updated: 2026-11-19 -->

# SDK Node.js

Biblioteca oficial para emitir comprobantes desde Node.js 18 o superior, con tipos de TypeScript, seguir su autorización y verificar webhooks.

Si desarrollas en JavaScript o TypeScript, puedes integrarte con nuestros
servicios de facturación usando nuestro SDK para Node.js. En lugar de armar cada
petición con `fetch`, llamas a métodos como `emitirFactura` o `descargarRide`, que
devuelven promesas con objetos tipados. Puedes reintentar sin miedo a duplicar
comprobantes, porque el SDK reutiliza la `Idempotency-Key` en sus reintentos.
Además, envía tu API Key en cada llamada, te indica si llegaste al límite de
solicitudes o si se agotó tu cupo, y verifica la firma de los webhooks que te
enviamos.

Esta guía sigue el orden de una integración. Primero instalas el paquete,
configuras el cliente, emites tu primera factura y haces el seguimiento hasta el
resultado del SRI; después recibes webhooks y manejas los errores, y al final
ajustas los reintentos, las opciones por llamada y la conexión, y armas
comprobantes con los constructores. La [referencia de métodos](#metodos) está
al final. Si todavía no decides entre el SDK y la API por HTTP directo,
compáralos en [SDKs](/v1/guias/sdk).

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal. Los ejemplos usan
> `https://api-sandbox.mynexusapi.com`; cambia a `https://api.mynexusapi.com`
> solo cuando emitas comprobantes reales.

## Para agentes

Usa esta vía cuando quieras que un agente de programación haga esta tarea en tu entorno actual.

Pega este prompt en un agente de programación con acceso a la terminal:

```text
Instala el SDK Node.js de Ecuafact en este proyecto y emite una factura de prueba de punta a punta. Solo ambiente de pruebas: usa https://api-sandbox.mynexusapi.com y no emitas nada real. Si tienes la skill de Ecuafact, úsala; si no, puedes instalarla con npx skills add Ecuanexus/ecuafact-skill. Lee https://docs.mynexusapi.com/llms.txt y la guía en Markdown https://docs.mynexusapi.com/v1/guias/sdk-node.md antes de escribir código; no inventes campos. Reutiliza el lenguaje, el gestor de paquetes y la estructura del proyecto; si no hay proyecto, crea uno mínimo. Instala con npm install @ecuafact/sdk. Reutiliza ECUAFACT_API_KEY sin mostrarla. Si falta, pídeme que la cree en el Portal del Cliente (Cuenta > API Keys) y la configure yo mismo en mi entorno o en un .env ignorado por git; nunca la pegues en el chat ni la imprimas. Crea el cliente con esa variable, consulta el contexto para obtener el RUC del emisor, arma la factura con los datos de prueba de la guía, valídala sin emitir, emítela con una Idempotency-Key estable y sigue la operación hasta un estado final. Requiere Node.js 18 o superior con módulos ES. La respuesta 202 puede traer codEstado 1001 o 1002 (recibido) o ya un estado final: decide siempre por estado y codEstado (numérico), usa urlEstado tal cual (URL absoluta) y lee errores como arreglo. Ejecuta el programa e informa solo el estado, el codEstado y la claveAcceso de la factura, y cualquier acción que yo deba hacer.
```

## Paquete

| Dato | Valor |
|---|---|
| Paquete npm | [`@ecuafact/sdk`](https://www.npmjs.com/package/@ecuafact/sdk) |
| Versión | `1.0.1` |
| Node.js | 18 o superior, porque usa el `fetch` nativo. |
| Formato | Módulo ES (`import`). Incluye tipos TypeScript (`.d.ts`). |
| Dependencias | No tiene dependencias en tiempo de ejecución. |

El paquete se distribuye solo como módulo ES. En un proyecto CommonJS, cárgalo con
`const { EcuafactClient } = await import("@ecuafact/sdk");` dentro de una
función `async`.

## Requisitos

- [ ] Node.js 18 o superior, que compruebas con `node --version`.
- [ ] Una API Key de pruebas guardada en la variable de entorno
      `ECUAFACT_API_KEY`. Si todavía no tienes una, crea tu sandbox como se
      explica en [Sandbox de pruebas](/v1/guias/sandbox).
- [ ] Nada que registrar para la IP en sandbox: acepta llamadas desde cualquier
      IP. En producción, la IP desde la que ejecutas el código debe estar en
      **Cuenta > IP permitidas**; si no lo está, la API responde 403 con el
      `codEstado` 3010 (`ip_no_autorizada`).

## Instalación

```bash
mkdir ecuafact-prueba && cd ecuafact-prueba
npm init -y
npm install @ecuafact/sdk
```

Para verificar la instalación, ejecuta `npm ls @ecuafact/sdk`, que debe mostrar
`@ecuafact/sdk@1.0.1`.

## Configuración

Crea el cliente **una vez** y reutilízalo, porque sirve para todos los
[contribuyentes](/v1/guias/glosario) de tu API Key.

```javascript
// Node.js 18 o superior. Guarda como cliente.mjs y ejecuta: node cliente.mjs
import { EcuafactClient } from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY,
  identificacion: "0123456789001" // opcional: contribuyente por defecto
});
console.log(client.options); // la API Key aparece como [oculta]
```

Si no pasas `apiKey`, el SDK lee la variable de entorno `ECUAFACT_API_KEY`, y si
no pasas `baseAddress`, lee `ECUAFACT_BASE_URL`. Con las dos variables definidas
basta `new EcuafactClient()`.

Eliges el ambiente con la URL que configuras, porque el SDK no tiene una opción
aparte para eso. Usa `https://api-sandbox.mynexusapi.com/` para pruebas y
`https://api.mynexusapi.com/` para producción, **sin** `/v1`, ya que el SDK
agrega la versión a cada ruta.

| Opción | Tipo | Valor por defecto | Descripción |
|---|---|---|---|
| `baseAddress` | `string` | `ECUAFACT_BASE_URL` | URL absoluta HTTPS, sin `/v1`, sin usuario, consulta ni fragmento. |
| `apiKey` | `string` | `ECUAFACT_API_KEY` | Tu API Key; viaja en la cabecera `X-Api-Key`. No puede tener espacios al inicio o al final ni caracteres de control. No aparece en `console.log`, `util.inspect` ni `JSON.stringify`; si la necesitas, léela con `client.options.apiKey`. |
| `identificacion` | `string` | - | Contribuyente por defecto para los métodos `emitir<Tipo>` y `validar<Tipo>` sin `En`. Usa el valor `identificacion` de `GET /v1/contexto` (la identificación completa del contribuyente, por ejemplo su RUC de 13 dígitos). |
| `timeoutMs` | `number` | `30000` | Tiempo máximo de **cada intento**, incluida la lectura de la respuesta, en milisegundos. Mayor que 0. |
| `maxResponseBytes` | `number \| null` | 32 MiB (`33554432`); 100 MiB (`104857600`) en las descargas de RIDE y XML | Tope en bytes del cuerpo de una respuesta. Un número lo aplica a todas las llamadas, incluidas las descargas; `0` o `null` lo desactiva. Al superarlo lanza `EcuafactResponseTooLargeException` con `limite` y `bytesLeidos`. |
| `additionalInfo` | `string` | - | Texto que se envía en la cabecera `X-Additional-Info` de cada solicitud, por ejemplo el nombre y la versión de tu ERP; no se guarda con el comprobante. Si la omites o la dejas vacía, la cabecera no se envía. Sus reglas están en [Información adicional](#informacion-adicional). |
| `userAgent` | `string` | `Ecuafact.Sdk/1.0` | Valor de la cabecera `User-Agent`. |
| `validarAntesDeEmitir` | `boolean` | `false` | Si es `true`, `emitir<Tipo>` y `emitir<Tipo>En` llaman primero a `/validar` y no envían la emisión cuando la API responde `valido: false` (ver [Validar antes de emitir](#validar-antes-de-emitir-opcional)). Cada emisión hace dos peticiones, así que déjalo en `false` en producción salvo que lo necesites. |
| `retryTransientFailures` | `boolean` | `true` | Reintenta fallos transitorios (ver [Idempotencia y reintentos](#idempotencia-y-reintentos)). `false` desactiva todo reintento. |
| `maxAttempts` | `number` | `3` | Intentos por solicitud, incluido el primero. Entero 1 o mayor. |
| `respectRetryAfter` | `boolean` | `true` | Espera lo que indique la cabecera `Retry-After` antes de reintentar. |
| `maxRetryDelayMs` | `number` | `60000` | Espera máxima entre reintentos, en milisegundos. Con `0` no hay tope. |
| `retryRateLimited` | `boolean` | `true` | Reintenta el 429 por límite de solicitudes, el que trae el `codEstado` 5005 (`limite_solicitudes`), respetando `Retry-After` y `maxRetryDelayMs`. El cupo agotado, un 429 con el `codEstado` 4004 (`cupo_agotado`), nunca se reintenta. |
| `retryableStatusCodes` | `number[]` | `[408, 425, 500, 502, 503, 504]` | Estados HTTP que se reintentan (enteros de 100 a 599). El 429 no va aquí: lo controla `retryRateLimited`. Los valores por defecto están en la constante exportada `DEFAULT_RETRYABLE_STATUS_CODES`. |
| `retryBaseDelayMs` | `number` | 200 | Espera base entre reintentos, en milisegundos. |
| `retryBackoff` | `"linear" \| "exponential"` | `"linear"` | `linear`: base x intento (200, 400, 600 ms). `exponential`: base x 2^(intento-1) (200, 400, 800 ms). |
| `retryJitterMs` | `number` | `50` | Variación aleatoria que se suma a cada espera, en milisegundos: hasta `retryJitterMs` x intento en `linear` y hasta `retryJitterMs` en `exponential`. |
| `totalTimeoutMs` | `number` | `0` (sin tope) | Tope de toda la llamada, incluidos reintentos y esperas, en milisegundos. Al superarlo lanza `EcuafactTimeoutException`. |
| `fetch` | `typeof fetch` | `globalThis.fetch` | Tu propia implementación de `fetch`, por ejemplo la de `undici` o un doble de pruebas. |
| `dispatcher` | `unknown` | - | `dispatcher` de `undici` que se pasa a cada `fetch` para usar un proxy (`ProxyAgent`), una CA propia o un tiempo de conexión (`Agent`). El detalle está en [Proxy, TLS y tiempo de conexión](#proxy-tls-y-tiempo-de-conexion). |

```js
new EcuafactClient({ maxResponseBytes: 64 * 1024 * 1024 }); // 64 MiB; null desactiva el tope
```

Las opciones se validan al crear el cliente. El constructor lanza
`EcuafactConfigurationException`, antes de hacer cualquier llamada, en
cualquiera de estos casos:

- Falta la API Key o la URL.
- La URL no es HTTPS, tiene usuario, consulta o fragmento, o termina en `/v1`.
- La API Key tiene espacios o caracteres de control.
- `additionalInfo` no cumple su formato.
- `maxAttempts` no es un entero 1 o mayor.
- `timeoutMs` no es mayor que 0, u otro tiempo es negativo.
- `maxResponseBytes` no es un entero mayor que 0, `0` ni `null`.
- `validarAntesDeEmitir` no es `true` ni `false`.
- `retryBackoff` tiene un valor distinto de los admitidos.
- `retryableStatusCodes` trae un código fuera del rango de 100 a 599.

El mensaje de la excepción nunca incluye la API Key.

## Quickstart: de la API Key al RIDE

Este script hace el flujo completo en el ambiente de pruebas: lee tu
[contexto](/v1/guias/consulta-contexto), emite una factura, espera el resultado
del SRI con el [seguimiento](/v1/guias/consulta-operacion) y descarga el
[RIDE](/v1/guias/glosario), el PDF del comprobante.

### Paso 1. Guarda el comprobante

Guarda este JSON como `comprobante.json` en la carpeta del proyecto. Es una
factura a consumidor final, con el tipo de identificación `07` y la
identificación `9999999999999`, que solo se admite en facturas de hasta 50.00.
Factura 10.00 más el IVA del 15 %, que son 1.50, por un total de 11.50. No
lleva `secuencial`, porque te asignamos el siguiente [secuencial](/v1/guias/glosario) de la serie
`estab`-`ptoEmi`. El script reemplaza `ruc` por el de tu contexto y
`fechaEmision` por la fecha de hoy.

```json
{
  "origenReferencia": "MiERP",
  "referenciaExterna": "FACTURA-2026-0001",
  "infoTributaria": {
    "ruc": "0123456789001",
    "estab": "001",
    "ptoEmi": "001"
  },
  "info": {
    "fechaEmision": "07/10/2026",
    "tipoIdentificacionComprador": "07",
    "identificacionComprador": "9999999999999",
    "razonSocialComprador": "CONSUMIDOR FINAL",
    "totalSinImpuestos": 10.00,
    "totalDescuento": 0.00,
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "baseImponible": 10.00,
        "valor": 1.50
      }
    ],
    "propina": 0.00,
    "importeTotal": 11.50,
    "moneda": "DOLAR",
    "pagos": [
      {
        "formaPago": "01",
        "total": 11.50
      }
    ]
  },
  "detalles": [
    {
      "codigoPrincipal": "SERV-001",
      "descripcion": "Servicio de prueba",
      "cantidad": 1,
      "precioUnitario": 10.00,
      "descuento": 0.00,
      "precioTotalSinImpuesto": 10.00,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 10.00,
          "valor": 1.50
        }
      ]
    }
  ]
}
```

El cuerpo no lleva el tipo de comprobante: lo da el método que eliges (`emitirFactura` para una factura) y la ruta
que ese método usa, como se explica en [Tipo de comprobante y ruta](#tipo-de-comprobante-y-ruta).

`estab` y `ptoEmi` deben ser un [establecimiento](/v1/guias/glosario) y un
[punto de emisión](/v1/guias/glosario) de tu emisor; el sandbox crea el
establecimiento `001` con el punto de emisión `001`. Cada campo está explicado en [Factura](/v1/guias/emision-01).

### Paso 2. Escribe el script

Guarda el código siguiente como `quickstart.mjs`. El paso 4 usa
`esperarResultado`, un método **opcional** que consulta la operación cada 5
segundos hasta tener un resultado final o hasta 2 minutos. En producción puedes
usar en cambio el flujo asíncrono, en el que emites, guardas el `idOperacion` y
procesas el resultado cuando llega el [webhook](/v1/guias/webhooks), sin que
tu proceso se quede esperando.

```javascript
// Node.js 18 o superior. Ejecuta: node quickstart.mjs
import { readFile, writeFile } from "node:fs/promises";
import { EcuafactClient, EcuafactApiException, esAutorizado, esFinal } from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY
});

try {
  // 1. Contexto: que contribuyentes puede usar tu API Key.
  const contexto = await client.getContexto();
  const emisor = (contexto.contribuyentes ?? []).find((c) => c.puedeEmitir);
  if (!emisor) {
    throw new Error("Tu API Key no tiene un contribuyente habilitado para emitir.");
  }
  console.log(`Emisor ${emisor.identificacion}`);

  // 2. Comprobante: lee el JSON y completa RUC y fecha de hoy (hora de Ecuador).
  const comprobante = JSON.parse(await readFile("comprobante.json", "utf8"));
  const hoy = new Date(Date.now() - 5 * 60 * 60 * 1000);
  comprobante.infoTributaria.ruc = emisor.identificacion;
  comprobante.info.fechaEmision =
    `${String(hoy.getUTCDate()).padStart(2, "0")}/${String(hoy.getUTCMonth() + 1).padStart(2, "0")}/${hoy.getUTCFullYear()}`;

  // 3. Emision: 202 Accepted. Guarda idOperacion e Idempotency-Key.
  const emision = await client.emitirFacturaEn(emisor.identificacion, comprobante, "FACTURA-2026-0001");
  // codEstado es 1001 (aun sin clave de acceso) o 1002 (con claveAcceso); acepta los dos.
  console.log(`estado ${emision.admission.estado} codEstado ${emision.admission.codEstado} idOperacion ${emision.admission.idOperacion}`);

  // 4. Seguimiento (opcional): espera el resultado del SRI (cada 5 s, maximo 2 min).
  const operacion = await client.esperarResultado(emision.admission.idOperacion);
  console.log(`estado ${operacion.estado} codEstado ${operacion.codEstado}`);
  operacion.errores.forEach((detalle) => console.log(` - ${detalle}`));

  // 5. RIDE: solo existe cuando el comprobante esta autorizado.
  if (esAutorizado(operacion)) {
    const ride = await client.descargarRide(emisor.identificacion, operacion.claveAcceso);
    await writeFile("ride.pdf", ride.contenido);
    console.log(`RIDE guardado en ride.pdf; claveAcceso ${operacion.claveAcceso}`);
  } else if (!esFinal(operacion)) {
    console.log("Aun sin resultado: consulta mas tarde o espera el webhook.");
  }
} catch (error) {
  if (error instanceof EcuafactApiException) {
    console.error(`HTTP ${error.estadoHttp} codEstado ${error.codEstado}: ${error.msgError}`);
    error.errores.forEach((detalle) => console.error(` - ${detalle}`));
    console.error(`X-Correlation-Id: ${error.correlationId}`);
  } else {
    throw error;
  }
}
```

### Paso 3. Ejecuta y verifica

```bash
node quickstart.mjs
```

Deberías ver algo como esto; los identificadores cambian en cada ejecución:

```
Emisor 0123456789001
estado recibido codEstado 1001 idOperacion 3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f
estado autorizado codEstado 2001
RIDE guardado en ride.pdf; claveAcceso 0710202601012345678900110010010000001231234567811
```

El programa funcionó si ves `estado autorizado` y el ejemplo guardó
el RIDE como `ride.pdf`. La tabla explica cada línea que puede imprimir.

| Salida | Significado | Qué hacer |
|---|---|---|
| `estado recibido codEstado 1001` | La API aceptó la emisión y respondió `202 Accepted`. Todavía no es la autorización. La respuesta puede traer 1001, cuando aún no hay clave de acceso y `claveAcceso` es `null`, o 1002, cuando ya la trae; tu código debe aceptar los dos. Si repetiste la misma `Idempotency-Key` con el mismo cuerpo, recibes la misma operación. | Sigue con el seguimiento. Para emitir otra factura cambia `referenciaExterna` y la `Idempotency-Key`. |
| `estado autorizado codEstado 2001` | El SRI autorizó el comprobante; `claveAcceso` trae la [clave de acceso](/v1/guias/glosario) real de 49 dígitos. | Descarga el RIDE o el XML. |
| `estado rechazado codEstado 3001` | El SRI rechazó el comprobante. Es un rechazo fiscal, y las líneas que empiezan con `-` muestran el mensaje del SRI, que llega en `errores`. | Corrige los datos y emite un comprobante nuevo con **nueva** `Idempotency-Key`, nueva `referenciaExterna` y un secuencial nuevo. |
| `estado rechazado`, `rechazo_configuracion`, `error` o `cancelado` con otro `codEstado` | La operación terminó sin autorización. | Busca el `codEstado` en [Códigos de resultado de una operación](/v1/guias/errores#codigos-de-resultado-de-una-operacion) y sigue lo que indica. |
| `Aun sin resultado` | Pasaron 2 minutos y el `estado` sigue en `recibido`. | Vuelve a consultar más tarde o espera el [webhook](/v1/guias/webhooks). |
| `HTTP 401 codEstado 3009` | La API Key no es válida. | Revisa `ECUAFACT_API_KEY`. |
| `HTTP 403 codEstado 3011` | El contribuyente o el tipo de comprobante no están habilitados, o `ruc` no coincide con el contribuyente de la ruta. | Revisa `puedeEmitir` y `tiposComprobante` en el contexto. |
| `HTTP 422 codEstado 3002` | Falta un campo, un campo está mal formado o no se cumple una regla fiscal. Lee las líneas que empiezan con `-`. | Corrige el JSON; un 422 consume 1 documento como intento. |

> [!NOTE]
> Si ejecutas el script otro día con la misma `Idempotency-Key`, la fecha cambia
> el cuerpo y la API responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`). Usa una
> `Idempotency-Key` y una `referenciaExterna` nuevas para cada factura nueva.

Todos los métodos `emitir<Tipo>` y `emitir<Tipo>En` devuelven un `EmisionResultado` con estos campos:

| Campo | Tipo | Descripción |
|---|---|---|
| `admission` | `Admission` | La respuesta de la emisión, con los mismos campos que `Operation`, que se describen en [Seguimiento y resultado](#seguimiento-y-resultado). En una emisión aceptada, `estado` es `recibido`: aceptamos el comprobante, que todavía no está autorizado. Un reintento con la misma `Idempotency-Key` y el mismo cuerpo responde igual. |
| `admission.codEstado` | `number` | 1001 si todavía no hay clave de acceso, con `claveAcceso` en `null`, o 1002 si ya la trae. Tu código debe aceptar los dos valores. |
| `admission.idOperacion` | `string` (UUID) | Guárdalo, porque lo necesitas para el seguimiento. |
| `admission.urlEstado` | `string` | URL completa del seguimiento (`https://<host>/v1/operaciones/{idOperacion}`). |
| `idempotencyKey` | `string` | La `Idempotency-Key` usada (la tuya o la que generó el SDK). Guárdala junto al documento. |
| `correlationId` | `string \| undefined` | Cabecera `X-Correlation-Id` de la respuesta. Inclúyela al pedir soporte. |

## Tipo de comprobante y ruta

Cada tipo de comprobante tiene su propio tipo de solicitud, igual que tiene su propio endpoint. El tipo del
request que entregas fija la ruta, así que el cuerpo no lleva ningún campo de tipo y `infoTributaria` solo trae
`ruc`, `estab`, `ptoEmi` y `secuencial`. Eliges el método por tipo; cada uno tiene una variante `...En` que recibe la
`identificacion` de la ruta como primer argumento:

| Código | Documento | Request | Emitir | Validar | Ruta de emisión | Ruta de validación |
|---|---|---|---|---|---|---|
| `01` | Factura | `FacturaRequest` | `emitirFactura` | `validarFactura` | `POST /v1/contribuyentes/{identificacion}/facturas` | `POST /v1/contribuyentes/{identificacion}/facturas/validar` |
| `03` | Liquidación de compra | `LiquidacionCompraRequest` | `emitirLiquidacionCompra` | `validarLiquidacionCompra` | `POST /v1/contribuyentes/{identificacion}/liquidaciones-compra` | `POST /v1/contribuyentes/{identificacion}/liquidaciones-compra/validar` |
| `04` | Nota de crédito | `NotaCreditoRequest` | `emitirNotaCredito` | `validarNotaCredito` | `POST /v1/contribuyentes/{identificacion}/notas-credito` | `POST /v1/contribuyentes/{identificacion}/notas-credito/validar` |
| `05` | Nota de débito | `NotaDebitoRequest` | `emitirNotaDebito` | `validarNotaDebito` | `POST /v1/contribuyentes/{identificacion}/notas-debito` | `POST /v1/contribuyentes/{identificacion}/notas-debito/validar` |
| `06` | Guía de remisión | `GuiaRemisionRequest` | `emitirGuiaRemision` | `validarGuiaRemision` | `POST /v1/contribuyentes/{identificacion}/guias-remision` | `POST /v1/contribuyentes/{identificacion}/guias-remision/validar` |
| `07` | Comprobante de retención | `RetencionRequest` | `emitirRetencion` | `validarRetencion` | `POST /v1/contribuyentes/{identificacion}/retenciones` | `POST /v1/contribuyentes/{identificacion}/retenciones/validar` |

```ts
const emision = await client.emitirNotaCreditoEn(identificacion, notaCredito, "NC-2026-0001");
const validacion = await client.validarRetencion(retencion); // usa la identificacion del cliente
```

Cada request contiene solo las propiedades de su esquema del contrato, con la misma obligatoriedad y nulabilidad
(`string | null` cuando el contrato admite nulo; sin `?` cuando es obligatorio). Su `info` es el tipo propio de cada
documento (`InfoFactura`, `InfoLiquidacionCompra`, `InfoNotaCredito`, `InfoNotaDebito`, `InfoGuiaRemision` e
`InfoComprobanteRetencion`), y sus líneas son `DetalleCompraVenta` (factura y liquidación de compra),
`DetalleNotaCredito`, `Motivo`, `Destinatario` con `DetalleGuia`, o `DocsSustento` con `ImpuestoDocSustento`,
`RetencionLinea` y `Pago`. Se reutilizan en todos los tipos que los comparten `InfoTributaria`, `Pago`, `Impuesto` y
`CampoAdicional`. La factura conserva los nueve campos de exportación en `InfoFactura`.

El SDK no tiene un tipo de comprobante genérico ni deduce el tipo por la forma del cuerpo: el método que eliges fija el tipo. El
filtro `tipoDocumento` de `listarOperaciones` acepta un código (`01`) o un nombre (`factura`) y, si no es uno
de los seis tipos, lanza `EcuafactTipoComprobanteException` antes de llamar a la API.

## Validar sin emitir

Con `validar<Tipo>En(identificacion, comprobante)` (por ejemplo `validarFacturaEn`) compruebas que un comprobante está
bien armado antes de emitirlo. El método llama siempre al endpoint `/validar` del
tipo: el SDK no valida nada localmente, porque las reglas de negocio de los
comprobantes (campos requeridos, formatos, catálogos, topes e importes) viven
solo en la API y esta puede cambiarlas sin que actualices el SDK. La API no emite
nada, no consume cupo ni usa un número de la serie, y por eso el método no
recibe `Idempotency-Key`. Si configuraste `identificacion` en
las opciones del cliente, puedes usar `validar<Tipo>(comprobante)`, y la vista
`client.para(identificacion)` también tiene los métodos `validar<Tipo>`.

```javascript
// Node.js 18 o superior. Guarda como validar.mjs y ejecuta: node validar.mjs
import { readFile } from "node:fs/promises";
import { EcuafactClient } from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY
});

const comprobante = JSON.parse(await readFile("comprobante.json", "utf8"));
const validacion = await client.validarFacturaEn("0123456789001", comprobante);
if (validacion.valido) {
  console.log("Listo para emitir");
} else {
  console.log(validacion.codEstado, validacion.errores);
  // 3002 [ '$.detalles[0].impuestos[0].valor: Valor de impuesto no coincide con base y tasa.' ]
}
```

El método devuelve un objeto con `valido`, `codEstado`, `msgError`, `errores`,
`advertencias` y `correlationId`. Cuando el comprobante cumple todas las reglas, la API responde
200 y el SDK lee `valido` (`true`) y `advertencias` del cuerpo: `codEstado` y `msgError` son `null`,
`errores` llega vacío y `advertencias` trae los avisos que no impiden emitir, si los hay. Cuando no las cumple, la
API responde 422 con el `codEstado` 3002 (`comprobante_invalido`) y el método no lanza una excepción: te
devuelve `valido` en `false` y en `errores` el problema con la ruta del campo,
para que lo corrijas y vuelvas a validar. Cualquier otro error se lanza igual
que al emitir; por ejemplo, si el contribuyente, su RUC o el tipo de
comprobante no están habilitados para tu API Key, recibes
`EcuafactAuthException` con el `codEstado` 3011 (`acceso_denegado`). Como validar no tiene efectos, el SDK
la reintenta ante fallos transitorios igual que una consulta.

Un resultado válido significa que la emisión de ese mismo contenido no tendrá
errores de validación, pero no comprueba tu cupo ni si ya emitiste ese
comprobante, y no es una autorización del SRI. Los detalles están en
[Validar sin emitir](/v1/guias/emision#validar-sin-emitir).

### Validar antes de emitir (opcional)

Por defecto `emitir<Tipo>` y `emitir<Tipo>En` envían el comprobante directo, con una sola
petición. Si la API lo rechaza, lanzan `EcuafactValidationException` (422) con
el detalle en `errores`. Si prefieres comprobar cada comprobante antes de
emitirlo, activa `validarAntesDeEmitir`, que vale `false` por defecto para que
en producción no se dupliquen las peticiones. Puedes activarla en el cliente o
solo en una llamada:

```javascript
const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY,
  validarAntesDeEmitir: true
});

// O solo en una llamada (también sirve para desactivarla con false):
const r = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0001", {
  validarAntesDeEmitir: true
});
console.log(r.advertencias); // avisos de /validar; si hay, no bloquean la emisión
```

Con la opción activa, cada emisión hace dos peticiones. Primero llama a
`/validar`. Si `valido` es `true` y `errores` está vacío, envía la emisión y
devuelve en `advertencias` los avisos que haya traído la validación. Si no es
válido, lanza la misma `EcuafactValidationException` (422, `codEstado` 3002,
con los `errores` de la API) **sin enviar la emisión**, así que no consume
cupo. Con la opción en `false`, una sola petición.

## Seguimiento y resultado

La emisión responde `202 Accepted` apenas recibe el comprobante, y el resultado
del SRI llega después. Puedes conocerlo de tres
formas, y combinarlas.

| Forma | Método | Cuándo usarla |
|---|---|---|
| Consulta puntual | `getOperacion(idOperacion)` (alias `consultarOperacion`) | Un proceso programado revisa las operaciones pendientes. |
| Espera activa | `esperarResultado(idOperacion, { intervaloMs, maximoMs, signal })` | Lo usas en scripts, pruebas o un proceso que puede esperar hasta 2 minutos. |
| Aviso | [Webhooks](#webhooks) | En producción, recibes el resultado sin consultar. |

`esperarResultado` consulta la operación cada `intervaloMs` (por defecto
`5000`) hasta que `esFinal(operacion)` es `true` o pasan `maximoMs` (por defecto
`120000`). **No lanza** una excepción al agotar el tiempo, sino que devuelve la
última operación leída, y tú decides con `esFinal`. Si `intervaloMs` no es mayor que 0 o `maximoMs` es
negativo, lanza `EcuafactSdkException`. `signal` cancela la espera y la promesa
se rechaza con `signal.reason`. `idOperacion` debe ser un UUID, con guiones o
como 32 caracteres hexadecimales; si no lo es, lanza `EcuafactSdkException` sin llamar
a la API.

```javascript
// Node.js 18 o superior. Guarda como seguimiento.mjs y ejecuta: node seguimiento.mjs
import { EcuafactClient, esAutorizado, esFinal } from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY
});
const idOperacion = "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"; // el de tu emision

// Consulta puntual.
const actual = await client.getOperacion(idOperacion);
console.log(`ahora: ${actual.estado}`);

// Espera activa: cada 3 s, maximo 60 s, cancelable con Ctrl+C.
const controller = new AbortController();
process.once("SIGINT", () => controller.abort());
const operacion = await client.esperarResultado(idOperacion, {
  intervaloMs: 3000,
  maximoMs: 60000,
  signal: controller.signal
});

if (esAutorizado(operacion)) {
  console.log(`Autorizado. claveAcceso ${operacion.claveAcceso}`);
} else if (esFinal(operacion)) {
  console.log(`Termino sin autorizacion: ${operacion.estado} ${operacion.codEstado}: ${operacion.msgError}`);
  operacion.errores.forEach((detalle) => console.log(` - ${detalle}`));
} else {
  console.log("Sin resultado todavia: vuelve a consultar o espera el webhook.");
}
```

Con una factura autorizada, deberías ver algo como esto:

```
ahora: autorizado
Autorizado. claveAcceso 0710202601012345678900110010010000001231234567811
```

`Operation` tiene los mismos campos de la respuesta de la API:

| Campo | Tipo | Descripción |
|---|---|---|
| `estado` | `string` | `recibido`, `autorizado`, `rechazado`, `rechazo_configuracion`, `error` o `cancelado`. Solo `recibido` no es final. |
| `codEstado` | `number` | Código numérico del resultado; su primer dígito es el `estado`. En `recibido` es 1001, sin clave de acceso, o 1002, con `claveAcceso`; en `autorizado`, 2001; y cuando no se autorizó, el código de la causa, por ejemplo 3001 (`rechazo_sri`) o 4002 (`firma_no_valida`). Compáralo con las constantes de `CodEstado`. |
| `msgError` | `string \| undefined` | Descripción general y fija del código. No viene con `recibido` ni con `autorizado`. |
| `errores` | `string[]` | Detalle del resultado; en un rechazo del SRI trae su mensaje. Viene siempre y está vacío si no hay detalle. |
| `idOperacion` | `string` | El identificador consultado. |
| `urlEstado` | `string \| null` | URL completa del seguimiento. |
| `ambiente` | `number \| null` | `1` pruebas, `2` producción. |
| `tipoDocumento` | `string \| null` | Tipo de comprobante (`01`, `03`, `04`, `05`, `06`, `07`). |
| `numeroDocumento` | `string \| null` | Número del comprobante, por ejemplo `001-001-000000123`. |
| `referenciaExterna` | `string \| null` | La `referenciaExterna` que enviaste al emitir. |
| `claveAcceso` | `string \| null` | Clave de acceso de 49 dígitos; es `null` con el `codEstado` 1001. |
| `fhRecibido` | `string \| null` | Momento en que la API aceptó la emisión (ISO 8601 con zona horaria). |
| `fhAutorizacion` | `string \| null` | Momento de la autorización del SRI, cuando existe. No la uses para decidir; decide con `estado`. |

Qué hacer ante cada estado se explica en
[Seguimiento de una operación](/v1/guias/consulta-operacion).

## Estados tipados

`Operation`, `Admission` y `Comprobante` conservan los campos de la API (`estado`,
`codEstado`, `tipoDocumento`). El SDK exporta constantes y funciones para
compararlos sin errores de escritura. Un valor que el SDK no conoce no rompe tu
código, porque las funciones devuelven `"desconocido"`, o `null` en el caso de
`tipoComprobante`, y el texto original queda en el campo.

| Constante o función | Valores |
|---|---|
| `CodEstado` / `estadoDeCodEstado(codEstado)` | Constantes numéricas del [catálogo de `codEstado`](/v1/guias/errores#catalogo-de-codestado), con el nombre de cada código en PascalCase, por ejemplo `CodEstado.RechazoSri` (3001), `CodEstado.ComprobanteInvalido` (3002) o `CodEstado.LimiteSolicitudes` (5005). `estadoDeCodEstado` devuelve el estado que corresponde al primer dígito, incluso para un código que tu versión del SDK todavía no conoce. |
| `EstadoOperacion` / `estadoOperacion(operacion)` | `Recibido` (`recibido`), `Autorizado`, `Rechazado`, `RechazoConfiguracion` (`rechazo_configuracion`), `Error`, `Cancelado`, `Desconocido` |
| `TipoComprobante` / `tipoComprobante(tipoDocumento)` | `Factura` (`01`), `LiquidacionCompra` (`03`), `NotaCredito` (`04`), `NotaDebito` (`05`), `GuiaRemision` (`06`), `Retencion` (`07`); `null` si el código no se conoce |
| `TipoEventoWebhook` / `tipoEventoWebhook(eventType)` | `DocumentoAutorizado` (`document.authorized`), `DocumentoRechazado` (`document.rejected`), `DocumentoFallido` (`document.failed`), `OperacionRequiereAtencion` (`operation.requires_attention`), `Desconocido` |
| `EstadosPublicos` | Los valores de texto de `estado`, por ejemplo `EstadosPublicos.Recibido`. |
| `esFinal(operacion)` | `true` si `estado` es cualquier valor distinto de `recibido`. Sirve también para el cuerpo de un webhook. |
| `esAutorizado(operacion)` | `true` si `estado` es `autorizado`. |

`estadoOperacion` acepta la operación completa, el cuerpo de un webhook o el texto
del campo.

```javascript
// Node.js 18 o superior. Guarda como estado.mjs y ejecuta: node estado.mjs
import { CodEstado, EcuafactClient, EstadoOperacion, estadoOperacion } from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY
});
const operacion = await client.getOperacion("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f");

switch (estadoOperacion(operacion)) {
  case EstadoOperacion.Autorizado:
    console.log("Descarga el RIDE");
    break;
  case EstadoOperacion.Recibido:
    console.log("Consulta mas tarde");
    break;
  case EstadoOperacion.Rechazado:
    if (operacion.codEstado === CodEstado.RechazoSri) {
      console.log(`Corrige y emite un comprobante nuevo: ${operacion.errores.join(" | ")}`);
      break;
    }
  // falls through
  default:
    console.log(`Revisa codEstado ${operacion.codEstado}: ${operacion.msgError} ${operacion.errores.join(" | ")}`);
}
```

## Webhooks

Puedes recibir el resultado del SRI en tu servidor sin consultar en bucle y,
antes de procesar cada entrega, comprobar que te la enviamos nosotros. Cada
entrega trae dos firmas: la cabecera `Ecuafact-Signature` y las cabeceras de
[Standard Webhooks](/v1/guias/webhooks-firma#standard-webhooks).

`construirEventoDesdeCabeceras` acepta cualquiera de las dos. Recibe las
cabeceras de la petición (`req.headers` o un `Headers` de Fetch), las comprueba
contra el cuerpo **crudo** y, si alguna es válida, devuelve el evento tipado. Si
ninguna coincide, está fuera de la tolerancia (300 s por defecto) o el cuerpo no
es un objeto JSON, lanza `EcuafactWebhookException`. Su firma es
`construirEventoDesdeCabeceras(secretos, cabeceras, cuerpo, toleranceSeconds = 300, now?)`.

Si solo recibes la cabecera `Ecuafact-Signature` (`t=<epoch>,v1=<hmac>`), puedes usar
`construirEvento(secretos, cabecera, cuerpo, toleranceSeconds = 300, now?)`, que verifica solo esa cabecera y se
comporta igual.

Las dos funciones aceptan un secreto o un arreglo de secretos, con o sin el prefijo `whsec_` en Standard Webhooks, y la
entrega es válida si coincide con cualquiera; así puedes rotar el secreto sin rechazar entregas. Agrega el
nuevo, publica tu aplicación y quita el anterior cuando las entregas lleguen
firmadas con el nuevo, como se explica en
[Rotación de secreto](/v1/guias/webhooks-firma#rotacion-de-secreto).

El ejemplo siguiente usa el módulo `node:http`, sin dependencias. Guarda tu
secreto en `ECUAFACT_WEBHOOK_SECRET` y, durante una rotación, el anterior en
`ECUAFACT_WEBHOOK_SECRET_ANTERIOR`.

```javascript
// Node.js 18 o superior. Guarda como webhook.mjs y ejecuta: node webhook.mjs
import { createServer } from "node:http";
import { construirEventoDesdeCabeceras, EcuafactWebhookException, TipoEventoWebhook } from "@ecuafact/sdk";

const secretos = [process.env.ECUAFACT_WEBHOOK_SECRET, process.env.ECUAFACT_WEBHOOK_SECRET_ANTERIOR]
  .filter((s) => s);
const procesados = new Set(); // en produccion, una tabla con clave unica

createServer((req, res) => {
  if (req.method !== "POST" || req.url !== "/webhooks/ecuafact") {
    res.writeHead(404).end();
    return;
  }
  const partes = [];
  req.on("data", (parte) => partes.push(parte));
  req.on("end", () => {
    const cuerpoCrudo = Buffer.concat(partes);
    let evento;
    try {
      evento = construirEventoDesdeCabeceras(secretos, req.headers, cuerpoCrudo);
    } catch (error) {
      if (error instanceof EcuafactWebhookException) {
        res.writeHead(401).end();
        return;
      }
      throw error;
    }
    // Deduplica por eventType + resourceId: una repeticion se responde 2xx sin procesar.
    const clave = `${evento.eventTypeRaw}|${evento.resourceId}`;
    if (procesados.has(clave)) {
      res.writeHead(200).end();
      return;
    }
    procesados.add(clave);
    switch (evento.eventType) {
      case TipoEventoWebhook.DocumentoAutorizado:
        console.log("Autorizado", evento.idOperacion, evento.claveAcceso);
        break;
      case TipoEventoWebhook.DocumentoRechazado:
        console.log("Rechazo fiscal", evento.idOperacion, evento.codEstado, evento.errores);
        break;
      case TipoEventoWebhook.DocumentoFallido:
        console.log("No emitido", evento.idOperacion, evento.estado, evento.codEstado);
        break;
      case TipoEventoWebhook.OperacionRequiereAtencion:
        // Con probe es el evento de prueba del portal; si no, un aviso: el comprobante sigue
        // recibido (codEstado 1001 o 1002), con el motivo en errores. No reemitas.
        console.log("Aviso", evento.idOperacion, evento.codEstado, evento.errores, "probe =", evento.probe);
        break;
      default:
        console.log("Evento no reconocido", evento.eventTypeRaw);
    }
    res.writeHead(200).end();
  });
}).listen(3000);
```

Para probarlo, configura el destino `https://<tu-dominio>/webhooks/ecuafact` en
el portal y pulsa **Probar**. Tu servidor imprime una línea que empieza con
`Aviso` y termina con `probe = true`, y responde con un 200.

El SDK no administra los destinos de webhooks, solo verifica la firma y construye
el evento. Los destinos los creas, listas, pausas y rotas desde el Portal del
Cliente (**Integración > Eventos**), con el CLI (`ecuafact webhooks`), con el
servidor MCP o con la API REST, como se explica en
[Administrar destinos por API](/v1/guias/webhooks#administrar-destinos-por-api).

Si usas el framework Express.js, lee el cuerpo crudo solo en la ruta del webhook.

```javascript
// Node.js 18 o superior con Express.js 4 o 5 (npm install express). Guarda como webhook-express.mjs
import express from "express";
import { construirEventoDesdeCabeceras, EcuafactWebhookException } from "@ecuafact/sdk";

const app = express();
// express.raw entrega req.body como Buffer con los bytes tal como llegaron.
app.post("/webhooks/ecuafact", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const evento = construirEventoDesdeCabeceras(process.env.ECUAFACT_WEBHOOK_SECRET, req.headers, req.body);
    console.log(evento.eventTypeRaw, evento.resourceId);
    res.sendStatus(200);
  } catch (error) {
    res.sendStatus(error instanceof EcuafactWebhookException ? 401 : 500);
  }
});
app.listen(3000);
```

> [!WARNING]
> Verifica la firma sobre el cuerpo crudo. No apliques un parser JSON a la ruta
> del webhook antes de `construirEventoDesdeCabeceras`, porque un JSON reconstruido no coincide
> con la firma.

`WebhookEvent` tiene estos campos:

| Campo | Tipo | Descripción |
|---|---|---|
| `eventType` | `TipoEventoWebhook` | Tipo tipado; `desconocido` si el SDK no conoce el valor. |
| `eventTypeRaw` | `string` | `eventType` tal como llegó. |
| `resourceId` | `string` | En los eventos `document.*`, el `idOperacion`; en el evento de prueba, el identificador del destino. |
| `occurredAtUtc` | `string` | Momento del evento (UTC, ISO 8601), tal como llegó; no cambia en los reintentos. |
| `occurredAt` | `Date \| null` | `occurredAtUtc` convertido a `Date`; `null` si no se pudo interpretar. |
| `idOperacion` | `string \| null` | Operación del comprobante. |
| `estado` | `string \| null` | El mismo `estado` del seguimiento: `autorizado`, `rechazado`, `rechazo_configuracion` o `error`, y `recibido` en el aviso `operation.requires_attention`. |
| `ruc` | `string \| null` | Identificación del contribuyente emisor. Sirve para enrutar un destino compartido por varios contribuyentes; es `null` en el evento de prueba. |
| `tipoDocumento` | `string \| null` | Tipo de comprobante (`01` a `07`), cuando el evento lo trae. |
| `claveAcceso` | `string \| null` | Clave de acceso del comprobante. |
| `codEstado` | `number \| null` | Código numérico del resultado, por ejemplo 2001 en `document.authorized`, 3001 (`rechazo_sri`) en `document.rejected` o 4002 (`firma_no_valida`) en `document.failed`. Decide con `estado` y `codEstado`, no solo con `eventType`. |
| `msgError` | `string \| null` | Descripción fija del código; `null` cuando no hay error. |
| `errores` | `string[]` | Detalle del resultado; en un rechazo del SRI trae su mensaje. Vacío si no hay detalle. |
| `fhAutorizacion` | `string \| null` | Momento de la autorización del SRI, cuando existe. |
| `probe` | `boolean` | `true` en el evento de prueba del portal. |
| `cuerpo` | `Record<string, unknown>` | Cuerpo completo ya interpretado, incluidos campos que el SDK no tipa. |

Si solo necesitas saber si la firma es válida, usa
`verificarWebhook(secretos, cabeceras, cuerpo, now?, toleranceSeconds?)`, que acepta
cualquiera de las dos firmas, o `verify(secretos, cabecera, cuerpo, now?, toleranceSeconds?)`, que
comprueba solo `Ecuafact-Signature`. Ambas devuelven `boolean` y nunca lanzan una excepción; aceptan un
secreto o un arreglo, y el cuerpo como `string`, `Buffer` o `Uint8Array`.
`verificarStandardWebhooks(secretos, { webhookId, webhookTimestamp, webhookSignature }, cuerpo)` comprueba solo la firma
de Standard Webhooks. Para tus pruebas automatizadas,
`sign(secreto, segundosUnix, cuerpo)` calcula una cabecera `Ecuafact-Signature`
válida.

Qué hacer ante cada evento está en [Webhooks](/v1/guias/webhooks), y el
algoritmo de la firma, en [Verificación de firma](/v1/guias/webhooks-firma).

## Errores

Todas las excepciones del SDK heredan de `EcuafactSdkException`, que extiende
`Error`, y las que vienen de una respuesta de la API heredan además de
`EcuafactApiException`. Pregunta primero por las específicas y al final por
`EcuafactApiException` o `EcuafactSdkException`.

| Excepción | Hereda de | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| `EcuafactConfigurationException` | `EcuafactSdkException` | Falta la API Key o la URL, la URL no es HTTPS, tiene usuario, consulta o fragmento, o termina en `/v1`, la API Key tiene espacios o caracteres de control, una opción del cliente o de `RequestOptions` es inválida, o un constructor de comprobantes recibe una escala o un modo de redondeo inválido. | Corrige la configuración. No llama a la API. |
| `EcuafactConnectionException` | `EcuafactSdkException` | Sin conexión con la API, o la respuesta se cortó, tras agotar los intentos. También se lanza cuando la API responde con éxito (2xx) pero el cuerpo no es JSON válido. | Reintenta más tarde con la misma `idempotencyKey`. Si estabas emitiendo, repite la emisión con esa clave para recuperar su resultado sin duplicar el comprobante. |
| `EcuafactTimeoutException` | `EcuafactSdkException` | Se agotó `timeoutMs` en el último intento o `totalTimeoutMs` de la llamada. | Reintenta con la misma `idempotencyKey`; si emitías, consulta antes el seguimiento. |
| `EcuafactWebhookException` | `EcuafactSdkException` | Firma de webhook inválida o vencida, o cuerpo que no es un objeto JSON. | Responde 401 y no proceses el evento. |
| `EcuafactAuthException` | `EcuafactApiException` | HTTP 401 o 403, con el `codEstado` 3009 (`credenciales_invalidas`), 3010 (`ip_no_autorizada`) o 3011 (`acceso_denegado`). | Corrige la API Key, registra la IP o revisa que el contribuyente y el tipo estén habilitados. |
| `EcuafactValidationException` | `EcuafactApiException` | HTTP 400 o 422, con el `codEstado` 3002 (`comprobante_invalido`), 3003 (`solicitud_invalida`), 3007 (`version_no_soportada`) o 3012 (`filtros_invalidos`). | Corrige según `errores`. Un 422 consume 1 documento como intento. |
| `EcuafactNotFoundException` | `EcuafactApiException` | HTTP 404, con el `codEstado` 3013 (`no_encontrado`), o sin `codEstado` si la ruta no existe y la respuesta no trae cuerpo de error. | Verifica el `idOperacion`, la `claveAcceso` o la identificación. |
| `EcuafactConflictException` | `EcuafactApiException` | HTTP 409, con el `codEstado` 3004 (`comprobante_duplicado`), 3005 (`conflicto_idempotencia`) o 3014 (`correo_no_disponible`). | Mira el `codEstado` en la tabla de códigos de abajo. |
| `EcuafactRateLimitException` | `EcuafactApiException` | HTTP 429 con un `codEstado` distinto de 4004, normalmente 5005 (`limite_solicitudes`). | Espera `retryAfterMs` y reintenta con la misma `idempotencyKey`. El SDK ya lo reintenta por defecto, así que la excepción llega cuando se agotan los intentos o si desactivaste `retryRateLimited`. |
| `EcuafactQuotaException` | `EcuafactApiException` | HTTP 429 con el `codEstado` 4004 (`cupo_agotado`). | Amplía el cupo ([`GET /v1/consumo`](/v1/guias/consumo)). No reintentes. |
| `EcuafactServerException` | `EcuafactApiException` | HTTP 5xx, con el `codEstado` 5001 (`error_interno`), 5002 (`servicio_no_disponible`), 5003 (`error_dependencia`) o 5004 (`tiempo_agotado`), tras agotar los intentos si el estado es reintentable. | Si `esReintentable` es `true`, reintenta más tarde con la misma `idempotencyKey`. Un 501 no se reintenta. |
| `EcuafactApiException` | `EcuafactSdkException` | Cualquier otro estado de error de la API, por ejemplo 413 con el `codEstado` 3006 (`cuerpo_excedido`). | Revisa `codEstado`, `msgError` y `errores`. |
| `EcuafactTipoComprobanteException` | `EcuafactSdkException` | El filtro `tipoDocumento` de `listarOperaciones` no es uno de los seis tipos. | Usa un código (`01`) o un nombre (`factura`), como se explica en [Tipo de comprobante](#tipo-de-comprobante-y-ruta). No llama a la API. |
| `EcuafactResponseTooLargeException` | `EcuafactSdkException` | El cuerpo de la respuesta supera el tope `maxResponseBytes`. Trae `limite` y `bytesLeidos`. | Sube el tope o desactívalo si esperas archivos más grandes. No se reintenta. |
| `EcuafactSdkException` | `Error` | Otros errores locales: `Idempotency-Key` inválida, `idOperacion` que no es UUID, importe con formato inválido, `identificacion` que no tiene de 5 a 13 dígitos, un identificador de ruta vacío, `.` o `..`, uso incorrecto de un constructor de comprobantes (un `Date` inválido, `linea` antes de `destinatario` o datos del documento sustento antes de `docSustento`), falta el contribuyente por defecto, parámetro obligatorio vacío o respuesta no reconocida. | Corrige la llamada. |

| Propiedad de `EcuafactApiException` | Tipo | Descripción |
|---|---|---|
| `codEstado` | `number \| undefined` | Código numérico del [catálogo de `codEstado`](/v1/guias/errores#catalogo-de-codestado), por ejemplo 3002 o 3004. Úsalo para decidir, comparándolo con las constantes de `CodEstado`. `undefined` si la respuesta no trae cuerpo de error. |
| `estado` | `string \| undefined` | `estado` de la respuesta de error, como `rechazado`, `rechazo_configuracion` o `error`; si no llegó, el que indica el primer dígito de `codEstado`. |
| `msgError` | `string \| undefined` | Descripción general y fija del código. Muéstrala o regístrala, pero no la uses para decidir. |
| `estadoHttp` | `number` | Estado HTTP. |
| `errores` | `string[]` | Detalle específico del error, como la ruta del campo que falla en un 3002. Vacío cuando no hay detalle. |
| `correlationId` | `string \| undefined` | Cabecera `X-Correlation-Id`. Inclúyelo al pedir soporte. |
| `idempotencyKey` | `string \| undefined` | Clave usada en la emisión; reutilízala al reintentar. |
| `retryAfterMs` | `number \| null` | Espera indicada por la cabecera `Retry-After`, en milisegundos; `null` si no llegó. |
| `esReintentable` | `boolean` | `true` si repetir la misma solicitud puede funcionar: 408, 425, 500, 502, 503, 504 y el 429 con el `codEstado` 5005. El 429 con 4004 (cupo agotado) no es reintentable. |

Si una emisión recibe una respuesta 2xx que el SDK no puede leer, la excepción
conserva la `Idempotency-Key` y el correlativo de la solicitud; repite la emisión
con esa misma clave y no se duplica el comprobante. En Node.js, esa excepción es
`EcuafactConnectionException`, que se lanza cuando el cuerpo no es JSON y trae la
clave en `idempotencyKey` y el `X-Correlation-Id` en `correlationId`.

`EcuafactConnectionException` y `EcuafactTimeoutException` traen
`idempotencyKey`, `correlationId` (el de la respuesta o, si no llegó, el que
enviaste en `RequestOptions`) y la causa original en `cause`.

```javascript
// Node.js 18 o superior. Guarda como errores.mjs y ejecuta: node errores.mjs
import { readFile } from "node:fs/promises";
import {
  EcuafactClient,
  EcuafactApiException,
  EcuafactConnectionException,
  EcuafactQuotaException,
  EcuafactRateLimitException,
  EcuafactTimeoutException,
  EcuafactValidationException
} from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY
});
const comprobante = JSON.parse(await readFile("comprobante.json", "utf8"));

try {
  const r = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0001");
  console.log(r.admission.estado, r.admission.idOperacion);
} catch (error) {
  if (error instanceof EcuafactValidationException) {
    // Comprobante invalido (campos o reglas fiscales): corrige; no reintentes igual.
    error.errores.forEach((detalle) => console.error(detalle));
  } else if (error instanceof EcuafactQuotaException) {
    console.error("Cupo agotado: compra un paquete. No reintentes.");
  } else if (error instanceof EcuafactRateLimitException) {
    console.error(`Limite de solicitudes: espera ${error.retryAfterMs ?? 1000} ms y reintenta con ${error.idempotencyKey}.`);
  } else if (error instanceof EcuafactApiException) {
    console.error(error.estadoHttp, error.codEstado, error.msgError, error.errores, "reintentable =", error.esReintentable,
      "correlation =", error.correlationId);
  } else if (error instanceof EcuafactConnectionException || error instanceof EcuafactTimeoutException) {
    // Sin conexion o sin respuesta: reintenta mas tarde con la MISMA Idempotency-Key.
    console.error(error.message, "clave =", error.idempotencyKey);
  } else {
    throw error;
  }
}
```

Estos son los códigos que verás con más frecuencia. El catálogo completo, con
el nombre de cada código, está en
[Errores](/v1/guias/errores#catalogo-de-codestado), y las constantes de `CodEstado`
llevan ese mismo nombre, escrito con la convención del lenguaje.

| `codEstado` | Nombre | HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|---|
| 3009 | `credenciales_invalidas` | 401 | API Key ausente o inválida. | Corrige la API Key. No reintentes sin cambiar nada. |
| 3010 | `ip_no_autorizada` | 403 | La IP no está permitida o no se pudo identificar. | Registra tu IP en **Cuenta > IP permitidas** o llama directo a la URL de la API, sin proxies intermedios; si persiste, contacta a soporte con el `correlationId`. |
| 3011 | `acceso_denegado` | 403 | Contribuyente o tipo de comprobante no habilitado, `ruc` distinto del contribuyente de la ruta, o sin paquete de documentos vigente. | Revisa `getContexto()` (`puedeEmitir`, `tiposComprobante`). |
| 5005 | `limite_solicitudes` | 429 | Superaste el límite de solicitudes por minuto. | Espera `retryAfterMs` y reintenta con la misma `Idempotency-Key`, aunque el SDK ya lo hace por defecto; reduce el ritmo. |
| 3003 | `solicitud_invalida` | 400 | Cabeceras inválidas (por ejemplo, `Idempotency-Key`) o JSON mal formado. | Corrige según `errores`. |
| 3002 | `comprobante_invalido` | 422 | Campos del comprobante faltantes o mal formados, campos desconocidos o de otro tipo, o una regla fiscal incumplida (totales, impuestos). | Corrige según `errores`; consume 1 documento como intento. |
| 3012 | `filtros_invalidos` | 400 | Filtro de consulta fuera de rango (fechas o `max`) o valor no admitido. | Ajusta los filtros. |
| 3006 | `cuerpo_excedido` | 413 | Cuerpo mayor a 2 MiB en la emisión o 1 MiB en otros `POST`/`PUT`. | Reduce el cuerpo. |
| 3004 | `comprobante_duplicado` | 409 | Ya existe un comprobante con ese número recibido, autorizado o rechazado por el SRI. | No reenvíes; si querías otro comprobante, usa otro `secuencial` u omítelo para que se asigne el siguiente. |
| 3005 | `conflicto_idempotencia` | 409 | Misma `Idempotency-Key` o `referenciaExterna` con otro contenido. | Si es el mismo comprobante, envía el cuerpo original; si es otro, usa claves nuevas. |
| 4004 | `cupo_agotado` | 429 | Se agotó el cupo de documentos. El SDK no lo reintenta. | Revisa `getConsumo()`; compra un paquete. |
| 3013 | `no_encontrado` | 404 | Operación, comprobante, catálogo o RIDE no encontrado. | Verifica el id o la clave; el RIDE existe solo si está autorizado. |
| 5001, 5002, 5003, 5004 | `error_interno`, `servicio_no_disponible`, `error_dependencia`, `tiempo_agotado` | 500, 503, 502, 504 | Error interno, servicio no disponible, o el servicio de validación fiscal falló o no respondió. | El SDK ya reintentó; vuelve a intentar más tarde con la misma `Idempotency-Key`. |

## Idempotencia y reintentos

La `Idempotency-Key` evita emitir dos veces el mismo comprobante si una llamada
se repite, por ejemplo después de un timeout o de una caída de la red.

- Si no la pasas, el SDK genera un UUID sin guiones, lo usa en todos sus
  reintentos y te la devuelve en `resultado.idempotencyKey` o, si falla, en
  `error.idempotencyKey`.
- Te recomendamos pasar un valor estable por intención, como tu número interno
  de factura, o un UUID v4 que guardes junto al documento.
- El SDK valida la clave antes de enviarla con la misma regla de la API: de 1 a
  128 caracteres, solo letras, dígitos y `-` `_` `.` `:` `/`. Si no cumple,
  lanza `EcuafactSdkException` sin llamar a la API.

> [!WARNING]
> Si reintentas una emisión desde tu aplicación, reutiliza la misma
> `Idempotency-Key`. Una clave nueva para el mismo comprobante puede duplicar la
> emisión.

| Situación | Se reintenta | Detalle |
|---|---|---|
| HTTP 408, 425, 500, 502, 503, 504 | Sí | Los configuras con `retryableStatusCodes`. Solo en `GET` y en `POST`/`PUT` con `Idempotency-Key` (la emisión siempre la lleva). |
| HTTP 429 con el `codEstado` 5005 (`limite_solicitudes`) | Sí, salvo con `retryRateLimited: false` | Espera lo que indica `Retry-After` y reintenta. Con `retryRateLimited: false` lanza `EcuafactRateLimitException` con `retryAfterMs`, y decides tú cuándo reintentar. |
| HTTP 429 con el `codEstado` 4004 (`cupo_agotado`) | Nunca | Esperar no repone el cupo. Lanza `EcuafactQuotaException`. |
| Error de red o timeout de un intento | Sí | Se reintenta en las mismas condiciones; al agotar los intentos lanza `EcuafactConnectionException` o `EcuafactTimeoutException`. |
| Consultas (`getContexto`, `getOperacion`, descargas de RIDE/XML, `getConsumo`, perfil, consultas SRI) | Sí | Se reintentan porque son `GET`. |
| `validar<Tipo>` y `validar<Tipo>En` | Sí | No llevan `Idempotency-Key`, pero se reintentan porque validar no tiene efectos. |
| `actualizarPerfil`, `actualizarLogo` | No | No llevan `Idempotency-Key`, así que un reintento automático podría repetir el efecto. |
| Cualquier otro 4xx | No | Se lanza la excepción de inmediato. |

Entre intentos, el SDK espera `retryBaseDelayMs` x intento con `linear` o
`retryBaseDelayMs` x 2^(intento-1) con `exponential`. A esa espera le suma un
margen aleatorio de hasta `retryJitterMs` x intento con `linear` y de hasta
`retryJitterMs` con `exponential`. Si la respuesta trae un `Retry-After` mayor y
`respectRetryAfter` es `true`, espera ese tiempo. La espera nunca supera
`maxRetryDelayMs`. Si con `totalTimeoutMs` configurado la siguiente espera
superaría el tope, el SDK no reintenta y lanza el error del último intento.

## Opciones por llamada

Puedes cambiar el tiempo máximo, el tope total, la correlación, la información adicional,
los reintentos o la cancelación de una sola llamada sin tocar la configuración del cliente.

Todos los métodos que llaman a la API aceptan un último parámetro opcional
`opciones?: RequestOptions`. También lo aceptan `esperarResultado` (como tercer parámetro) y los métodos de la vista
`client.para(...)`. Lo que no indiques se toma de la configuración del cliente.

| Campo | Tipo | Qué hace |
|---|---|---|
| `timeoutMs` | `number` | Tiempo máximo de cada intento, en milisegundos. Reemplaza `timeoutMs` del cliente solo en esta llamada. Mayor que 0. |
| `totalTimeoutMs` | `number` | Tope de toda la llamada, incluidos reintentos y esperas, en milisegundos. Con `0` no hay límite. Al superarlo rechaza con `EcuafactTimeoutException`. |
| `correlationId` | `string` | Se envía en la cabecera `X-Correlation-Id`. De 1 a 64 caracteres `A-Z a-z 0-9 . _ -`. |
| `additionalInfo` | `string` | Se envía en la cabecera `X-Additional-Info` solo en esta llamada y reemplaza el `additionalInfo` del cliente. Con `null` o sin valor usa el del cliente, y con `""` no envía la cabecera en esta llamada. Sigue las mismas reglas que la opción del cliente, descritas en [Información adicional](#informacion-adicional). |
| `reintentos` | `boolean` | `false` desactiva los reintentos solo en esta llamada. `true` no los reactiva si el cliente tiene `retryTransientFailures: false`. |
| `signal` | `AbortSignal` | Cancela la llamada en curso y las esperas entre reintentos. La promesa se rechaza con `signal.reason` (`AbortError` por defecto). |
| `validarAntesDeEmitir` | `boolean` | Solo en `emitir<Tipo>` y `emitir<Tipo>En`. Reemplaza el valor del cliente en esta llamada, tanto para activarlo como para desactivarlo. |

La API devuelve la correlación que enviaste. La encuentras en
`resultado.correlationId` de la emisión, en `correlationId` de
`EcuafactApiException` y en `correlationId` de `EcuafactTimeoutException` y
`EcuafactConnectionException`. Si la API no devuelve la cabecera, se usa la que
enviaste.

```javascript
// Node.js 18 o superior. Guarda como opciones.mjs y ejecuta: node opciones.mjs
import { writeFile } from "node:fs/promises";
import { EcuafactClient } from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY,
  additionalInfo: "MiERP/4.2" // cabecera X-Additional-Info en cada solicitud
});

// Un solo intento y correlacion propia para esta consulta.
const contexto = await client.getContexto({
  reintentos: false,
  correlationId: "pedido-2026-0457",
  additionalInfo: "MiERP/4.2 sucursal=norte" // reemplaza al del cliente solo aqui
});
console.log(`Contribuyentes: ${contexto.contribuyentes?.length ?? 0}`);

// Mas tiempo para una descarga grande, con tope total y cancelacion a los 90 s.
const controller = new AbortController();
const temporizador = setTimeout(() => controller.abort(), 90_000);
try {
  const ride = await client.descargarRide(
    "0123456789001",
    "0710202601012345678900110010010000001231234567811",
    { timeoutMs: 60_000, totalTimeoutMs: 120_000, signal: controller.signal }
  );
  await writeFile("ride.pdf", ride.contenido);
} finally {
  clearTimeout(temporizador);
}
```

Reemplaza la `claveAcceso` del ejemplo por la de un comprobante autorizado de tu
emisor. Si pasas un valor inválido, la promesa se rechaza con
`EcuafactConfigurationException` sin llamar a la API. Pasa, por ejemplo, con un
`correlationId` con espacios o de más de 64 caracteres, con un `additionalInfo`
fuera de sus reglas, con un `timeoutMs` menor o igual a 0, con un
`totalTimeoutMs` negativo o con un `signal` que no es un `AbortSignal`.

Si cancelas una emisión, no sabes si la API la recibió. Reintenta después con la
**misma** `Idempotency-Key` y el mismo cuerpo. Si ya se había recibido, la API
responde con el mismo `idOperacion` y el estado actual de la operación.

En `esperarResultado(idOperacion, opciones, llamada)` el tercer parámetro se
aplica a cada consulta; si `opciones.signal` no está, se usa `llamada.signal`
para cancelar también la espera.

## Información adicional

Puedes enviar un dato tuyo en cada solicitud, por ejemplo la versión de tu ERP
o la sucursal que emite, para que ubiquemos tus llamadas cuando nos pidas
soporte. Viaja en la cabecera `X-Additional-Info`; la API la asocia a tu
solicitud y no cambia su respuesta.
Es la única cabecera personalizada que admite el SDK. Las reglas de la API están en
[Límites](/v1/guias/limites#cabeceras).

| Dónde | Qué hace |
|---|---|
| `additionalInfo` en las opciones del cliente | Se envía en todas las solicitudes del cliente, incluidas las consultas de `esperarResultado`, los reintentos y la vista `client.para(...)`. Sin valor o con `""`, no se envía. |
| `additionalInfo` en `RequestOptions` | Reemplaza el valor del cliente solo en esa llamada. Sin valor o con `null` usa el del cliente, y con `""` no envía la cabecera en esa llamada. |

El SDK valida el valor en tu proceso, antes de llamar a la API, con estas reglas:

- Solo caracteres ASCII imprimibles (0x20 a 0x7E): sin tildes, `ñ` ni saltos de línea.
- Sin espacios al inicio ni al final.
- Máximo 256 caracteres.

Si no cumple, el SDK lanza `EcuafactConfigurationException` sin llamar a la API.
El valor no aparece en `console.log`, `util.inspect` ni `JSON.stringify` de las
opciones. No pongas en él la API Key ni datos personales.

```javascript
// Node.js 18 o superior. Guarda como info-adicional.mjs y ejecuta: node info-adicional.mjs
import { EcuafactClient } from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY,
  additionalInfo: "erp=MiERP/4.2; sucursal=001"
});

// Todas las solicitudes llevan X-Additional-Info: erp=MiERP/4.2; sucursal=001
const contexto = await client.getContexto();

// Solo esta llamada lleva otro valor.
await client.getConsumo({ additionalInfo: "erp=MiERP/4.2; sucursal=002; lote=2026-10-08" });

// Esta llamada no envia la cabecera.
await client.getConsumo({ additionalInfo: "" });
console.log(`Contribuyentes: ${contexto.contribuyentes?.length ?? 0}`);
```

| Error | Por qué pasa | Qué hacer |
|---|---|---|
| `EcuafactConfigurationException` al crear el cliente | `additionalInfo` tiene tildes, `ñ`, saltos de línea u otro carácter fuera de 0x20 a 0x7E, espacios al inicio o al final, o más de 256 caracteres. | Corrige el valor: quita tildes y espacios de los extremos y acórtalo. |
| La promesa de una llamada se rechaza con `EcuafactConfigurationException` | El mismo problema en `additionalInfo` de `RequestOptions`. No se llamó a la API. | Corrige el valor de esa llamada. |

## Proxy, TLS y tiempo de conexión

Si necesitas salir por un proxy, confiar en una CA corporativa o limitar el
tiempo de conexión, puedes pasar un `dispatcher` de `undici`, la biblioteca en
la que se apoya el `fetch` de Node.js. Instálala en tu proyecto con
`npm install undici` y pasa también el `fetch` de `undici`, para que el `dispatcher` y el `fetch` sean de la
misma versión sin depender de la que trae tu Node.js.

```javascript
// Node.js 18 o superior. Guarda como proxy.mjs y ejecuta: node proxy.mjs
import { fetch, ProxyAgent } from "undici";
import { EcuafactClient } from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY,
  fetch,
  dispatcher: new ProxyAgent("http://proxy.miempresa.local:8080"),
  retryBackoff: "exponential",
  retryBaseDelayMs: 500,
  retryRateLimited: true,
  totalTimeoutMs: 60000
});
console.log((await client.getContexto()).contribuyentes?.length ?? 0);
```

Para una CA corporativa o un tiempo de conexión propio, usa
`new Agent({ connect: { ca, timeout: 10000 } })` de `undici` como `dispatcher`,
donde `ca` es el contenido PEM del certificado, por ejemplo
`readFileSync("ca-corporativa.pem")`.

## Constructores de comprobantes

Puedes armar la [Estructura del comprobante](/v1/guias/emision) con métodos en
lugar de escribir el JSON.

`ComprobanteBuilder` es opcional y solo ayuda a armar el cuerpo: produce el mismo request de su tipo
(`FacturaRequest`, `NotaCreditoRequest`...) que armas a mano, sin calcular, sin completar valores y sin
lanzar por reglas de negocio. Los campos requeridos, los formatos, los
catálogos, los topes y los importes los valida únicamente la API; para
comprobarlos usa [`validar<Tipo>`](#validar-sin-emitir) o
[`validarAntesDeEmitir`](#validar-antes-de-emitir-opcional). Todo valor que
asignes se envía tal cual.

```javascript
// Node.js 18 o superior. Guarda como constructor.mjs y ejecuta: node constructor.mjs
import { ComprobanteBuilder, EcuafactClient } from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY
});

// Factura a consumidor final: 10.00 mas IVA 15 %. Usa el RUC de tu emisor.
const comprobante = ComprobanteBuilder.factura("0123456789001", "001", "001")
  .referencias("MiERP", "FACTURA-2026-0002")
  .fechaEmision(new Date()) // se formatea en hora de Ecuador
  .comprador("07", "9999999999999", "CONSUMIDOR FINAL")
  .linea("SERV-001", "Servicio de prueba", 1, "10.00", 0, { codigoPorcentaje: "4", tarifa: 15 })
  .pago("01", "11.50")
  .construir();

const validacion = await client.validarFacturaEn("0123456789001", comprobante); // la API decide
console.log(validacion.valido, validacion.errores, validacion.advertencias);

const r = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0002", {
  correlationId: "pedido-2026-0458"
});
console.log(r.admission.estado, r.admission.idOperacion, r.correlationId);
```

Si la API acepta el comprobante, deberías ver `true [] []` y luego
`recibido <idOperacion> pedido-2026-0458`. Si ejecutas el script otro día con la
misma `Idempotency-Key`, la API responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`); en ese caso usa una
`Idempotency-Key` y una `referenciaExterna` nuevas.

| Tipo | Entrada | Métodos propios |
|---|---|---|
| Factura (`01`) | `ComprobanteBuilder.factura(ruc, estab, ptoEmi)` | `comprador(tipo, identificacion, razonSocial, direccion?)`, `linea`, `propina`, `moneda`, `pago(formaPago, total?, plazo?, unidadTiempo?)` |
| Liquidación de compra (`03`) | `ComprobanteBuilder.liquidacionCompra(...)` | `proveedor(tipo, identificacion, razonSocial, direccion?)`, `linea`, `moneda`, `pago` |
| Nota de crédito (`04`) | `ComprobanteBuilder.notaCredito(...)` | `comprador`, `documentoModificado(codDocModificado, numDocModificado, fecha, totalDocumentoSustento?)`, `motivo(texto)`, `linea` (con `codigoInterno`), `moneda` |
| Nota de débito (`05`) | `ComprobanteBuilder.notaDebito(...)` | `comprador`, `documentoModificado(codDocModificado, numDocModificado, fecha)`, `iva(tarifa)`, `motivo(razon, valor)`, `pago` |
| Guía de remisión (`06`) | `ComprobanteBuilder.guiaRemision(...)` | `traslado(dirPartida, fechaIni, fechaFin)`, `transportista(tipo, identificacion, razonSocial, placa)`, `destinatario(identificacion, razonSocial, direccion, motivoTraslado, opciones?)`, `linea(codigoInterno, descripcion, cantidad, opciones?)` |
| Retención (`07`) | `ComprobanteBuilder.retencion(...)` | `sujetoRetenido(tipo, identificacion, razonSocial)`, `periodoFiscal("MM/yyyy")`, `parteRelacionada(boolean)`, `docSustento({...})`, `impuestoDocSustento(...)`, `retencion(codigo, codigoRetencion, base, porcentaje, valor?)`, `pago(formaPago, total?)` |

Todos los constructores tienen además `referencias(origen, externa)`, `secuencial`,
`dirEstablecimiento`, `infoAdicional(nombre, valor)`, `info({...})` (asigna
campos del `Info*` de su tipo tal cual) y `construir()`, que devuelve una copia independiente.
`fechaEmision` acepta un texto `dd/MM/yyyy` o un `Date`, que se formatea en la
hora de Ecuador, y existe en todos salvo la guía de remisión, que usa
`traslado`.

Algunos métodos tienen reglas propias:

- En `linea(codigo, descripcion, cantidad, precioUnitario, descuento?, iva?, opciones?)`,
  `descuento` es un importe en dólares e `iva` un objeto `{ codigoPorcentaje, tarifa }`
  como los acepta la API, por ejemplo `{ codigoPorcentaje: "4", tarifa: 15 }`.
  El séptimo parámetro lleva el ICE y otros datos de la línea, por ejemplo
  `linea(..., { codigoPorcentaje: "4", tarifa: 15 }, { ice: { codigoPorcentaje: "3011", tarifa: 10 } })`;
  también acepta `codigoAuxiliar`, `precioTotalSinImpuesto` y `detallesAdicionales`
  (en la nota de crédito, `codigoAdicional` en lugar de `codigoAuxiliar`). `linea(detalle)` con un
  objeto agrega la línea tal cual.
- En la guía de remisión, `linea` agrega el bien al **último** destinatario, así
  que llama antes a `destinatario(...)`; si no, lanza `EcuafactSdkException`.
- En la retención, `impuestoDocSustento`, `retencion` y `pago` se aplican al
  **último** documento sustento, así que llama antes a `docSustento(...)`; si
  no, lanza `EcuafactSdkException`. `docSustento` envía `pagoLocExt` solo si lo
  indicas.

Los importes que das como texto decimal (`"11.50"`) se envían como número JSON
literal, sin pasar por `number`, para no perder precisión.

### Reglas de negocio solo en la API

Las reglas de negocio de los comprobantes viven solo en la API, de modo que un
cambio de regla no te obliga a actualizar el SDK. Por eso el SDK no calcula
totales ni valida reglas fiscales; solo valida localmente lo que evita una
petición mal construida: la identificación, la `claveAcceso` y los UUID de la
ruta, el tipo de documento que elige el método, la `Idempotency-Key`, que
`pagina` y `tamanoPagina` sean enteros, y la firma de los webhooks. Los importes
con formato inválido, como `"10,50"`, lanzan `EcuafactSdkException`
porque no se pueden serializar sin perder precisión.

## Métodos

`<Tipo>` es `Factura`, `LiquidacionCompra`, `NotaCredito`, `NotaDebito`, `GuiaRemision` o `Retencion`, y cada combinación
es un método propio (por ejemplo `emitirNotaDebito` o `validarGuiaRemisionEn`). Todos los métodos devuelven una `Promise`, salvo `para`, que devuelve la vista
del contribuyente. La identificación que reciben es siempre el
valor `identificacion` del contexto. Todos los que llaman a la API aceptan
`opciones?: RequestOptions` como último parámetro.

| Método | Endpoint | Devuelve |
|---|---|---|
| `getContexto()` | `GET /v1/contexto` | `Contexto` |
| `emitir<Tipo>(comprobante, idempotencyKey?)` | `POST /v1/contribuyentes/{identificacion por defecto}/{ruta del tipo}` (ver [Tipo de comprobante y ruta](#tipo-de-comprobante-y-ruta)) | `EmisionResultado` |
| `emitir<Tipo>En(identificacion, comprobante, idempotencyKey?)` | `POST /v1/contribuyentes/{identificacion}/{ruta del tipo}` | `EmisionResultado` |
| `validar<Tipo>(comprobante)` | `POST /v1/contribuyentes/{identificacion por defecto}/{ruta del tipo}/validar` | `ValidacionComprobante` (ver [Validar sin emitir](#validar-sin-emitir)) |
| `validar<Tipo>En(identificacion, comprobante)` | `POST /v1/contribuyentes/{identificacion}/{ruta del tipo}/validar` | `ValidacionComprobante` |
| `listarOperaciones(filtro?)` | `GET /v1/operaciones` | `PaginaComprobantes` (ver [Listado de operaciones](#listado-de-operaciones)) |
| `getSalud()` | `GET /salud` | `Salud` (`status` y `cuerpo`) |
| `getEstadoServicio()` | `GET /estado` | `EstadoServicio` (ver [Estado del servicio y catálogos](#estado-del-servicio-y-catalogos)). No envía la API Key. |
| `listarCatalogos()` | `GET /v1/catalogos` | `Catalogos` |
| `getCatalogo(nombre)` | `GET /v1/catalogos/{nombre}` | `CatalogoDetalle` |
| `getOperacion(idOperacion)` | `GET /v1/operaciones/{idOperacion}` | `Operation`. `idOperacion` debe ser un UUID. |
| `consultarOperacion(idOperacion)` | `GET /v1/operaciones/{idOperacion}` | `Operation` (alias) |
| `esperarResultado(idOperacion, { intervaloMs?, maximoMs?, signal? }, llamada?)` | `GET /v1/operaciones/{idOperacion}` en bucle | `Operation`: la última leída (ver [Seguimiento y resultado](#seguimiento-y-resultado)). |
| `descargarRide(identificacion, claveAcceso)` | `GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/ride` | `ArchivoComprobante` (PDF) |
| `descargarXml(identificacion, claveAcceso)` | `GET /v1/contribuyentes/{identificacion}/comprobantes/{claveAcceso}/xml` | `ArchivoComprobante` (XML del comprobante autorizado) |
| `getConsumo()` | `GET /v1/consumo` | `QuotaBucket` |
| `getPerfil(identificacion)` | `GET /v1/contribuyentes/{identificacion}/perfil` | `PerfilEmisor` |
| `actualizarPerfil(identificacion, cambios)` | `PUT /v1/contribuyentes/{identificacion}/perfil` | `PerfilEmisor` |
| `actualizarLogo(identificacion, contenido, contentType, nombreArchivo)` | `POST /v1/contribuyentes/{identificacion}/perfil/logo` | `PerfilEmisor` (ver [Logo del perfil](#logo-del-perfil)) |
| `consultarContribuyente(identificacion, fusionar = true, fuente?)` | `GET /v1/consultas/contribuyentes/{identificacion}` | `ContribuyenteConsulta` |
| `buscarContribuyentes(apellidos, nombres?, clase?, max?)` | `GET /v1/consultas/contribuyentes` | `BusquedaContribuyente[]` |
| `listarEstablecimientos(ruc, filtro?)` | `GET /v1/consultas/establecimientos/{ruc}` | `EstablecimientosContribuyente`. `filtro` acepta `Todos`, `SoloActivos`, `SoloCerrados`, `SoloMatriz` o `SoloSucursales`. |
| `validarIdentificacion(numero)` | `GET /v1/consultas/identificacion/validar/{numero}` | `ValidacionIdentificacion` (revisa `valido`) |
| `decodificarClaveAcceso(claveAcceso)` | `GET /v1/consultas/comprobantes/decodificar/{claveAcceso}` | `ClaveAccesoDecodificada` |
| `para(identificacion)` | - (no llama a la API) | `EcuafactContribuyente` (ver [Varios contribuyentes](#varios-contribuyentes)) |
| `construirEventoDesdeCabeceras(...)`, `construirEvento(...)`, `verificarWebhook(...)`, `verificarStandardWebhooks(...)`, `verify(...)` y `sign(...)` | - (funciones exportadas, locales) | `WebhookEvent`, `boolean` o `string` (ver [Webhooks](#webhooks)) |

Ten en cuenta además estos detalles de los métodos y de sus tipos:

- Los métodos `emitir<Tipo>` y `emitir<Tipo>En` no validan el contenido del comprobante: lo envían y
  propagan el 422 de la API como `EcuafactValidationException`.
- Si no configuras `identificacion` en las opciones del cliente, `emitir<Tipo>` y
  `validar<Tipo>` lanzan `EcuafactSdkException`. En ese caso usa
  `emitir<Tipo>En`, `validar<Tipo>En` o `client.para(...)`.
- `ArchivoComprobante` tiene `contenido` (`Uint8Array`) y `contentType`. Las
  descargas solo existen con el comprobante autorizado; ver [Descargar XML](/v1/guias/consulta-xml).
- `QuotaBucket` tiene `limiteDocumentos`, `reservados`, `consumidos`,
  `disponibles`, `vigenteHasta` y los campos `...Extra`, que se mantienen por compatibilidad y valen 0,
  que se explican en [Consumo](/v1/guias/consumo). Cada comprobante autorizado
  o rechazado consume un documento de tu cupo, y uno cancelado lo libera.
- `actualizarPerfil` recibe solo los campos editables: `nombreComercial`,
  `direccionMatriz`, `correo`, `telefono`, `ciudad` y `provincia`, descritos en
  [Perfil del emisor](/v1/guias/perfil-emisor).

## Importes exactos

En JavaScript un `number` es binario, y por eso `0.1 + 0.2` da
`0.30000000000000004`. Para
enviar importes exactos, los campos de importe, cantidad, precio y tarifa de la
solicitud aceptan `number` o `string` (tipo `Importe`). Un texto decimal con
punto, como `"11.50"`, se envía como número JSON literal (`11.50`), sin pasar
por `number`. Un texto con otro formato (por ejemplo `"10,50"`) se rechaza con
`EcuafactSdkException` antes de llamar a la API. Los campos `valor` de
`infoAdicional` y `detallesAdicionales` son texto y se envían como texto.

```javascript
// Node.js 18 o superior. Guarda como importes.mjs y ejecuta: node importes.mjs
import { readFile } from "node:fs/promises";
import { EcuafactClient } from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY
});
const comprobante = JSON.parse(await readFile("comprobante.json", "utf8"));

// Calcula en centavos enteros y envia el resultado como texto con 2 decimales.
const baseCentavos = 1000;                              // 10.00
const ivaCentavos = Math.round(baseCentavos * 15 / 100); // 1.50
comprobante.info.totalSinImpuestos = (baseCentavos / 100).toFixed(2);              // "10.00"
comprobante.info.importeTotal = ((baseCentavos + ivaCentavos) / 100).toFixed(2);  // "11.50"

const r = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0001");
console.log(r.admission.estado, r.admission.idOperacion);
```

En las respuestas, los importes (por ejemplo `Comprobante.total`) llegan como
`number`. En TypeScript, si lees un importe de tu propio request (por ejemplo `FacturaRequest`)
para calcular, su tipo es `number | string | null`, así que conviértelo con
`Number(...)`. Las
reglas de cálculo de cada comprobante están en [Factura](/v1/guias/emision-01).

## Varios contribuyentes

Si no configuras `identificacion` en las opciones, usa los métodos `...En` o una
vista por contribuyente. La vista repite la identificación por ti en cada
método.

```javascript
// Node.js 18 o superior. Guarda como perfil.mjs y ejecuta: node perfil.mjs
import { EcuafactClient } from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY
});

const matriz = client.para("0123456789001");

const perfil = await matriz.getPerfil();
console.log(perfil.razonSocial, perfil.identificacion);
```

La vista `EcuafactContribuyente` tiene estos métodos, y todos aceptan
`RequestOptions` al final.

| Método | Equivale a |
|---|---|
| `emitir<Tipo>(comprobante, idempotencyKey?)` | `client.emitir<Tipo>En(identificacion, comprobante, idempotencyKey)` |
| `validar<Tipo>(comprobante)` | `client.validar<Tipo>En(identificacion, comprobante)` |
| `descargarRide(claveAcceso)` | `client.descargarRide(identificacion, claveAcceso)` |
| `descargarXml(claveAcceso)` | `client.descargarXml(identificacion, claveAcceso)` |
| `getPerfil()` | `client.getPerfil(identificacion)` |
| `actualizarPerfil(cambios)` | `client.actualizarPerfil(identificacion, cambios)` |
| `actualizarLogo(contenido, contentType, nombreArchivo)` | `client.actualizarLogo(identificacion, ...)` |
| `esperarResultado(idOperacion, opciones?, llamada?)` | `client.esperarResultado(idOperacion, opciones, llamada)` |
| `listarOperaciones(filtro?)` | `client.listarOperaciones({ identificacion, ...filtro })` |
| `getConsumo()` | `client.getConsumo()` (el cupo es de la API Key, no del contribuyente) |

## Logo del perfil

Con `actualizarLogo` puedes subir el logo que aparece en el RIDE de tu contribuyente sin
armar la petición `multipart/form-data`; recibes el `PerfilEmisor` actualizado. Acepta PNG o JPEG de hasta 512 KB; el contenido
puede ser `Uint8Array` (incluido `Buffer`), `ArrayBuffer` o `Blob`. Si el
contenido está vacío o falta `contentType` o `nombreArchivo`, lanza
`EcuafactSdkException` sin llamar a la API. La subida no se reintenta
automáticamente.

```javascript
// Node.js 18 o superior. Guarda como logo.mjs y ejecuta: node logo.mjs
import { readFile } from "node:fs/promises";
import { EcuafactClient } from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY
});

const perfil = await client.actualizarLogo("0123456789001", await readFile("logo.png"), "image/png", "logo.png");
console.log(`Logo actualizado para ${perfil.razonSocial}: ${perfil.logo}`);
```

Las reglas del archivo y los errores posibles están en
[Perfil del emisor](/v1/guias/perfil-emisor).

## Listado de operaciones

`listarOperaciones` devuelve una página de los comprobantes emitidos de un
contribuyente (`GET /v1/operaciones`) y no consume cupo. `identificacion` es
obligatoria (si no la indicas, usa la `identificacion` del cliente); los demás
filtros son opcionales: `desde` y `hasta` en formato `yyyy-MM-dd`, `tipoDocumento` (el código
o el nombre del tipo), `buscar` (número, clave de acceso, contraparte o
referencia), `pagina` desde 1 y `tamanoPagina` de 1 a 100. Si un filtro no tiene
el formato esperado, el SDK lanza `EcuafactSdkException` sin llamar a la API.

```js
let pagina = 1;
for (;;) {
  const resultado = await client.listarOperaciones({
    identificacion: "0123456789001",
    desde: "2026-11-01",
    hasta: "2026-11-30",
    pagina,
    tamanoPagina: 50
  });
  for (const fila of resultado.comprobantes) {
    console.log(fila.numeroDocumento, fila.estado, fila.codEstado, fila.total);
  }
  if (!resultado.hayMas) break;
  pagina += 1;
}
```

La respuesta trae `comprobantes`, `pagina`, `tamanoPagina` y `hayMas`; mientras
`hayMas` sea `true`, pide la página siguiente. Cada fila incluye
`claveAcceso`, `numeroDocumento`, `tipoDocumento`, `fechaEmision`,
`identificacionContraparte`, `razonSocialContraparte`, `total`, `estado`,
`codEstado`, `msgError`, `errores` y `fhAutorizacion`. La vista
`client.para(identificacion)` ofrece el mismo método con la identificación fija.

Para comprobar que el servicio responde, `getSalud()` llama a `GET /salud` (sin
API Key) y devuelve el código HTTP y el cuerpo; si la respuesta no es 2xx,
lanza la excepción correspondiente.

## Consultas SRI

Con estos métodos puedes consultar el catastro del SRI, y no consumen cupo.

```javascript
// Node.js 18 o superior. Guarda como sri.mjs y ejecuta: node sri.mjs
import { EcuafactClient } from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY
});

const validacion = await client.validarIdentificacion("0123456789001");
const contribuyente = await client.consultarContribuyente("0123456789001");
const encontrados = await client.buscarContribuyentes("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10);
const establecimientos = await client.listarEstablecimientos("0123456789001", "SoloActivos");
console.log(validacion.valido, contribuyente.razonSocial, encontrados.length, establecimientos);
```

`fuente` admite `Todas`, el valor por defecto, o `SriCatastro`; `clase` admite
`PersonaNatural`, el valor por defecto, `Sociedad` o `SociedadPublica`; y el
`filtro` de establecimientos admite valores como `SoloActivos`. Un valor no
admitido hace que la API responda 400 con el `codEstado` 3012 (`filtros_invalidos`), que el SDK lanza como
`EcuafactValidationException`.

Los parámetros y las respuestas de cada consulta están en
[Contribuyente por identificación](/v1/guias/consulta-contribuyente),
[Contribuyentes por nombre](/v1/guias/consulta-contribuyente-nombre),
[Establecimientos de un RUC](/v1/guias/consulta-establecimientos),
[Validar identificación](/v1/guias/consulta-identificacion) y
[Decodificar clave de acceso](/v1/guias/consulta-clave-acceso).

## Estado del servicio y catálogos

`getEstadoServicio` lee el estado público del servicio, el mismo que describe [Estado del servicio](/v1/guias/estado-del-servicio) (`GET /estado`), y no envía la API Key ni consume cupo. `listarCatalogos` devuelve el índice de catálogos del SRI, con la clave (`nombre`) y una descripción de cada uno. `getCatalogo` recibe esa clave y devuelve las filas del catálogo. Estas dos consultas usan tu API Key y tampoco consumen cupo. Si la clave no existe, el SDK lanza `EcuafactNotFoundException`. Los catálogos cambian pocas veces al año, así que puedes guardar la respuesta en caché por una hora.

`getEstadoServicio` devuelve un `EstadoServicio`:

| Campo | Tipo | Descripción |
|---|---|---|
| `estado` | `string` | Estado global: `operativo`, `degradado`, `caido` o `sin_datos`. |
| `medidoEn` | `string \| null \| undefined` | Momento de la última medición (ISO 8601). Es `null` mientras no hay mediciones. |
| `componentes` | `ComponenteEstado[]` | Componentes monitoreados, cada uno con `nombre` y `estado` (mismos valores que el estado global). |
| `disponibilidad90Dias` | `number \| null \| undefined` | Porcentaje de minutos sin caída en los últimos 90 días. Es `null` si aún no hay muestras. |
| `incidentes` | `IncidentePublico[]` | Incidentes de los últimos 90 días y los abiertos, del más reciente al más antiguo. Arreglo vacío si no hubo ninguno. |
| `incidentes[].inicio` | `string` | Inicio del incidente (ISO 8601). |
| `incidentes[].fin` | `string \| null \| undefined` | Fin del incidente. Falta mientras sigue abierto. |
| `incidentes[].impacto` | `string` | `degradado` o `caido`. |
| `incidentes[].titulo` | `string` | Título breve. |
| `incidentes[].detalle` | `string \| null \| undefined` | Qué significó para las integraciones. Falta si no hay detalle. |

`listarCatalogos` devuelve un objeto `Catalogos` y `getCatalogo`, un `CatalogoDetalle`:

| Campo | Tipo | Descripción |
|---|---|---|
| `catalogos` | `CatalogoResumen[]` | Catálogos disponibles, cada uno con `nombre` (la clave que recibe `getCatalogo`) y `descripcion`. |
| `nombre` | `string` | Clave del catálogo, en `CatalogoDetalle`. |
| `descripcion` | `string` | Descripción breve, en `CatalogoDetalle`. |
| `fuente` | `string` | Tabla o anexo de la ficha técnica del SRI de donde proviene. |
| `items` | `CatalogoItem[]` | Filas del catálogo. |
| `items[].codigo` | `string` | Código tal como va en el comprobante. |
| `items[].descripcion` | `string` | Descripción del código. |
| `items[].valor` | `number \| null \| undefined` | Valor numérico asociado, por ejemplo la tarifa en porcentaje. Falta si el catálogo no lo tiene. |
| `items[].vigenteDesde` | `string \| null \| undefined` | Primer día de vigencia, en formato `yyyy-MM-dd`. Falta si no está acotada por el inicio. |
| `items[].vigenteHasta` | `string \| null \| undefined` | Último día de vigencia, en formato `yyyy-MM-dd`. Falta si sigue vigente. |
| `items[].atributos` | `Record<string, unknown> \| null \| undefined` | Atributos propios del catálogo. Falta si no hay. |

```javascript
// Node.js 18 o superior. Guarda como catalogos.mjs y ejecuta: node catalogos.mjs
import { EcuafactClient } from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://api-sandbox.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY
});

const estado = await client.getEstadoServicio();
console.log(estado.estado, estado.disponibilidad90Dias, estado.incidentes.length);

const { catalogos } = await client.listarCatalogos();
console.log(catalogos.map((c) => c.nombre));

const tarifas = await client.getCatalogo("tarifas-iva");
for (const fila of tarifas.items) {
  console.log(fila.codigo, fila.descripcion, fila.valor);
}
```

El significado de cada catálogo y de sus códigos está en [Catálogos](/v1/guias/catalogos#consultar-los-catalogos-por-api).

## Siguientes pasos

- [Factura](/v1/guias/emision-01): revisa todos los campos y las reglas de cálculo para construir tus comprobantes.
- [Seguimiento de una operación](/v1/guias/consulta-operacion): consulta qué significa cada `estado` y cada `codEstado`.
- [Webhooks](/v1/guias/webhooks): recibe el resultado del SRI sin consultar en bucle.
- [Visión general de los SDK](/v1/guias/sdk): compara los cinco SDK y decide entre SDK o HTTP directo.
