Autenticación

API keys (recomendado)

Simplo autentica con API keys por empresa. Una key se muestra una sola vez al crearla — guárdala en un gestor de secretos (Simplo solo conserva su hash SHA-256 y un prefijo de 8 caracteres para mostrar).

Cada key fija dos cosas además de la empresa:

• El ambiente — el modelo de Stripe: sk_simplo_sandbox_... opera el sandbox de tu empresa (self-serve, incluido en cualquier plan con Facturación); sk_simplo_... (sin _sandbox_) opera producción (se habilita por empresa — ver Pasar a producción). Mismo endpoint, mismo contrato: la key decide el ambiente.
• El scope — qué superficie alcanza:

Scope	Qué permite
billing:dte	Emitir y consultar DTEs vía la API REST de facturación — exactamente las cinco rutas de la tabla del quickstart (POST/GET /billing/dte, detalle, PDF, XML). El resto de /api/v1/billing/* es solo-sesión y responde 403 BILLING_API_KEY_ROUTE_NOT_ALLOWED.
agent:read	Lectura de datos vía el MCP y los tools de agente. Es el scope por defecto de una key nueva. No sirve para emitir.

Una key billing:dte no es de solo lectura — emite documentos tributarios. Y no es intercambiable con agent:read: el MCP responde 401 a una key billing:dte, y la fachada de facturación no acepta agent:read.

La key viaja en el header X-Api-Key. Con el SDK (aún no publicado en npm):

import Simplo from '@simplohq/sdk';

const simplo = new Simplo({ apiKey: process.env.SIMPLO_API_KEY });

Si omites apiKey, el cliente lee la variable de entorno SIMPLO_API_KEY y lanza un error de inmediato (no en la primera request) si no existe ninguna.

La credencial es la empresa. Una API key está ligada a exactamente una empresa: cada llamada queda acotada a ella y ningún parámetro puede ampliar ese alcance. Para operar varias empresas, ver Multi-empresa.

Crear, listar y revocar keys

Puedes gestionar tus keys desde Desarrolladores en tu cuenta de Simplo (solo dueño o administrador de la empresa), o por API autenticándote con tu JWT de sesión. environment elige el ambiente ("sandbox" o "live"; si lo omites, es "live") y scopes la superficie:

curl -sS -X POST https://api.simplo.cl/api/v1/api-keys \
  -H "Authorization: Bearer $SIMPLO_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "Backend de facturación", "environment": "sandbox", "scopes": ["billing:dte"]}'

La respuesta 201 Created incluye el campo key esta única vez — no se puede recuperar después:

{
  "id": "a1b2c3d4-...",
  "name": "Backend de facturación",
  "prefix": "sk_simpl",
  "is_sandbox": true,
  "revoked": false,
  "created_at": "2026-06-13T12:00:00Z",
  "key": "sk_simplo_sandbox_3f9a...e1"
}

Al crear una key sandbox, tu empresa necesita su identidad completa: sin RUT real el mint responde 422 COMPANY_RUT_REQUIRED_FOR_SANDBOX (y sin razón social, 422 COMPANY_RAZON_SOCIAL_REQUIRED_FOR_SANDBOX) — complétala en la app y reintenta.

Para listar o revocar:

curl -sS https://api.simplo.cl/api/v1/api-keys \
  -H "Authorization: Bearer $SIMPLO_JWT"

curl -sS -X DELETE https://api.simplo.cl/api/v1/api-keys/$KEY_ID \
  -H "Authorization: Bearer $SIMPLO_JWT"

El listado nunca devuelve el valor completo de la key, solo su metadata (prefix, scopes, last_used_at, revoked). Revocar es idempotente y tiene efecto inmediato.

Higiene de keys

• Nunca envíes una API key a un navegador o app móvil. Llama a Simplo desde tu backend.
• Nunca la commitees. Usa variables de entorno o un gestor de secretos.
• Rota creando una key nueva, desplegándola y revocando la antigua. La revocación es inmediata.

Bearer tokens (avanzado)

Si ya tienes un JWT emitido por Simplo (por ejemplo dentro de una integración que autentica usuarios contra Simplo), puedes pasarlo en lugar de una API key. Se envía como Authorization: Bearer <token>:

const simplo = new Simplo({ token: sessionJwt });

Prefiere API keys para integraciones server-to-server: no expiran con el calendario de una sesión y son revocables individualmente.

Modos de falla

Status	Clase de error	Significado
401	AuthenticationError	Credencial ausente, malformada, revocada, expirada o desconocida — o una key billing:dte contra el MCP.
403	PermissionError	Credencial válida, pero sin permiso para esta acción. Con una API key en /billing/*, el código BILLING_API_KEY_ROUTE_NOT_ALLOWED significa que la ruta es solo-sesión — no es un problema de tu cuenta.

La API intencionalmente no distingue por qué ocurrió un 401 (anti-enumeración). Revisa el nombre del header (X-Api-Key), el prefijo de la key (sk_simplo_) y que no esté revocada.

Manda siempre un User-Agent propio

Si recibes un 403 cuyo cuerpo NO es JSON y dice error code: 1010, no es tu key: es nuestro CDN bloqueando la petición antes de que llegue a la API, por la firma del cliente HTTP.

Medido el 2026-09-04: el User-Agent por defecto de urllib de Python (Python-urllib/3.x) se bloquea. requests, curl, Go, Node, Java y axios pasan sin problema, igual que el ejemplo Python de esta documentación (usa http.client, que no manda User-Agent).

Identifica tu integración y te ahorras la clase entera de problema:

User-Agent: mi-erp/1.2 (integración Simplo)

Es buena práctica de todas formas: cuando nos escribas por un problema, podemos encontrar tus requests por ese nombre.

Ver Errores para el manejo completo.