Ambientes del SII

El SII expone dos ambientes separados para la emisión de DTE, cada uno con su propia numeración de folios. Folyo te permite trabajar con ambos.

Los dos ambientes

Ambiente	Valor tributario	Uso recomendado
`produccion`	Sí, los DTE son legalmente válidos	Operación real
`certificacion`	No, solo para pruebas	Validar tu integración antes de ir a producción

El mismo certificado digital sirve para ambos ambientes.

Cómo sabes en qué ambiente estás

Toda cuenta nueva parte en certificación, y el panel te lo dice de forma permanente hasta que actives producción. Los avisos que vas a ver:

Dónde	Qué muestra
Panel (todas las páginas)	Una franja fija mientras la empresa esté en certificación. Si tu cuenta es del producto Plataforma dice "Estás en el ambiente de certificación del SII"; si es del producto API dice "Ambiente de pruebas (sandbox)". Es el mismo ambiente con el nombre que corresponde a cada uso, y no se puede descartar.
Barra lateral	Un distintivo junto al nombre de tu empresa: "Certificación" o "Sandbox" según tu producto, "Producción" cuando ya emites de verdad.
Folios	La página indica de qué ambiente son los folios que estás solicitando o cargando, porque la numeración no cruza de un ambiente al otro.
Emitir	El formulario de emisión avisa cuando el documento que estás por generar es de certificación y no tendrá validez tributaria.
Configuración	El selector de ambiente explica qué implica cada opción. Pasar a producción no es un interruptor: requiere que tu empresa esté autorizada por el SII como emisor electrónico, con certificado digital y folios de producción.

Además, desde el alta Folyo verifica contra el registro público del SII si tu empresa ya está autorizada como emisor electrónico, y el asistente de configuración te muestra ese estado con el paso siguiente que te corresponde. Si la verificación no se pudo hacer (por ejemplo, si el SII no respondió), el panel lo dice tal cual y te deja volver a comprobar cuando quieras: "no verificado" nunca significa "no autorizado".

Certificación no emite documentos reales

Todo lo que emitas en certificación es una prueba: no tiene validez tributaria, no llega a tus clientes y no afecta tu contabilidad. Si tu intención es facturar, el camino es activar producción; el panel te muestra qué falta.

Cambio de plan y ambiente

El ambiente de cada empresa y el plan de tu cuenta son cosas distintas, pero se tocan en un punto: emitir en producción requiere un plan que la incluya. De ahí salen estas reglas:

Si tu plan baja a uno sin producción (por ejemplo, al cancelar una suscripción), todas las empresas de tu cuenta pasan automáticamente al ambiente de certificación. Te lo avisamos con una notificación en el panel en el momento en que ocurre.
Tus folios de producción no se pierden. Cada rango de folios pertenece al ambiente en que fue autorizado; los de producción quedan en pausa mientras la empresa esté en certificación y vuelven a estar disponibles cuando reactives producción.
Volver a subir de plan no reactiva producción por sí solo. La reactivación es una decisión tuya: se hace en Configuración, en el selector de ambiente, con un plan que incluya producción.
Cambiar de ambiente con folios del ambiente contrario pide confirmación. Folyo te muestra qué rangos quedarían en pausa antes de aplicar el cambio, para que nunca te encuentres la numeración "desaparecida" sin explicación.

Flujo recomendado para integradores

La visión de Folyo es que el ambiente productivo no debería fallar nunca. Para lograrlo, valida tu flujo completo contra certificación antes de mover una sola línea a producción:

Configura la empresa en Folyo con ambiente = certificacion.
Implementa emisión, manejo de webhooks y consultas de estado en tu sistema.
Prueba el flujo completo en certificación hasta tener confianza.
Cambia la empresa a ambiente = produccion en el dashboard cuando esté todo verde.

Puntualmente puedes necesitar probar un request contra el otro ambiente sin cambiar la configuración de la empresa. Para eso existe el header X-SII-Ambiente.

Header `X-SII-Ambiente`

Overridea el ambiente sólo para ese request, sin tocar la configuración de la empresa.

Aspecto	Detalle
Nombre	`X-SII-Ambiente`
Obligatorio	No
Valores	`produccion`, `certificacion` (case-insensitive)
Si está ausente	Se usa el `ambiente` de la empresa
Si es inválido	`HTTP 400` con `code = INVALID_AMBIENTE`

json

{
  "ok": false,
  "error": "Header X-SII-Ambiente inválido. Valores aceptados: produccion, certificacion.",
  "code": "INVALID_AMBIENTE"
}

{
  "ok": false,
  "error": "Header X-SII-Ambiente inválido. Valores aceptados: produccion, certificacion.",
  "code": "INVALID_AMBIENTE"
}

Modo test

Cuando el header difiere del ambiente configurado en la empresa, ese request corre en modo test: la respuesta se marca con modo_test: true y no afecta la operación real de tu empresa. Sirve para validar tu integración de forma efímera.

Los folios no se mezclan entre ambientes

La numeración de folios de certificación y de producción es independiente. Un folio pedido en modo test no queda disponible para emitir en producción: se te devuelve para que valides y no se guarda, de modo que tu operación productiva nunca se contamina.

Ejemplo

Una empresa configurada en ambiente = produccion quiere validar la solicitud de folios contra certificación sin tocar su configuración:

bash

curl -X POST "https://api.folyo.cl/v1/dte/folios/solicitar" \
  -H "X-API-Key: $API_KEY" \
  -H "X-SII-Ambiente: certificacion" \
  -H "Content-Type: application/json" \
  -d '{ "tipo_dte": 33, "cantidad": 10 }'

curl -X POST "https://api.folyo.cl/v1/dte/folios/solicitar" \
  -H "X-API-Key: $API_KEY" \
  -H "X-SII-Ambiente: certificacion" \
  -H "Content-Type: application/json" \
  -d '{ "tipo_dte": 33, "cantidad": 10 }'

La respuesta trae el resultado marcado como modo_test: true y no modifica la operación de la empresa.

Alcance actual

El header X-SII-Ambiente aplica a los siguientes endpoints (desde v1.8.0, excepto solicitar que existe desde v1.5.0):

Endpoint	Modo test
`POST /v1/dte/folios/solicitar`	Sí. El resultado es efímero (`modo_test: true`).
`GET /v1/dte/consulta/:tipo/:folio`	Sí. Consulta el ambiente indicado; respuesta marcada con `modo_test`.
`GET /v1/contribuyente/:rut`	Etiqueta. La respuesta se marca con `modo_test` para trazabilidad.
`GET /v1/rcv/:periodo`	Etiqueta. La respuesta se marca con `modo_test`.
`POST /v1/dte/emitir`	No. Un override distinto al ambiente de la empresa responde `400 AMBIENTE_OVERRIDE_NO_SOPORTADO`.

Por qué la emisión no admite modo test

La emisión consume folios productivos de tu empresa, así que mezclar ambientes corrompería tu numeración. Para validar emisión contra certificación, configura una empresa dedicada en ambiente = certificacion, con su propia numeración de folios.