# Para agentes (/docs/agentes)

Facturia es la API de facturación electrónica multiempresa de Chile: emisión de DTE (facturas,
boletas, notas de crédito y débito), recepción de documentos de proveedores, la suite tributaria
(RCV, F29) y webhooks firmados, con un servidor MCP para que un agente la opere directo. Sandbox
gratis para siempre, sin tarjeta ni certificado.

## El camino en cinco pasos [#el-camino-en-cinco-pasos]

**1. Arranque en frío, una sola llamada.** `POST /account/register` con `bootstrap.sandbox_key` y
opcionalmente `bootstrap.empresa` devuelve, en la misma respuesta, la cuenta, una llave
`sk_test_` y `data.next` — la llamada exacta que sigue, con método, URL y headers. Nunca hace falta
confirmar un correo para llegar hasta acá. Contrato completo:
`https://docs.facturia.cl/openapi-bootstrap.yaml`.

**2. Emite en el sandbox.** `POST /v1/documents` con `Authorization: Bearer sk_test_…` y
`Facturia-Empresa: <rut>` crea un documento sin tocar el SII: `folio: null`, aceptado en menos de
un segundo, PDF y XML al toque. La llave de arranque trae los seis scopes que recorren esto entero:
`documents:read`, `documents:write`, `empresas:read`, `empresas:write`, `webhooks:read`,
`webhooks:write`. `keys:write` es aparte (una llave root, solo mintea otras llaves) y los cuatro
scopes de puesta en marcha (`mandato:write`, `mandato:attest`, `onboarding:write`,
`onboarding:attest`) nunca vienen por defecto: se piden explícitamente cuando hacen falta.

**3. Producción es una máquina de estados que se lee con un GET.**
`GET /v1/empresas/{empresa_id}/onboarding` contesta siempre con la lista de pasos que faltan y, si
el que sigue necesita a una persona, un `pending_action`. No hay que adivinar el flujo completo: cada
lectura dice el siguiente paso, uno a la vez.

**4. El patrón de handoff.** Cuando `pending_action` aparece, dice **quién** (`performed_by.role`:
`representante_legal`, `usuario_administrador`, `titular_certificado` o `titular_cuenta` — un rol,
nunca una persona), **dónde** (`action_url`, o `link.mint` con `{method, url, body}` si hay que
acuñar el enlace primero), **qué hacer** (`instructions[]`, en español, textual — no la parafrasees)
y **cómo nos enteramos** (`verification.recheck`: llámalo cuando la persona termine y volvemos a
mirar). Relaya el objeto entero a tu principal; nunca resumas ni inventes un campo que no vino.

**5. Por MCP.** `https://mcp.facturia.cl/mcp` expone las mismas capacidades como herramientas, con
OAuth para la conexión y consentimiento explícito por scope. El descubrimiento vive en
`/.well-known/oauth-protected-resource`.

## Las dos reglas [#las-dos-reglas]

* **Sigue `next` (o `pending_action`/`link.mint`/`recheck`), nunca construyas la URL a mano.** Cada
  respuesta trae la llamada exacta que sigue — método, URL absoluta, headers y a veces el cuerpo — y
  eso es lo único que hay que ejecutar. Adivinar una ruta o inventar un campo es exactamente el error
  que este patrón existe para evitar.
* **Relaya `pending_action` verbatim.** El `title`, las `instructions[]` y el `performed_by.role` son
  la comunicación con una persona real que va a hacer un trámite ante el SII; resumirlos, traducirlos
  de más o saltarte el rol correcto le entrega a la persona equivocada una instrucción distinta de la
  que a nosotros nos consta que es correcta.

## Para seguir [#para-seguir]

* [OpenAPI 3.1 — arranque en frío](https://docs.facturia.cl/openapi-bootstrap.yaml): el contrato del
  paso 1.
* [OpenAPI 3.1 — /v1](https://docs.facturia.cl/openapi.yaml): el contrato completo.
* [Quickstart](https://docs.facturia.cl/docs/empezar/quickstart): los pasos 1 y 2, con las respuestas
  completas.
* [De sandbox a producción](https://docs.facturia.cl/docs/empezar/produccion): los pasos 3 y 4, con
  cada handoff documentado.
* [Servidor MCP](https://docs.facturia.cl/docs/mcp): qué ve un agente que se conecta por MCP.
* [Diccionario de errores](https://docs.facturia.cl/docs/errores/codigos): todos los códigos, su
  causa y si conviene reintentar. La API sirve el mismo diccionario en `GET /v1/error_codes`.
* [Todo lo anterior en un solo archivo](https://docs.facturia.cl/llms-core.txt): quickstart,
  producción, autenticación y MCP, sin las \~200 páginas de códigos de error.