Ciclo de vida de una certificación

Una certificación es asíncrona: usted la crea, la inicia y después consulta su avance hasta que termina. El avance depende de los tiempos del SII y no es inmediato. Esta guía explica el recorrido, qué significan Estado, Etapa y PasoEnSII, cada cuánto consultar y qué hacer cuando la certificación termina o queda con error.

El recorridoCopiar enlace a esta sección

1. Crear. certificaciones_v1_crear (POST /v1/certificaciones/{rut}/crear) o certificaciones_v2_crear (POST /v2/certificaciones/{rut}/crear). La v2 funciona como la v1, pero el certificado digital es opcional al crear y se puede cargar después con certificaciones_v2_actualizar. La certificación recién creada queda en Etapa = IngresoDatos (1), con Estado = EnProgreso (1). Si se creó con la v2 sin certificado digital, Estado queda en Creada (0).
2. Iniciar. certificaciones_v1_iniciar (POST /v1/certificaciones/{rut}/iniciar) o certificaciones_v2_iniciar (POST /v2/certificaciones/{rut}/iniciar). Se recomienda usar la misma versión con la que creó la certificación. Después de crear siempre va iniciar: mientras no lo llame, la certificación no avanza, aunque Estado diga EnProgreso. El cuerpo puede traer los productos, servicios y sets que falten. Sin al menos un producto y un servicio, la API rechaza el inicio con PRODUCTO_REQUERIDO o SERVICIO_REQUERIDO. En la v2, si falta el certificado digital, rechaza con CERTIFICADO_DIGITAL_REQUERIDO.
3. Consultar. certificaciones_v1_consultar (GET /v1/certificaciones/{rut}/consultar), cada cierto tiempo, hasta que la certificación termine. La consulta es la misma para las dos versiones: no existe una consulta v2, así que una certificación creada con la v2 también se consulta con la v1.

curl -u '<usuario>:<apikey>' -H 'Accept: application/json' \
  https://api.enrolamiento.cl/v1/certificaciones/11111111-1/consultar

Qué se puede repetir sin riesgoCopiar enlace a esta sección

• certificaciones_v1_crear y certificaciones_v2_crear no son idempotentes. Si la respuesta no llega (un timeout, una conexión cortada), no repita la creación a ciegas. Consulte primero: un 404 de certificaciones_v1_consultar («No existe una certificación…») significa que no se creó.
• certificaciones_v1_iniciar sí se puede repetir: si la certificación ya pasó por la carga de datos, responde true sin hacer nada.
• Para certificaciones_v2_iniciar el contrato marca la idempotencia como desconocida: ante un error dudoso, consulte el estado antes de repetir.

La regla completa, código por código, está en Errores y reintentos.

Estado, Etapa y PasoEnSIICopiar enlace a esta sección

La respuesta de certificaciones_v1_consultar trae tres campos de avance, de lo más general a lo más específico. Los valores son números. El nombre que aparece al lado de cada número es el que usan los filtros de certificaciones_v1_buscar y las claves de certificaciones_v1_stats.

EstadoCopiar enlace a esta sección

Dice si la certificación avanza, terminó o tiene un problema.

EtapaCopiar enlace a esta sección

Dice en qué parte del recorrido está la certificación. Es el campo que dice qué hacer: Estado puede seguir en EnProgreso mientras la certificación espera algo de usted (iniciar o declarar).

PasoEnSIICopiar enlace a esta sección

Dice en qué paso del proceso ante el SII está la certificación. Tiene sentido cuando Etapa es ConfiguracionSII (2).

Otros campos que ayudan a seguir el avanceCopiar enlace a esta sección

• FechaEstado: la fecha del estado actual.
• HorasEnEstado: las horas completas que la certificación lleva sin que cambie nada de lo que se ve en la respuesta. Sirve para detectar una certificación detenida. Un cambio de PasoEnSII no siempre lo vuelve a cero.
• Comentario: el comentario del estado. Cuando Estado es Error, describe el error.
• ClasificacionError y CodigoError: cuando Estado es Error, quién tiene que resolverlo y con qué código (más abajo).
• Reinicios: cuántas veces se reinició la certificación a pedido de alguien, por la API o por el portal de administración.

Qué hacer en cada estadoCopiar enlace a esta sección

certificaciones_v1_declarar_cumplimiento solo corre en DeclaracionFinal: en otra etapa responde ERROR_GENERAL. No es idempotente. Si falla con ERROR_DECLARANDO_CUMPLIMENTO, la certificación queda marcada con ese error: consúltela y lea el mensaje antes de repetir.

Una certificación con errorCopiar enlace a esta sección

ClasificacionError dice quién puede resolver el error:

Qué hacer con un error lo decide usted, según esa clasificación. Si un error de Sistema no se resuelve, escriba a soporte@enrolamiento.cl con el RUT de la empresa. Mientras espera, consulte con el intervalo largo (10 minutos). Cuando la causa de un error está resuelta, la certificación se retoma con reiniciar.

ReiniciarCopiar enlace a esta sección

certificaciones_v1_reiniciar (POST /v1/certificaciones/{rut}/reiniciar) reinicia la certificación y elimina los datos generados para ella. En Etapa = DeclaracionFinal (3) no se puede reiniciar: la API responde ERROR_GENERAL. El campo Paso del cuerpo dice qué se reinicia:

El caso típico de VerificacionSII (2): la certificación quedó en Etapa = VerificacionSII porque el representante legal tenía situaciones pendientes en el SII. Una vez resueltas en el SII, reinicie con Paso = 2 para continuar.

El cuerpo lleva también un Motivo y, de forma opcional, datos para actualizar (razón social, giro, dirección, productos, servicios, sets).

curl -u '<usuario>:<apikey>' -X POST \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  -d '{"Paso": 2, "Motivo": "Situación del representante legal resuelta en el SII"}' \
  https://api.enrolamiento.cl/v1/certificaciones/11111111-1/reiniciar

certificaciones_v1_reiniciar no es idempotente. Ante un error dudoso, no repita: consulte la certificación y compare Reinicios con el valor que tenía antes. Si aumentó, el reinicio se aplicó.

Cada cuánto consultarCopiar enlace a esta sección

La API no fija un intervalo de consulta. Lo que sigue es una recomendación, no un límite de la API:

• Mientras la certificación esté en ConfiguracionSII (2) con Estado = EnProgreso (1), consulte cada 60 segundos.
• Si entre una consulta y la siguiente PasoEnSII no cambia, duplique el intervalo (60 s, 120 s, 240 s…) hasta un máximo de 10 minutos.
• Cuando cambie PasoEnSII, Etapa o Estado, vuelva a 60 segundos.
• En IngresoDatos (1) no consulte: llame a iniciar. En DeclaracionFinal (3), declare el cumplimiento y siga con el intervalo largo. En Completada (2), deje de consultar. En Error (3), decida qué hacer; si espera una resolución, consulte cada 10 minutos.

El avance depende de los tiempos del SII: consultar más seguido no lo acelera, solo consume cupo. La API admite 120 requests por minuto y no está garantizado que ese cupo sea solo suyo (ver Rate limits). Si recibe un 409, espere al menos 60 segundos antes de volver a consultar.

import time
import requests

URL = "https://api.enrolamiento.cl/v1/certificaciones/11111111-1/consultar"
AUTH = ("<usuario>", "<apikey>")
MINIMO, MAXIMO = 60, 600  # segundos

# Antes de este bucle la certificación ya se creó y se inició.
intervalo, anterior = MINIMO, None
declarado = False  # True después de llamar a declarar-cumplimiento
while True:
    r = requests.get(URL, auth=AUTH, headers={"Accept": "application/json"})
    if r.status_code == 409:  # rate limit: esperar al menos 60 s
        time.sleep(60)
        continue
    r.raise_for_status()
    c = r.json()
    if c["Estado"] == 2:  # Completada: terminal
        break
    if c["Estado"] == 3:  # Error: el bucle no lo resuelve; usted decide según
        break             # ClasificacionError (reiniciar, esperar a soporte...)
    if c["Etapa"] == 1:   # IngresoDatos: falta iniciar; consultar no la mueve
        break
    if c["Etapa"] == 3:   # DeclaracionFinal
        if not declarado:
            break         # Falta declarar: llame una sola vez a declarar-cumplimiento
                          # (no es idempotente), marque declarado = True y vuelva al bucle.
        time.sleep(MAXIMO)  # Ya declaró: espere con el intervalo largo.
        continue
    actual = (c["Estado"], c["Etapa"], c["PasoEnSII"])
    intervalo = MINIMO if actual != anterior else min(intervalo * 2, MAXIMO)
    anterior = actual
    time.sleep(intervalo)

Muchas certificaciones: buscar en vez de consultar una por unaCopiar enlace a esta sección

Si sigue muchas certificaciones, consultar cada una por separado multiplica los requests. Con certificaciones_v1_buscar (GET /v1/certificaciones/buscar/{pagina}/{cantidadPorPagina}) trae varias en una sola llamada. La respuesta es un array de certificaciones, de la más reciente a la más antigua, sin total.

curl -u '<usuario>:<apikey>' -H 'Accept: application/json' \
  'https://api.enrolamiento.cl/v1/certificaciones/buscar/1/100?Fecha=20261001'

Lo que conviene saber de los filtros:

• Van por query string y el nombre distingue mayúsculas: estado se ignora, Estado no. Un valor vacío también se ignora.
• Fecha (aaaammdd-aaaammdd) trae las certificaciones con algún cambio de estado en el rango. Sin fecha de fin, el rango llega hasta ahora. El día final queda prácticamente afuera, porque el fin cuenta desde las 00:00 de ese día.
• RUT se compara tal cual, sin normalizar: va sin puntos, con guion y la K en mayúscula.
• Fecha y RUT se aplican antes de paginar.
• Estado, Estapa y PasoEnSII se aplican después de paginar, sobre la página ya cortada. Una página puede traer menos filas que cantidadPorPagina, o ninguna, aunque haya coincidencias en otras páginas.
• El filtro de etapa se llama Estapa, con esa ortografía. Etapa se ignora sin aviso.
• Los filtros de estado, etapa y paso aceptan el nombre o el número del valor, con las mayúsculas exactas. Un valor inválido produce un 500.

Para no perder filas, pida las páginas sin Estado, Estapa ni PasoEnSII y filtre de su lado. La API no impone tope a cantidadPorPagina, pero se recomienda no pasar de 100. Empiece en pagina 1: una página menor que 1 produce un 500. Sin esos tres filtros, una página vacía o con menos filas que cantidadPorPagina es la última. Para repetir la búsqueda sirve el mismo intervalo de la sección anterior.

Al juntar las páginas, deduplique por RUT. La lista va de la más reciente a la más antigua: si se crea una certificación mientras usted pagina, las filas se corren y una misma certificación puede aparecer en dos páginas. Si una empresa puede tener más de una certificación, use RUT junto con Fecha, que es la fecha de creación.