---
title: "Consultar el estado de las conexiones"
method: POST
path: "/v1/tools/conexiones.estado.consultar/execute"
tags: ["conexiones"]
---

# Consultar el estado de las conexiones

`POST /v1/tools/conexiones.estado.consultar/execute`

## Request

- Base URL: `https://connect.emisso.ai/api`
- URL: `https://connect.emisso.ai/api/v1/tools/conexiones.estado.consultar/execute`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://connect.emisso.ai/authorize`, token URL `https://connect.emisso.ai/token`, scopes: `conexiones:read`)

Dice en qué va cada conexión: si la credencial quedó vinculada, qué sincronizaciones corrieron y si YA HAY DATOS para consultar ('datosListos'). Úsala después de que la persona complete un enlace, y antes de intentar leer: un listado vacío no significa que no haya nada, puede ser que todavía no sincronizó. La primera sincronización de un sistema con navegador puede tardar cerca de un minuto. El campo 'herramientas' trae los ids que ya puedes invocar; si tu cliente MCP todavía no los muestra en su lista, invócalos con la herramienta 'execute' pasando el id en 'tool'.

## Request body

- object
  - `input` ConexionesEstadoConsultarInput, required
    - `sistema` string: Filtra por código de sistema.
    - `conexionId` string: conn_…, filtra una conexión puntual.

## Response `200`

La tool corrió bien. 'data' es la salida de la tool tal cual, y 'meta' trae el 'request_id' que identifica esta llamada en la bitácora.

- object
  - `data` ConexionesEstadoConsultarOutput, required
    - `conexiones` object[], required: Las conexiones de esta organización que pasan el filtro, con su estado y sus últimas sincronizaciones.
      - `id` string, required: El id de la conexión (conn_…). Es lo que va en la cabecera 'X-Connect-Connection' de cada llamada a este sistema.
      - `sistema` string, required: El código del sistema al que pertenece esta conexión.
      - `nombre` string, required: El nombre con que se creó la conexión, normalmente la empresa a la que pertenece la credencial.
      - `estado` 'active' | 'disabled' | 'pending', required: En qué estado está la conexión. 'active' = utilizable. 'disabled' = pausada: sus tools no responden, y 'pausa' dice por qué. 'pending' = creada pero todavía sin credencial vinculada.
      - `pausa` 'sin_suscripcion' | 'deshabilitada', nullable, required: Por qué está pausada, cuando 'estado' es 'disabled'; 'null' en otro caso. 'sin_suscripcion' = la organización no tiene un plan activo (terminó su prueba): dile a la persona que contrate en https://connect.emisso.ai/billing; al contratar se reactiva sola, sin enlace nuevo. 'deshabilitada' = la pausó una persona: se reanuda con 'conexiones.conexion.habilitar'.
      - `credencial` 'linked' | 'invalid' | 'revoked' | 'ausente', required: En qué estado está la credencial de esta conexión. 'linked' = vinculada y utilizable. 'invalid' = el sistema externo la rechazó, hay que reconectar. 'revoked' = se revocó a propósito. 'ausente' = nunca se entregó. Todo lo que no sea 'linked' se arregla con 'conexiones.enlace.crear' en modo 'reconectar'. OJO: 'linked' NO es un certificado de salud. Dice que alguien entregó la credencial y que se aceptó en su momento, no que hoy siga sirviendo.
      - `verificadaEn` string, nullable, required: Cuándo se probó por última vez la credencial contra el sistema externo (ISO 8601). 'null' si nunca se probó. Una fecha vieja no invalida la credencial por sí sola.
      - `alcances` string[], required: Los módulos de datos habilitados en esta conexión. Pedir uno que no esté en esta lista responde 'alcance_not_enabled'.
      - `cadencia` 'off' | 'daily' | '12h' | '4h' | '6h', nullable, required: CADA CUÁNTO sincroniza sola esta conexión. Es la frecuencia, no si está corriendo. 'null' = todavía no se le sembró una. NO decidas con este campo solo: un 'off' puede ser «nadie la sincroniza por ti» o «la detuvimos nosotros», y cuál de los dos es lo dice 'cadenciaEstado'.
      - `cadenciaEstado` 'activa' | 'pausada_credencial' | 'pausada_otro', required: Si la sincronización automática está corriendo, y cuando no, por qué. 'activa' = nada la detiene; si además 'cadencia' es 'off' o 'null', nadie la sincroniza por ti, así que llama a la tool 'conexion.sincronizar' del sistema cuando quieras datos frescos. 'pausada_credencial' = la credencial dejó de servir y la detuvimos: NO llames a 'conexion.sincronizar', es un login real que va a fallar y en algunos bancos quema la única sesión que permiten; el remedio es 'conexiones.enlace.crear' en modo 'reconectar'. 'pausada_otro' = detenida por otro motivo, sincronizar tampoco corresponde y no hay nada que puedas hacer desde aquí. Este campo manda sobre 'credencial': una conexión auto-pausada sigue leyendo 'linked'.
      - `trabajos` object[], required: Las últimas sincronizaciones programadas de esta conexión, de la más reciente a la más antigua.
        - `id` string, required: El id de esta sincronización programada (sjb_…).
        - `estado` 'queued' | 'running' | 'succeeded' | 'failed' | 'partial', required: En qué va la sincronización. 'queued' y 'running' significan que todavía está trabajando: espera antes de concluir que no hay datos. 'succeeded' terminó bien, 'partial' escribió una parte y 'failed' no escribió nada, con la causa en 'error'.
        - `periodo` string, required: El mes que sincronizó esta corrida, en formato AAAA-MM.
        - `alcances` string[], required: Qué módulos de datos abarcó esta corrida.
        - `registros` integer, nullable, required: Cuántos registros escribió. 'null' significa que todavía no se sabe (la corrida no terminó), y es distinto de un 0, que sí es un resultado: ese período no tenía nada.
        - `error` string, nullable, required: La causa de la falla cuando 'estado' es 'failed'. 'null' en cualquier otro caso.
      - `datosListos` boolean, required: La respuesta a «¿ya puedo leer?» para los meses que Connect mantiene al día: alguna sincronización terminó bien y ninguno de esos meses está en curso. Una carga de meses anteriores no la apaga; el estado de cada mes está en 'historico'. En Previred también exige que no queden períodos o alcances fallidos sin recuperar de esos meses. Revísalo antes de concluir que no hay datos, porque un listado vacío con 'datosListos' en false significa «espera», no «no tienes nada». Un período legítimamente sin registros cuenta como sincronización exitosa: este campo no mira si hay filas.
      - `historico` object, nullable, required: Qué meses están cargados. 'null' en sistemas sin histórico. Un mes que no aparece en 'cargados' no está cargado: no informes su vacío como cero.
        - `piso` string, nullable, required: Desde qué mes (AAAA-MM) se puede cargar en el panel: el inicio de actividades de la empresa o, en el SII, agosto 2017 si la empresa es anterior o no se conoce su inicio. 'null' si no hay piso.
        - `cargados` object[], required: Meses cargados, en tramos seguidos (AAAA-MM), del más nuevo al más viejo.
          - `desde` string, required: Primer mes del tramo (AAAA-MM), el más viejo.
          - `hasta` string, required: Último mes del tramo (AAAA-MM), el más nuevo.
        - `incompletos` string[], required: Meses (AAAA-MM) que se cargaron a medias o no se pudieron traer.
        - `cargarMas` 'disponible' | 'requiere_plan' | 'no_aplica' | 'no_disponible', required: 'requiere_plan' = la prueba solo incluye los 3 meses más recientes; cargar anteriores requiere un plan activo. 'no_aplica' = la empresa no tiene meses anteriores que cargar. 'no_disponible' = Ahora no se puede cargar: la conexión está en pausa, la suscripción tiene un problema o no se pudo leer el plan. Revisa el estado de la conexión y Facturación.
      - `herramientas` string[], required: Los ids de tool que ya puedes invocar sobre esta conexión. Si tu cliente MCP todavía no los muestra, llámalos pasando el id en 'tool': con 'execute' los de lectura y con 'execute_write' los que escriben (la ficha de 'search_docs' dice la puerta de cada uno).
      - `tiposDte` object, nullable, required: Qué tipos de DTE puede emitir esta conexión en el Facturador Gratuito del SII. 'null' si la conexión no emite facturas o todavía no se comprobó; se comprueba al activar la emisión y al volver a comprobarla desde el panel de la conexión.
        - `autorizados` string[], required: Los tipos de documento que el SII le permite emitir a esta conexión. Previsualiza y emite sólo éstos.
        - `noAutorizados` string[], required: Los tipos que el SII rechazó para la persona de esta conexión en esta empresa. Pedir uno responde 'sii_dte_type_not_authorized' sin entrar al SII. Un tipo que no está en ninguna de las dos listas no se pudo comprobar: el SII responde al previsualizarlo.
        - `comprobadoEn` string, required: Cuándo se comprobó en el SII, como instante ISO 8601 en UTC (termina en 'Z').
  - `meta` ResponseMeta
    - `request_id` string, required: Identificador que el servidor le da a esta llamada (req_…). Correlaciona con la fila de la bitácora y es lo primero que pide soporte: guárdalo en tus logs.
    - `operation_request_id` string, uuid: Identidad del intento e-Boleta original. Se conserva al reproducir el resultado del journal; request_id identifica la llamada actual.
    - `tool_id` string, required: La tool que se ejecutó, con su id punteado.
    - `plane` 'action' | 'read', required: 'read' = la llamada escribió en el plano persistido (un sync). 'action' = efímera, no persistió nada de negocio: actuar afuera, o leer lo que un sync ya dejó.
    - `latency_ms` integer, required: Cuánto tardó la ejecución, en milisegundos.
    - `audit_status` 'recorded' | 'degraded', required: 'recorded' = la bitácora recibió la fila de esta llamada. 'degraded' = la acción se hizo pero el registro cayó a un respaldo duradero. Nunca convierte una acción exitosa en un error, porque reintentar por eso sería pagar o emitir dos veces.
    - `idempotency` 'replayed': Presente solo cuando una tool destructiva devolvió la respuesta guardada de un intento previo con la misma Idempotency-Key. Significa que en ESTA llamada no ocurrió ningún efecto nuevo.

## Other responses

- `400`: validation_error (400)
- `401`: unauthorized (401)
- `403`: scope_not_granted | connection_scope_not_enabled | alcance_not_enabled
- `404`: tool_not_found (404)
- `409`: connection_ambiguous | connection_busy
- `428`: connection_credential_required (428)
- `500`: internal_error (500)

---

[API](https://skmtc.dev/emisso/apis/emisso-connect-api.md) · [All operations](https://skmtc.dev/emisso/apis/emisso-connect-api/llms.txt) · [OpenAPI document](https://skmtc.dev/emisso/apis/emisso-connect-api/revisions/e766c01ef2a0?raw)