Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
En esta página

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 está al final. Si todavía no decides entre el SDK y la API por HTTP directo, compáralos en SDKs.

Importante

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:

Prompt para agentes

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
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.
  • 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#

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 de tu API Key.

// 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.
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). 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). 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.
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, emite una factura, espera el resultado del SRI con el seguimiento y descarga el RIDE, 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 de la serie estab-ptoEmi. El script reemplaza ruc por el de tu contexto y fechaEmision por la fecha de hoy.

{
  "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.

estab y ptoEmi deben ser un establecimiento y un punto de emisión de tu emisor; el sandbox crea el establecimiento 001 con el punto de emisión 001. Cada campo está explicado en Factura.

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, sin que tu proceso se quede esperando.

// 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#

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 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 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.
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.

Nota

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. 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
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>.

// 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.

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:

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 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.

// 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.

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, 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.

// 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.

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.

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.

// 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.

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

// 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);

Atención

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, y el algoritmo de la firma, en Verificación de 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). 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. 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, 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.

// 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, 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.

Atención

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.
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.

// 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.

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.

// 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.

// 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 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> o validarAntesDeEmitir. Todo valor que asignes se envía tal cual.

// 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) 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<Tipo>En(identificacion, comprobante) POST /v1/contribuyentes/{identificacion}/{ruta del tipo}/validar ValidacionComprobante
listarOperaciones(filtro?) GET /v1/operaciones PaginaComprobantes (ver Listado de operaciones)
getSalud() GET /salud Salud (status y cuerpo)
getEstadoServicio() GET /estado EstadoServicio (ver Estado del servicio y catálogos). 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).
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)
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)
construirEventoDesdeCabeceras(...), construirEvento(...), verificarWebhook(...), verificarStandardWebhooks(...), verify(...) y sign(...) - (funciones exportadas, locales) WebhookEvent, boolean o string (ver 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.
  • QuotaBucket tiene limiteDocumentos, reservados, consumidos, disponibles, vigenteHasta y los campos ...Extra, que se mantienen por compatibilidad y valen 0, que se explican en 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.

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.

// 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.

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.

// 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.

// 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.

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.

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.

// 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, Contribuyentes por nombre, Establecimientos de un RUC, Validar identificación y Decodificar clave de acceso.

Estado del servicio y catálogos#

getEstadoServicio lee el estado público del servicio, el mismo que describe 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.
// 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.

Siguientes pasos#

No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.