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.

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-Empresa-Id: $EMPRESA_ID" \
  -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-Empresa-Id: $EMPRESA_ID" \
  -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.