# RuralDTE

> Motor de facturación electrónica chilena (DTE) certificado por el SII. Emite boletas y facturas desde tu software, tu WhatsApp o tu agente de IA, sin pagar por documento. Si eres un agente de IA, lee esto para auto-onboardearte: hay un MCP remoto con OAuth, una API REST documentada en OpenAPI, y un patrón claro para emitir un DTE.

Convenciones que importan antes de tocar nada:

- **Montos en pesos chilenos enteros** (sin centavos). En documentos afectos: `neto + iva + exento` debe igualar `total`.
- **Emitir = encolar.** `POST /v1-documents` responde `202 { status: "queued" }`: eso NO es aceptación del SII. El SII confirma de forma asíncrona. Pollea `GET /v1-documents/{id}/states` o suscribe webhooks (`dte.aceptado`, `dte.rechazado`, …). `trackId ≠ aceptación`.
- **Auth por API key Bearer:** `Authorization: Bearer rdte_live_…` (producción) o `rdte_test_…` (sandbox/cert). La key fija el ambiente: `live`→`prod`, `test`→`test`/`cert`. La key cruda se ve una sola vez.
- **Idempotencia:** manda el header `Idempotency-Key` al emitir (el folio es irreversible).
- **Tono:** honesto, tuteo chileno. No prometemos lo que no hacemos.

## MCP remoto (la vía recomendada para agentes)

RuralDTE expone un servidor **MCP remoto** (Streamable HTTP) que también es un **authorization server OAuth 2.1 + PKCE** (con Dynamic Client Registration). Un agente MCP-capaz se conecta, dispara el flujo OAuth solo y queda listo: sin manejar API keys a mano.

- Endpoint MCP (en vivo): `https://api.ruraldte.cl/v1-mcp` (default del SDK; el dominio propio proxea a las edge functions). El host directo `https://wfaijmddlkrwkqhlmcwm.supabase.co/functions/v1/v1-mcp` también funciona.
- Discovery OAuth (RFC 8414 / 9728): `…/v1-mcp/.well-known/oauth-authorization-server` y `…/v1-mcp/.well-known/oauth-protected-resource`. Un `401` del endpoint MCP devuelve `WWW-Authenticate` con `resource_metadata` → tu cliente arranca el flujo.
- Flujo: `POST /register` (DCR) → `GET /authorize` (con PKCE) → `POST /token` → Bearer access token → llamadas MCP.
- Tools disponibles: `emit_dte`, `emit_dte_bulk`, `list_documents`, `document_states`, `folio_stock`, `request_folios`, `list_emisores`, `register_webhook`, `reporte_ventas`, `reporte_top_receptores`, `reporte_folios_bajos`. El XML/PDF crudos van por SDK/CLI.
- El MCP es paridad por construcción con REST/SDK/CLI: traduce tools a llamadas v1 con tus mismos guards de cuenta/scope/ambiente.

## API y especificación

- [OpenAPI 3.1 (spec completa)](/openapi.yaml): todos los endpoints REST con request/response, auth, idempotencia y el catálogo de eventos de webhook.
- [Docs navegables](/docs): la referencia renderizada del OpenAPI ("try it" incluido).
- Base URL (en vivo, default SDK): `https://api.ruraldte.cl` (dominio propio; proxea a las edge functions). El host directo `https://wfaijmddlkrwkqhlmcwm.supabase.co/functions/v1` también funciona.

## SDKs y herramientas oficiales (npm)

- TypeScript/Node: `npm i @ruraldte/sdk` → `new RuralDte({ apiKey })`; ESM con tipos completos, fetch nativo (Node >= 18, Deno, Bun, edge).
- CLI: `npx @ruraldte/cli …` (o `npm i -g @ruraldte/cli`) → comando `ruraldte`; auth por env `RURALDTE_API_KEY`, salida JSON pipeable.
- MCP local (stdio): `npx -y @ruraldte/mcp` con env `RURALDTE_API_KEY` — alternativa autoalojada al MCP remoto de arriba (mismas tools).
- Python: `pip install ruraldte` → `RuralDte(api_key=…)`; cero dependencias (stdlib). Cobertura MVP (documents/folios/emisores/webhooks/keys); para pagos/cesiones/conectores usa la API REST o el SDK TS.

## Endpoints clave (REST)

- `POST /v1-documents`: emitir (= encolar) un DTE. Scope `dte:create`. Header `Idempotency-Key`. → `202 { id, folio, status: "queued" }`.
- `POST /v1-documents/batch`: lote ≤ 100 (boleta de alto volumen). No aborta si uno falla.
- `GET /v1-documents/{id}`: metadatos; `?incluir=pdf,xml,states` embebe los artefactos.
- `GET /v1-documents/{id}/states`: línea de tiempo de estados (con `detalle_sii` traducido).
- `GET /v1-documents/{id}/xml` · `GET /v1-documents/{id}/pdf`: EnvioDTE firmado / muestra impresa.
- `POST /v1-documents/{id}/share`: enlace del portal del receptor (descarga sin login por token).
- `GET /v1-folios` · `POST /v1-folios/request` · `GET /v1-folios/gaps`: stock, solicitar CAF al SII (scope `caf:write`), folios a declarar.
- `GET|POST /v1-emisores` + `/{emisorId}/credentials` (carga del .pfx en custodia) + `/{emisorId}/credentials/revoke`.
- `GET|POST /v1-keys` + `/{id}/revoke`: API keys con scopes finos.
- `GET|POST /v1-webhooks` + `/{id}/disable`: webhooks firmados HMAC (scope `webhooks:write`).
- `GET /v1-reportes/ventas` · `/top-receptores` · `/folios-bajos`: reportería.
- `GET|POST /v1-scheduled`: emisión recurrente (semanal/quincenal/mensual).
- `POST /v1-intercambio`: recibir un EnvioDTE entrante y devolver los 3 acuses firmados (Ley 19.983).

## Cómo emitir un DTE (con prompts, vía MCP)

Una vez conectado al MCP, basta con conversar. Ejemplos de prompts:

- "Lista mis emisores" → tool `list_emisores`. Quédate con el `id` del emisor.
- "Revisa cuántos folios tengo para factura (tipo 33)" → tool `folio_stock`. Si no hay, "Solicita 50 folios de tipo 33 para el emisor <id>" → `request_folios` (acción real al SII).
- "Emite una factura (tipo 33) en cert del emisor <id> a ACME SpA, RUT 11111111-1, por 1190 total (1000 neto, 190 IVA)" → tool `emit_dte`. Responde `queued`.
- "Consulta el estado del documento <id>" → tool `document_states`. Espera `dte.aceptado` (DOK) o revisa el rechazo.

El equivalente REST del paso de emisión:

```
POST /v1-documents
Authorization: Bearer rdte_test_…
Idempotency-Key: orden-123
Content-Type: application/json

{
  "emisorId": "<uuid>",
  "tipo": 33,
  "ambiente": "cert",
  "receptor": { "rut": "11111111-1", "razonSocial": "ACME SpA" },
  "montos": { "total": 1190, "neto": 1000, "iva": 190 }
}
```

Tipos de DTE certificados: 39 (boleta), 41 (boleta exenta), 33 (factura), 34 (factura exenta), 43 (liquidación-factura), 46 (factura de compra), 52 (guía de despacho), 56 (nota de débito), 61 (nota de crédito), 110/111/112 (exportación).

## Errores del SII, explicados

Cuando el SII devuelve un código (`sii_code`), la API lo traduce a `detalle_sii` = `{ code, glosa, causa, solucion }` (en tuteo chileno) para que sepas qué pasó y qué hacer: no descifras códigos crudos. Aparece en `GET /v1-documents/{id}` y en `…/states`. Ejemplos: `DOK` (aceptado), `DNK` (aceptado con reparos), `RCH` (rechazado), `RFR` (rechazo por firma: revisa el certificado), `CAF_AGOTADO` (sin folios: solicita un CAF).

## Eventos de webhook (catálogo)

`dte.encolado`, `dte.aceptado`, `dte.con_reparos`, `dte.rechazado`, `dte.manual_pending`, `folios.bajos`, `sii.incidente`, `sii.recuperado`. Cada entrega se firma HMAC-SHA256 y viaja en el header `X-RuralDTE-Signature` (+ timestamp). El `secret` se ve una sola vez al registrar el webhook.

## Producto y precios

Todos los precios son **+IVA, sin contratos, sin tarjeta para probar**. **DTE ilimitados** en todos los planes pagados — nunca se cobra por documento.

| Plan | Precio/mes | RUTs | DTE/mes | Para quién |
|---|---|---|---|---|
| Partida (Free) | $0 | 1 | hasta 100 | micro/dev/agentes probando; API+MCP+CLI reales, PDF con marca "Emitido con RuralDTE" |
| Emprende | $7.900 | 1 | ilimitado | pyme single-RUT; sin marca, WhatsApp delivery, webhooks, bulk Excel/CSV, recepción DTE |
| Negocio | $16.900 | 3 | ilimitado | varias razones sociales; link de pago + conciliación, cobranza |
| Contador | $44.900 | 20 (luego $1.900/RUT) | ilimitado | contadores/agencias; panel multi-cliente, white-label básico, certificación asistida incluida |
| Plataforma | desde $119.000 | a medida (~$300/RUT marginal) | ilimitado | SaaS/ERP que embeben el motor; marca propia, SLA contractual |

Add-ons: **Certificación SII asistida** $39.000 one-time/RUT (incluida en Contador y Plataforma); **Certificado digital** ~$19.900 (1 año) / ~$29.900 (3 años) (vía handoff Clave Única).

**Entrega y avisos por WhatsApp.** El documento cuesta ~$0; lo caro es el WhatsApp saliente en frío. Por eso la entrega al receptor es email-first (WhatsApp al receptor solo si la cuenta lo activa), y los avisos proactivos por WhatsApp (documento emitido, rechazo del SII) tienen un tope mensual por plan. Es fair-use: conversar por WhatsApp —pedir o consultar un documento— es gratis e ilimitado y NO consume el tope.

| Plan | Avisos WhatsApp/mes |
|---|---|
| Partida | Solo email |
| Emprende | 300 |
| Negocio | 1.500 |
| Contador | 5.000 |
| Plataforma | Ilimitados |

- [Precios](/precios) · [Alternativas comparadas](/comparar/alternativas) · [vs. portal SII gratuito](/comparar/portal-sii-gratuito) · [vs. facturadores por documento](/comparar/facturadores-por-documento) · [vs. suites ERP](/comparar/suite-erp)

## Guías

- [Referencia navegable de la API](/docs): endpoints con 'try it'. Los comandos de SDK (TypeScript / Python), CLI y MCP están arriba en este mismo archivo, paso a paso.