SDK TypeScript

El SDK oficial de Simplo es open source: github.com/SimploHQ/simplo-sdk, publicado como el paquete @simplohq/sdk (licencia MIT).

Los SDKs son complementos oficiales del API REST: el contrato OpenAPI manda y los SDKs lo envuelven. SDKs para .NET y Java están en el roadmap, generados desde el mismo contrato — mientras tanto, cualquier lenguaje integra directo contra la API o con un cliente generado desde la spec.

npm install @simplohq/sdk

Features

• Cero dependencias en runtime — fetch global, corre en Node ≥ 18.17, Deno, Bun y Cloudflare Workers.
• DTEs tipados — los 12 tipos de documento del SII y el ciclo completo de estados como uniones estrictas de TypeScript; los tipos de request/response reflejan el formato de la API.
• Auto-idempotencia — dtes.emit genera una Idempotency-Key por llamada, así que una emisión reintentada nunca puede crear una factura duplicada.
• Auto-reintentos — fallas 429/5xx/de red se reintentan con backoff exponencial, jitter y soporte de Retry-After; las requests no idempotentes nunca se reintentan a ciegas.
• Auto-paginación — for await sobre cualquier listado recorre todas las páginas por ti.
• Verificación de webhooks — implementa el contrato de firma Standard Webhooks (HMAC-SHA256, comparación en tiempo constante, tolerancia de timestamp) que la entrega de webhooks llevará cuando se habilite con la beta.
• Docs listas para agentes — AGENTS.md, llms.txt y docs solo-markdown en el repo, diseñadas para ser leídas por coding agents.

Tour de uso

// Sigue un documento hasta su veredicto en el SII
const current = await simplo.dtes.retrieve(dte.id);
current.estado;             // 'procesando' | 'aceptado' | 'rechazado' | ...
current.tracking?.track_id; // track ID del SII

// Descargas
const pdf = await simplo.dtes.pdf(dte.id, { cedible: true }); // ArrayBuffer
const xml = await simplo.dtes.xml(dte.id);                    // XML firmado

// Auto-paginación
for await (const doc of await simplo.dtes.list({ estado: 'aceptado' })) {
  console.log(doc.folio, doc.monto_total);
}

// Folios (CAF) y certificado
await simplo.folios.upload({ tipo_dte: 33, caf_xml });
await simplo.company.certificate.status(); // { has_certificado, fecha_vencimiento, ... }

// Webhooks
const hook = await simplo.webhooks.create({
  url: 'https://tu-app.example/webhooks/simplo',
  events: ['dte.accepted', 'dte.rejected'],
});
const event = await simplo.webhooks.verify(rawBody, headers, hook.secret!);

Los errores son tipados por status (ValidationError, RateLimitError, …) con code, requestId y details a nivel de campo — ver Errores.

Ejemplos en el repo

• examples/express — endpoint Express mínimo que emite una factura y devuelve el PDF.
• examples/nextjs — route handler de Next.js App Router.

Requisitos

• Node.js ≥ 18.17 (o Deno / Bun / runtimes edge con fetch global)
• TypeScript ≥ 5.0 si consumes los tipos (opcional — JS plano funciona)
• Una cuenta de Simplo con acceso a la API (beta privada — [email protected])

Relacionado

• Quickstart — tu primera emisión con el SDK
• Para coding agents — el playbook de integración