# SDK TypeScript

> @simplohq/sdk — el SDK open source de Simplo: cero dependencias, tipos estrictos para los 12 tipos de DTE, idempotencia y reintentos automáticos.

El SDK oficial de Simplo es open source:
[`github.com/SimploHQ/simplo-node-sdk`](https://github.com/SimploHQ/simplo-node-sdk),
publicado como el paquete [`@simplohq/sdk`](https://www.npmjs.com/package/@simplohq/sdk)
(licencia MIT).

Los SDKs son **complementos oficiales del API REST**: el
[contrato OpenAPI](/referencia/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](/api/) o con un cliente generado desde la spec.

```bash
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

```ts
// 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](/referencia/errores/).

## Ejemplos en el repo

- [`examples/express`](https://github.com/SimploHQ/simplo-node-sdk/tree/main/examples/express)
  — endpoint Express mínimo que emite una factura y devuelve el PDF.
- [`examples/nextjs`](https://github.com/SimploHQ/simplo-node-sdk/tree/main/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 —
  [hola@simplo.cl](mailto:hola@simplo.cl))

## Relacionado

- [Quickstart](/comienza/quickstart/) — tu primera emisión con el SDK
- [Para coding agents](/agentes/para-coding-agents/) — el playbook de
  integración

---

Versión HTML: https://docs.simplo.cl/agentes/sdk/ · Índice para agentes: https://docs.simplo.cl/llms.txt