Ambientes y claves

En foliios el ambiente lo decide la clave con la que llamas. No hay un parámetro de ambiente: la misma URL, https://api.foliios.com, atiende los tres.

Clave	Ambiente	A dónde va el documento	Efecto fiscal
sk_sandbox_...	sandbox	La DIAN simulada de foliios. Nunca llama a la DIAN ni envía correos reales	Ninguno
sk_test_...	test (habilitación)	El servicio de habilitación de la DIAN, con el certificado de tu empresa	Ninguno
sk_live_...	live (producción)	Producción de la DIAN	Real

Toda respuesta de una clave autenticada trae la cabecera Foliios-Environment (sandbox, test o live), y cada documento guarda su ambiente al crearse y nunca lo cambia.

Cuándo usar cada uno

• Sandbox. Para integrar. Valida con las mismas reglas del anexo técnico que se pueden comprobar sin las bases de la DIAN, permite provocar rechazos, contingencia y fallos de entrega con escenarios, y no tiene riesgo. Tiene límites propios y sus datos duran 30 días.
• Habilitación (test). Es el ensayo real ante la DIAN: tu software y tu certificado contra su servicio de pruebas. Una empresa no emite documentos nuevos con una clave sk_test_ hasta aprobar el set de habilitación; antes recibe 409 habilitation_required. Ver la guía de habilitación.
• Producción (live). Documentos con validez fiscal. Ver paso a producción.

Cómo se consigue una clave

Las claves se crean en el portal. Se muestran completas una sola vez; foliios no guarda la clave, solo una huella con la que la reconoce, así que no hay forma de recuperarla: si la pierdes, crea otra y revoca la anterior.

• La clave de sandbox permanente se crea al entrar por primera vez al ambiente Sandbox.
• Clave temporal de sandbox. POST /v1/sandbox/keys con una clave de sandbox permanente crea otra que muere sola pasado un día, para la misma cuenta y empresas. Sirve para CI o para dársela a un agente. Cada cuenta tiene un tope de claves temporales vivas (ver los límites en escenarios).

curl -s -X POST https://api.foliios.com/v1/sandbox/keys \
  -H "Authorization: Bearer $FOLIIOS_API_KEY"

Formato y errores

Una clave es el prefijo de su ambiente seguido de 43 caracteres. Una clave mal formada, desconocida, revocada, vencida o con el prefijo de otro ambiente responde siempre lo mismo, 401 invalid_api_key; sin cabecera, 401 missing_api_key. No se distingue cuál fue la causa.

Permisos

Una clave tiene permisos sobre los documentos: documents:read (consultar, listar, descargar) y documents:write (emitir, reenviar, reintentar). Sin el permiso, 403 insufficient_permissions.

Las conexiones de agente (claves con un perfil, para el servidor MCP) solo funcionan en el MCP, donde se aplica su perfil. En la API REST responden 403 agent_key_mcp_only.

Cuida la clave

• Guárdala en una variable de entorno o en un gestor de secretos, nunca en el código ni en el control de versiones.
• No la pegues en un chat, un correo ni un ticket; tampoco se la des a un agente por el chat.
• Usa una clave por sistema, para revocar una sin afectar las otras.
• Si se expone, revócala en el portal y crea otra.

Un error frecuente

Una empresa que todavía no terminó de configurarse en un ambiente responde 409 environment_not_configured a una clave de ese ambiente (por ejemplo, una sk_live_ antes de completar el alta de producción). No se numera ni se guarda nada, y tu Idempotency-Key queda libre.