SDK de Node.js para SmartDoc

Cliente de Node.js y TypeScript para SmartDoc, el sistema de facturación electrónica para Paraguay. Cubre su API pública y la recepción de sus webhooks.

import { Client, Item, Recipient } from '@araitek/smartdocjs';

const sd = new Client({ apiKey: 'pk_...' });

let factura = await sd.invoices.create({
  recipient: Recipient.entity({ ruc: '80012345-1', socialName: 'Cliente S.A.' }),
  items: [new Item('Consultoría', { quantity: 1, unitAmount: 1_100_000 })],
});

factura = await sd.invoices.waitUntilFinal(factura.id);
console.log(factura.status, factura.cdc);

Eso alcanza para emitir una factura. Los datos del emisor, el timbrado, el establecimiento, el punto de expedición, la clave de idempotencia, el monto total y el desglose de IVA los completa el SDK.

Qué incluye

• Los seis tipos de documento electrónico —factura, recibo, nota de crédito, nota de débito, nota de remisión y autofactura— con sus acciones: anular, reenviar, confirmar o descartar borradores.
• Cálculo de totales y desglose de IVA con aritmética decimal exacta. La API rechaza el documento si el monto no cuadra con los ítems, así que el SDK lo arma.
• Los catálogos de SIFEN completos, con validación local: un valor inválido falla antes de salir a la red, no después de emitir.
• El catálogo geográfico de Paraguay embebido —18 departamentos, 262 distritos, 6419 ciudades—, que la API pública no expone. Una búsqueda por nombre resuelve los seis campos que pide un documento con dirección.
• Recepción de webhooks: verificación de firma, ruteo por tipo de evento y adaptadores para Express, Fastify y cualquier runtime con Request/Response (Hono, Next.js, Deno, Bun).
• Tipos de TypeScript en todo el paquete, y funciona igual desde JavaScript, con import o con require.
• Manejo del límite de tasa, reintentos con backoff, paginación por cursor y claves de idempotencia, sin que haya que pensarlos.

Instalación

npm install @araitek/smartdocjs

Requiere Node.js 18 o superior.

Por dónde seguir

• Primeros pasos — de cero a una factura emitida, con una cuenta demo y sin contratar el servicio.
• Cómo integrar — las tres piezas que hay que implementar, con el código de cada operación.
• Adaptar tu sistema — cómo traducir tu modelo de datos y qué revisar antes de producción.
• Documentos — qué pide cada tipo y qué acciones acepta.
• Webhooks — recibir eventos y verificar la firma.
• Catálogos SIFEN — los valores válidos de cada campo.
• Errores — la jerarquía de errores y qué hacer con cada uno.
• Recetas — migrar desde la API cruda, emitir por lotes, exportar un período.
• Referencia de la API — todas las clases, funciones y tipos del paquete.