SDK Node.js

Cliente oficial de la API para Node.js (TypeScript). Cubre autenticacion, idempotencia, reintentos y firma de webhook.

Paquete: @ecuafact/sdk.
Requiere Node.js 18+ (usa fetch nativo).

Como se instala#

npm install @ecuafact/sdk

Configuracion#

import { EcuafactClient } from "@ecuafact/sdk";

const client = new EcuafactClient({
  baseAddress: "https://staging-api.mynexusapi.com/",
  apiKey: process.env.ECUAFACT_API_KEY,
  identificacion: "1790012345001" // solo integraciones de un RUC
});

Opcion	Default	Descripcion
`baseAddress`	-	Direccion base del API (obligatoria; define el ambiente)
`apiKey`	-	API Key (obligatoria)
`identificacion`	-	RUC por defecto (opcional)
`timeoutMs`	`100000`	Tiempo maximo por intento
`userAgent`	`Ecuafact.Sdk/1.0`	User-Agent
`retryTransientFailures`	`true`	Reintenta `408/425/429/5xx`
`maxAttempts`	`3`	Intentos por solicitud
`respectRetryAfter`	`true`	Respeta `Retry-After` en `429`/`503`
`maxRetryDelayMs`	`60000`	Espera maxima entre reintentos

Metodos#

Metodo	Que hace	Devuelve
`emitir(comprobante)`	Emite para el RUC por defecto	`EmisionResultado` (`admission`, `idempotencyKey`)
`emitirEn(ruc, comprobante)`	Emite para un RUC explicito	`EmisionResultado`
`para(ruc)`	Fija un contribuyente	`EcuafactContribuyente`
`getOperacion(idOperacion)`	Consulta el seguimiento de la operacion	`Operation`
`getContexto()`	Contexto de tu API Key	`Contexto`
`getConsumo()`	Cupo disponible	`QuotaBucket`
`listarEmitidos(...)`	Listan comprobantes	`PaginaComprobantes`
`consultarContribuyente(id)`	Consulta un contribuyente en el SRI	`ContribuyenteConsulta`
`buscarContribuyentes(...)`	Busca por nombre	`BusquedaContribuyente[]`
`listarEstablecimientos(ruc)`	Establecimientos de un RUC	`EstablecimientosContribuyente`
`validarIdentificacion(numero)`	Valida el formato (sin red)	`ValidacionIdentificacion`
`decodificarClaveAcceso(clave)`	Descompone una clave de acceso	`ClaveAccesoDecodificada`
`verify(...)`	Verifica la firma de un webhook	`boolean`

Emision#

const comprobante = {
  origenReferencia: "MiERP",
  referenciaExterna: "FACTURA-2026-0001",
  infoTributaria: { ruc: "1790012345001", codDoc: "01", estab: "002", ptoEmi: "001", secuencial: "000000123" },
  info: {
    fechaEmision: "01/01/2026",
    tipoIdentificacionComprador: "04",
    identificacionComprador: "1790012345001",
    razonSocialComprador: "Cliente Ejemplo",
    totalSinImpuestos: 100.0,
    totalDescuento: 0.0,
    totalConImpuestos: [
      { codigo: "2", codigoPorcentaje: "4", baseImponible: 100.0, valor: 15.0 }
    ],
    importeTotal: 115.0,
    moneda: "DOLAR",
    pagos: [{ formaPago: "01", total: 115.0 }]
  },
  detalles: [
    {
      codigoPrincipal: "SERV-001",
      descripcion: "Servicio de ejemplo",
      cantidad: 1,
      precioUnitario: 100.0,
      descuento: 0.0,
      precioTotalSinImpuesto: 100.0,
      impuestos: [
        { codigo: "2", codigoPorcentaje: "4", tarifa: 15.0, baseImponible: 100.0, valor: 15.0 }
      ]
    }
  ]
};

const resultado = await client.emitir(comprobante);
console.log(resultado.admission.idOperacion, resultado.admission.codigo);

Emision con RUC explicito: client.emitirEn("1790012345001", comprobante).

Multi-RUC#

const ruc = client.para("1790099987001");
const pagina = await ruc.listarEmitidos({ pagina: 1, tamanoPagina: 20 });

Estado y consultas#

const operacion = await client.getOperacion("3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f");
const contexto = await client.getContexto();
const cupo = await client.getConsumo();

Consultas SRI#

Consultas al SRI (contribuyentes, establecimientos, identificaciones y claves de acceso). Son de solo lectura, no consumen cupo y usan la misma API Key.

const contribuyente = await client.consultarContribuyente("1760013210001");
const encontrados = await client.buscarContribuyentes("PEREZ LOPEZ", "JUAN", "PersonaNatural", 10);
const establecimientos = await client.listarEstablecimientos("1760013210001", "SoloActivos");
const validacion = await client.validarIdentificacion("1760013210001");
const clave = await client.decodificarClaveAcceso(claveAcceso);

Idempotencia#

idempotencyKey es opcional: si no se envia, el SDK la genera, la reutiliza en los reintentos y la devuelve en resultado.idempotencyKey (y en el error, como EcuafactApiException.idempotencyKey). Al reintentar, reutiliza la clave devuelta. La correlacion de la respuesta queda en resultado.correlationId (o EcuafactApiException.idSeguimiento en error). Los fallos transitorios (408/425/429/5xx) se reintentan respetando Retry-After; el resto de los 4xx no.

Webhooks#

import { verify } from "@ecuafact/sdk";

const valido = verify(secreto, cabecera, cuerpoCrudo, new Date(), 300);

Ve Verificacion de firma y Webhooks.

Errores#

try {
  await client.emitir(comprobante);
} catch (error) {
  if (error instanceof EcuafactApiException) {
    console.error(error.codigo, error.mensaje, error.errores, error.idSeguimiento);
  }
}

EcuafactApiException trae codigo, mensaje, estadoHttp, idSeguimiento, errores e idempotencyKey. Los errores locales son EcuafactSdkException.

Siguientes pasos#

Vision general de los SDK: compara lenguajes y metodos.
Autenticacion: obten y usa tu API Key.
Emision: emite tu primer comprobante.
Verificacion de firma: valida los webhooks entrantes.