Consultar estado de folios

curl -X POST 'https://developers.enrolamiento.cl/mock/v1/caf/11111111-1/estado-folios/33/1001/1100?ambiente=0' \
  -H 'x-mock-authorization: Basic <base64 de usuario:apikey>' \
  -H 'Content-Type: application/json' \
  -H 'x-amz-content-sha256: <sha256 del body>' \
  --data-raw '{
  "Contrasenna": "********",
  "Data": "MIIC"
}'

Cuenta los folios de un rango según el SII, en el ambiente que indique ambiente: cuántos el SII todavía no recibió ni anuló (Disponibles), cuántos ya no permite anular, en la práctica los de documentos que el SII recibió (Utilizados), y cuántos se anularon (Anulados). Es una lectura: no anula nada, y repetirla no cambia nada en el SII.

El rango tiene que estar contenido entero en un solo CAF de los que lista caf_v1_listar: tome FolioInicial y FolioFinal de uno de esos CAF, o un subrango. Disponibles y Anulados son los que informa el SII; Utilizados no lo informa el SII: se calcula como Cantidad - Disponibles - Anulados. Disponibles no es la cantidad de folios libres para emitir: puede incluir folios que usted ya usó en documentos que aún no envió al SII; para decidir qué folio emitir, use su propio foliado. Si los conteos del SII no cuadran con el rango, la respuesta es un error, nunca un 200 con ceros.

Cuál usar. Para saber el último folio emitido, use caf_v1_consulta; esta operación cuenta un rango. Consulte bajo demanda, un CAF a la vez: cada llamada es una consulta completa al SII, y recorrer todos los CAF de caf_v1_listar consume una llamada por CAF del límite de requests. Para varios CAF, una llamada por CAF y en secuencia. La suma de los subrangos de un CAF no tiene por qué coincidir con una sola consulta del CAF entero si entre una y otra se emitieron o anularon folios.

Permisos. Como caf_v1_listar, verifica en el SII del mismo ambiente que el titular del certificado esté autorizado por la empresa para operar con folios (CAF); no hace falta que administre usuarios. Consulta la opción de anulación masiva del SII: una empresa que no está habilitada ahí recibe CONTRIBUYENTE_SIN_PERMISO. Las boletas (39 y 41) solo se pueden consultar en certificación (ambiente=0).

Tiempos. Hace varias llamadas al SII en serie, más que caf_v1_listar, y puede tardar decenas de segundos: configure un timeout de cliente de al menos 70 segundos. Si tarda más de 60 segundos, la capa de entrada de la API responde 504 con una página HTML, sin código: es una lectura, repítala. SII_ERROR_CXN es frecuente e intermitente en el SII de producción: reintente respetando Retry-After (30 segundos), con espera exponencial (30, 60 y 120 segundos) y un tope de 3 intentos; cada intento puede tardar decenas de segundos.

Sesión del SII entre ambientes (sin verificar). La sesión del SII se reusa 15 minutos por certificado, en los dos ambientes. Si alterna ambiente=0 y ambiente=1 con el mismo certificado en menos de 15 minutos, el SII podría rechazar la sesión. Desde la versión 1.5.3 la respuesta es SII_ERROR_CXN, reintentable (antes, SII_RESPUESTA_INESPERADA): si persiste después de los reintentos, espere 15 minutos y repita antes de contactar a soporte.

Para probar. Con el RUT 1-9 o un RUT de prueba del cliente no se consulta al SII ni se valida el certificado: cualquier rango válido responde 200 con todos sus folios disponibles, sin contrastarlo con el CAF de ejemplo de caf_v1_listar (del folio 1 al 10). PARAMETRO_FUERA_DE_RANGO y NO_SOPORTADO_BOLETAS sí llegan con el RUT de prueba, porque se revisan antes. El RUT de prueba no simula los errores del SII: CAF_NO_ENCONTRADO, SII_ERROR_CXN y los rechazos solo se ven contra el SII; CAF_NO_ENCONTRADO, con una empresa real en certificación.