Operaciones

Panorama operativo del proyecto: documentos atascados, entregas de webhooks pendientes, y el mismo resumen en formato Prometheus.

Una lectura por proyecto que responde "¿algo está atascado?" sin escribir SQL.

Petición

curl https://api.timbrecr.com/core/v1/ops/summary \
  -H "Authorization: Bearer timbre_sk_…"

Respuesta

{
  "invoices": {
    "byStatus": { "accepted": 120, "processing": 2 },
    "nonTerminalCount": 2,
    "oldestNonTerminalAgeMs": 45000,
    "stuckCount": 0,
    "stuckOldestAgeMs": null,
    "stuckIds": []
  },
  "webhookDeliveries": {
    "pending": 1,
    "failed": 0,
    "oldestPendingAgeMs": 3000
  },
  "representations": {
    "pending": 0,
    "failed": 0,
    "oldestPendingAgeSeconds": null
  },
  "generatedAt": "2026-09-24T14:02:00.000Z"
}

Qué significa "atascado"

Un documento está atascado cuando lleva más tiempo que el umbral configurado en un estado no terminal. Hacienda tiene un SLA de tres horas para resolver un documento, así que el umbral por defecto, 30 minutos, avisa bastante antes de eso. Ajustalo por consulta con ?stuckThresholdMs=, entre 1000 (un segundo) y 86 400 000 (un día).

Como texto Prometheus

El mismo panorama, en el formato que un scraper puede consumir directamente:

Petición

curl https://api.timbrecr.com/core/v1/ops/metrics \
  -H "Authorization: Bearer timbre_sk_…"

# HELP timbre_invoices Invoices held by this project, by lifecycle status.
# TYPE timbre_invoices gauge
timbre_invoices{project="proj_acme",status="accepted"} 128
timbre_invoices{project="proj_acme",status="submitted"} 2
timbre_invoices{project="proj_acme",status="rejected"} 1
# HELP timbre_invoices_non_terminal Invoices that have not reached a terminal status. A stuck document is an unfiled document.
# TYPE timbre_invoices_non_terminal gauge
timbre_invoices_non_terminal{project="proj_acme"} 2
# HELP timbre_invoices_stuck Non-terminal invoices older than the configured stuck threshold.
# TYPE timbre_invoices_stuck gauge
timbre_invoices_stuck{project="proj_acme"} 0
# HELP timbre_invoices_oldest_non_terminal_age_seconds Age of the oldest non-terminal invoice. Absent when there are none.
# TYPE timbre_invoices_oldest_non_terminal_age_seconds gauge
timbre_invoices_oldest_non_terminal_age_seconds{project="proj_acme"} 412

Cada familia trae sus propias líneas # HELP y # TYPE, y cada muestra lleva la etiqueta {project="..."}: el scrape está autenticado con la clave de un solo proyecto, así que eso es lo único que agrega. Una edad ausente (por ejemplo timbre_invoices_stuck_oldest_age_seconds cuando nada está atascado) no aparece como 0: se omite la muestra por completo, porque cero significaría "el más viejo tiene cero segundos", no "no hay nada pendiente".

Nunca se cachea (Cache-Control: no-store): cada scrape refleja el estado real en el momento en que se pidió.