Consultar el estado de las conexiones

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "sistema": {
      "description": "Filtra por código de sistema.",
      "type": "string"
    },
    "conexionId": {
      "description": "conn_…, filtra una conexión puntual.",
      "type": "string"
    }
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "conexiones": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "El id de la conexión (conn_…). Es lo que va en la cabecera 'X-Connect-Connection' de cada llamada a este sistema."
          },
          "sistema": {
            "type": "string",
            "description": "El código del sistema al que pertenece esta conexión."
          },
          "nombre": {
            "type": "string",
            "description": "El nombre con que se creó la conexión, normalmente la empresa a la que pertenece la credencial."
          },
          "estado": {
            "type": "string",
            "enum": [
              "active",
              "disabled",
              "pending"
            ],
            "description": "En qué estado está la conexión. 'active' = utilizable. 'disabled' = pausada, sus tools responden 'connection_disabled'. 'pending' = creada pero todavía sin credencial vinculada."
          },
          "credencial": {
            "type": "string",
            "enum": [
              "linked",
              "invalid",
              "revoked",
              "ausente"
            ],
            "description": "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": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "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": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Los módulos de datos habilitados en esta conexión. Pedir uno que no esté en esta lista responde 'alcance_not_enabled'."
          },
          "cadencia": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "off",
                  "daily",
                  "12h",
                  "4h",
                  "6h"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "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": {
            "type": "string",
            "enum": [
              "activa",
              "pausada_credencial",
              "pausada_otro"
            ],
            "description": "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": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "El id de esta sincronización programada (sjb_…)."
                },
                "estado": {
                  "type": "string",
                  "enum": [
                    "queued",
                    "running",
                    "succeeded",
                    "failed",
                    "partial"
                  ],
                  "description": "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": {
                  "type": "string",
                  "description": "El mes que sincronizó esta corrida, en formato AAAA-MM."
                },
                "alcances": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "Qué módulos de datos abarcó esta corrida."
                },
                "registros": {
                  "anyOf": [
                    {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "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": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "La causa de la falla cuando 'estado' es 'failed'. 'null' en cualquier otro caso."
                }
              },
              "required": [
                "id",
                "estado",
                "periodo",
                "alcances",
                "registros",
                "error"
              ],
              "additionalProperties": false
            },
            "description": "Las últimas sincronizaciones programadas de esta conexión, de la más reciente a la más antigua."
          },
          "datosListos": {
            "type": "boolean",
            "description": "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": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "piso": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "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": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "desde": {
                          "type": "string",
                          "description": "Primer mes del tramo (AAAA-MM), el más viejo."
                        },
                        "hasta": {
                          "type": "string",
                          "description": "Último mes del tramo (AAAA-MM), el más nuevo."
                        }
                      },
                      "required": [
                        "desde",
                        "hasta"
                      ],
                      "additionalProperties": false
                    },
                    "description": "Meses cargados, en tramos seguidos (AAAA-MM), del más nuevo al más viejo."
                  },
                  "incompletos": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Meses (AAAA-MM) que se cargaron a medias o no se pudieron traer."
                  },
                  "cargarMas": {
                    "type": "string",
                    "enum": [
                      "disponible",
                      "requiere_plan",
                      "no_aplica",
                      "no_disponible"
                    ],
                    "description": "'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."
                  }
                },
                "required": [
                  "piso",
                  "cargados",
                  "incompletos",
                  "cargarMas"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "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."
          },
          "herramientas": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "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": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "autorizados": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "33",
                        "34",
                        "52",
                        "56",
                        "61"
                      ],
                      "description": "Tipo de DTE: 33 factura, 34 factura exenta, 52 guía de despacho, 56 nota de débito, 61 nota de crédito."
                    },
                    "description": "Los tipos de documento que el SII le permite emitir a esta conexión. Previsualiza y emite sólo éstos."
                  },
                  "noAutorizados": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "33",
                        "34",
                        "52",
                        "56",
                        "61"
                      ],
                      "description": "Tipo de DTE: 33 factura, 34 factura exenta, 52 guía de despacho, 56 nota de débito, 61 nota de crédito."
                    },
                    "description": "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": {
                    "type": "string",
                    "description": "Cuándo se comprobó en el SII, como instante ISO 8601 en UTC (termina en 'Z')."
                  }
                },
                "required": [
                  "autorizados",
                  "noAutorizados",
                  "comprobadoEn"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "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."
          }
        },
        "required": [
          "id",
          "sistema",
          "nombre",
          "estado",
          "credencial",
          "verificadaEn",
          "alcances",
          "cadencia",
          "cadenciaEstado",
          "trabajos",
          "datosListos",
          "historico",
          "herramientas",
          "tiposDte"
        ],
        "additionalProperties": false
      },
      "description": "Las conexiones de esta organización que pasan el filtro, con su estado y sus últimas sincronizaciones."
    }
  },
  "required": [
    "conexiones"
  ],
  "additionalProperties": false
}