Para 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

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

• 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

• OpenAPI 3.1 — arranque en frío: el contrato del paso 1.
• OpenAPI 3.1 — /v1: el contrato completo.
• Quickstart: los pasos 1 y 2, con las respuestas completas.
• De sandbox a producción: los pasos 3 y 4, con cada handoff documentado.
• Servidor MCP: qué ve un agente que se conecta por MCP.
• Diccionario de errores: 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: quickstart, producción, autenticación y MCP, sin las ~200 páginas de códigos de error.