Panel de estado para clientes de API

Cuando una integración empieza a devolver respuestas raras —consultas lentas, una jurisdicción que falla, un webhook que no llega— la primera pregunta no es técnica sino de atribución: si el problema está en su código, en nuestra API o en el organismo consultado. Sin un lugar donde mirar, esa pregunta se responde abriendo un ticket.

Un panel de estado es ese lugar: una publicación fuera de banda que informa qué componentes funcionan, cuáles están degradados y qué incidentes hay abiertos. No reemplaza el detalle de cobertura que viaja en cada respuesta; responde otra cosa: si lo que alguien ve es un caso aislado o parte de algo ya detectado.

Diseñarlo depende menos del semáforo de la portada que de tres decisiones: qué componentes se publican, con qué criterio cambian y dónde vive el panel.

Separar lo que operamos de lo que consultamos

Una API de infracciones tiene dos clases de dependencia: la superficie propia —autenticación, consulta, entrega de webhooks, reportes— y las fuentes oficiales de cada jurisdicción, cuya disponibilidad no controlamos.

Mezclarlas produce un tablero inútil. Si un portal provincial no responde y el panel anuncia “API degradada”, el cliente supone que el problema es nuestro; si muestra todo en verde porque nuestra infraestructura está sana, no explica por qué sus resultados vienen parciales.

Lo más honesto son dos bloques con identificadores estables —uno por componente propio, otro por fuente—, cada uno con su historial. El estado de una fuente describe lo que observamos al consultarla, no un comunicado del organismo.

Un diccionario de estados con criterio medible

Cuatro estados alcanzan para casi todo: operativo, degradado, interrumpido y mantenimiento programado. Lo que les da valor no es el nombre sino la definición: qué medición, sobre qué ventana y con qué umbral mueve a un componente.

Sin ese criterio, el panel refleja la percepción de quien lo actualiza. Con él, el cambio lo dispara la misma alerta que despierta a la guardia y queda registrado qué señal lo movió.

Conviene aclarar qué no promete un color. “Operativo” significa que las mediciones agregadas están dentro de lo esperado, no que una consulta puntual vaya a completarse. Para eso está el detalle de cobertura de esa respuesta.

El panel no puede vivir donde vive la falla

Un panel alojado en la misma infraestructura que describe se cae con ella, justo cuando hacía falta. Conviene servirlo desde otro proveedor, sin depender de la base de datos, la cola ni la autenticación de la API. Y necesita un modo manual: si el sistema que calcula los estados forma parte de lo caído, alguien tiene que poder publicar una entrada a mano.

También conviene que no exija las mismas credenciales: un cliente cuya autenticación falla tiene que poder leer que la autenticación está fallando. Eso obliga a decidir qué es público: el estado por componente y el texto del incidente, sí; cualquier detalle por cliente, no.

Una versión legible por máquinas

La página sirve para una persona. El monitoreo del cliente necesita un recurso estructurado y estable:

{
  "componentes": [
    { "id": "api-consultas", "estado": "operativo" },
    { "id": "entrega-webhooks", "estado": "degradado" }
  ],
  "fuentes": [
    { "id": "jurisdiccion-ejemplo", "estado": "interrumpido" }
  ],
  "incidentes": [
    { "id": "inc-000123", "tipo": "entrega-demorada", "abierto": true }
  ]
}

Tres coherencias importan más que el formato:

• el identificador del componente es el mismo en el panel, en las trazas y en el soporte;
• durante un mantenimiento anunciado, la API responde con la semántica de servicio no disponible de RFC 9110 y el encabezado que indica cuándo reintentar;
• el tipo de problema que devuelve la API, en el formato estable que propone RFC 9457, coincide con el que nombra el incidente publicado.

Las marcas de tiempo van en el formato de RFC 3339, con desplazamiento explícito: un cronograma sin zona horaria genera discusiones evitables.

Un incidente es un ciclo, no un cartel

Esperar a tener la causa antes de publicar es un error frecuente. La primera entrada puede decir apenas qué se observa y a quién puede afectar. Después importa la cadencia: si se promete una actualización cada media hora, se cumple aunque la novedad sea que no hay novedad. Al cerrar queda el cronograma completo y una nota sobre qué pasó; las entradas no se editan en silencio, se corrigen con fecha.

El texto tiene un límite de privacidad. Un incidente se describe por componente, jurisdicción y ventana temporal, nunca con la patente, el CUIT o la razón social afectada: la Ley 25.326 alcanza al tratamiento de datos personales, y publicarlos es una forma de tratarlos. Vale la misma disciplina que rige a las etiquetas de métricas.

Antes de abrirlo conviene revisar cuatro cosas:

• que cada componente tenga responsable, criterio de cambio y alerta asociada;
• que el panel siga respondiendo con la API apagada, probado de verdad;
• que la página y el recurso para máquinas digan lo mismo a la vez;
• que ningún incidente del historial contenga datos de un cliente.

Un panel de estado no evita las caídas. Evita que cada caída sea una ronda de preguntas sin respuesta y le da al equipo del otro lado lo que suele faltarle durante un incidente: información publicada antes de tener que pedirla.

Preguntas frecuentes

¿Un panel en verde garantiza que mi consulta va a completarse?

No. El color resume mediciones sobre una ventana de tiempo y describe el comportamiento general de un componente. Una consulta puntual puede fallar igual; para ese caso mandan el detalle de cobertura y el error de esa respuesta.

¿Por qué separar el estado de la API del estado de las fuentes oficiales?

Porque habilitan acciones distintas. Si la degradación es nuestra, reintentar tiene sentido cuando el incidente cierre. Si el organismo no responde, la consulta puede quedar parcial aunque nuestra infraestructura esté sana.

¿El panel puede mostrar qué clientes están afectados?

No conviene. El alcance se describe por componente, jurisdicción y ventana temporal. Publicar patentes, CUIT o razones sociales convierte una comunicación operativa en una divulgación de datos personales o comerciales.

¿Alcanza con una página web o hace falta un recurso para máquinas?

La página sirve para leerla durante un incidente; el recurso estructurado sirve para que el monitoreo del cliente reaccione sin intervención. Conviene que ambos salgan de la misma fuente y usen los mismos identificadores de componente.

Notas relacionadas