SDK TypeScript

@simplohq/sdk — el SDK oficial TypeScript de Simplo, aún no publicado. Hoy, integra directo contra la API REST usando el contrato OpenAPI.

Cuando se publique, el SDK oficial de Simplo será open source (licencia MIT), en github.com/SimploHQ/simplo-node-sdk, como el paquete @simplohq/sdk. Los SDKs son pensados como complementos oficiales del API REST, nunca la única vía: 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.

Features (previstas para el lanzamiento)

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 active.
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 (previsto — no funcional todavía)

// 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 (repo aún privado)

Cuando el repo se haga público, traerá ejemplos runnable:

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

Hoy, el equivalente en curl está en el Quickstart.

Requisitos (cuando se publique)

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 su API key (sandbox self-serve — ver Quickstart)

Integra hoy, sin esperar el SDK

Quickstart — tu primera emisión vía curl (o el cliente HTTP de tu lenguaje) contra la API REST
Para coding agents — el playbook de integración, REST primero
Contrato OpenAPI — genera un cliente en tu lenguaje desde la spec