# 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.

> **Aún no publicado:**
> El SDK oficial TypeScript (`@simplohq/sdk`) está en preparación: el paquete
> todavía no está publicado en npm y el repositorio
> ([`github.com/SimploHQ/simplo-node-sdk`](https://github.com/SimploHQ/simplo-node-sdk))
> todavía no es público. **No ejecutes `npm install @simplohq/sdk` todavía** —
> el paquete no existe en el registro.
>
> **Hoy integra directo contra la API REST**: el
> [contrato OpenAPI](/referencia/contrato-openapi/) es la fuente de verdad y
> funciona ahora mismo con curl o el cliente HTTP de cualquier lenguaje — ver el
> [Quickstart](/comienza/quickstart/) y la
> [referencia por endpoint](/api/). Cuando el SDK se publique, será un
> complemento sobre ese mismo contrato, no un requisito.

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](/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.

## 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)

```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 (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](/comienza/quickstart/#2-emite-una-factura).

## 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](/comienza/quickstart/))

## Integra hoy, sin esperar el SDK

- [Quickstart](/comienza/quickstart/) — tu primera emisión vía curl (o el
  cliente HTTP de tu lenguaje) contra la API REST
- [Para coding agents](/agentes/para-coding-agents/) — el playbook de
  integración, REST primero
- [Contrato OpenAPI](/referencia/contrato-openapi/) — genera un cliente en tu
  lenguaje desde la spec

---

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