Ambientes

El SII tiene dos ambientes, y varias operaciones de la API le dejan elegir en cuál trabajar con el parámetro ambiente:

Homologación es lo que el SII llama ambiente de certificación: es el ambiente para probar. Producción es el ambiente real del SII.

No confunda el ambiente de certificación del SII con una certificación de la API. Salvo certificaciones_v1_actualizar_casillas_intercambio, las operaciones de certificaciones no reciben ambiente.

Regla de esta guía: pase siempre ambiente explícito, y use ambiente=0 mientras prueba. Los ejemplos del portal usan ambiente=0.

Las operaciones que eligen ambienteCopiar enlace a esta sección

Estas son las siete operaciones que reciben ambiente. En todas, si se omite, la operación corre en producción. Las operaciones que no figuran en la tabla no reciben el parámetro.

En todas va en el query string (?ambiente=0), salvo en empresas_v1_permisos, donde es el último segmento de la ruta (POST /v1/empresas/{rutEmpresa}/permisos/{rutUsuario}/{ambiente}). Ese segmento también se puede omitir, y entonces la operación corre en producción.

curl -u '<usuario>:<apikey>' -X POST \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  -d '{"Data": "<pfx en base64>", "Contrasenna": "********"}' \
  'https://api.enrolamiento.cl/v1/caf/11111111-1/consulta/33?ambiente=0'

Valores que no son 0 ni 1Copiar enlace a esta sección

La API no valida ambiente contra el enum: un valor distinto de 0 y 1 no da error.

• Un valor que no se reconoce corre en producción. ambiente=abc, o ambiente=homologación con tilde, no da error: la operación corre en producción, igual que si lo hubiera omitido.
• Los nombres se aceptan sin distinguir mayúsculas. ambiente=homologacion u ambiente=HOMOLOGACION, sin tilde, equivalen a ambiente=0. Aun así, use el número.
• Un número distinto de 0 y 1 se trata distinto según la operación. ambiente=7 no da error en ninguna, pero en unas corre en producción y en otras en homologación. Por ejemplo, en caf_v1_descargar corre en producción y en caf_v1_consulta corre en homologación. La columna «Comportamiento» de la tabla lo dice para cada una.
• ambiente= sin valor: qué hace la API no está verificado. No lo mande.

Por todo esto, un error de tipeo en ambiente no se nota: la API no lo rechaza y la operación corre en el ambiente equivocado.

El certificado se valida en producción al descargar o reobtener un CAFCopiar enlace a esta sección

caf_v1_descargar y caf_v1_reobtener validan el certificado digital contra el SII de producción, aunque el CAF se pida con ambiente=0. El ambiente elige dónde se pide el CAF, no dónde se valida el certificado.

En la práctica: si el certificado está habilitado para autenticarse solo en el ambiente de certificación del SII, estas dos operaciones lo rechazan, y el error habla del certificado, no del ambiente. Antes de pedir un CAF de homologación, verifique que el certificado también esté habilitado en producción.

Anulación masiva: siempre en producciónCopiar enlace a esta sección

caf_v1_anulacion_masiva_listar y caf_v1_anulacion_masiva_anular operan siempre en el SII de producción. Su ruta no recibe ambiente y un ?ambiente=0 se ignora. Además, caf_v1_anulacion_masiva_anular es irreversible.

caf_v1_anular también es irreversible, pero respeta ambiente: si lo omite, anula en producción.

Para probar la anulación masiva sin tocar el SII, use el RUT 1-9 o un RUT de prueba de su perfil de cliente: para esos RUT la API no llama al SII.

ResumenCopiar enlace a esta sección

• Pase siempre ambiente, con 0 o 1, nunca un nombre ni otro número.
• Mientras integra, use ambiente=0.
• Si omite ambiente, o el valor no se reconoce, la operación corre en producción.
• caf_v1_descargar y caf_v1_reobtener validan el certificado en producción, aunque pida el CAF de homologación.
• La anulación masiva corre siempre en producción. caf_v1_anulacion_masiva_anular y caf_v1_anular son irreversibles.