Rutas del diagnóstico

Las rutas que describen tu aplicación, con sus campos, sus cupos y lo que responden con cada clave. Para probar en cinco minutos, empieza por Probar tu integración. Lo que significa cada hallazgo está en Hallazgos del diagnóstico.

Las rutas de un vistazo

check-request y la prueba activa están en Comprobar y ensayar sin escribir, y los dos envíos de avisos, en Probar los avisos a tu servidor. Ninguna ruta escribe datos de tu organización ni emite nada: los avisos de prueba son lo único que sale hacia fuera, y llegan de verdad a tu servidor. La pestaña Pruebas del panel enseña el mismo diagnóstico, calculado en el mismo sitio.

Lo que exigen

• La clave de la aplicación en X-Api-Key y ningún permiso de la API: una aplicación sin permisos puede diagnosticarse, que es justo cuando más falta le hace.
• Ningún plan, salvo los dos envíos de avisos, que exigen Integraciones: el trabajo del diagnóstico es explicar los bloqueos, también los de plan.
• Con la organización suspendida o de baja responden todas y lo dicen, menos los dos envíos de avisos, que se rechazan con TENANT_SUSPENDED o TENANT_CANCELLED.
• Con la aplicación desactivada o sin persona responsable activa no responde ninguna: la llamada se corta antes, como cualquier otra, con 403 APP_DISABLED o 403 APP_RESPONSIBLE_INACTIVE, y el docsUrl de ese error explica qué hacer. Por eso los hallazgos app-disabled, responsible-missing y responsible-inactive solo se ven en la pestaña Pruebas y por MCP, con la operación app_diagnosis.
• Con una clave publicada en una web, cuatro rutas no la aceptan: ver Claves publicadas en una web.

Cupos

Todas cuentan en el cupo por hora de la clave. Al pasar el cupo de la prueba activa o el de los avisos de prueba, la respuesta es 429 DIAGNOSTICS_RATE_LIMITED, con Retry-After y las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset de ese cupo (6 o 5 al minuto, con Remaining a 0), no las del freno general por minuto; el cuerpo trae retryAfterSeconds y retryable: true. Estas dos pruebas no se lanzan sin contarlas: si el contador de su cupo no responde, la respuesta es 503 DIAGNOSTICS_UNAVAILABLE, y basta con repetir en unos minutos.

Quién es tu aplicación

{
  "app": { "id": "ckapp1234567890", "name": "Tienda online", "isActive": true },
  "organization": { "name": "Ejemplo SL", "status": "active" },
  "credential": {
    "keyInUse": "current",
    "previousKeyExpiresAt": null,
    "rateLimitPerHour": 1000,
    "rateLimitRemaining": 987
  },
  "scopes": ["crm:invoices:read", "crm:invoices:write", "crm:invoices:issue"],
  "apiVersion": "v1",
  "docsUrl": "https://os.utilia.ai/docs/developers/getting-started/testing"
}

Si responde 200, la clave vale y va en la cabecera buena, y ya cuenta como primera llamada correcta.

• keyInUse: "previous": llamas con la clave anterior durante una renovación; previousKeyExpiresAt dice hasta cuándo vale.
• organization.status: active, suspended o cancelled.
• Con una clave publicada en una web: credential.publishable: true, el estado de la organización solo dice active o inactive, y scopes solo lista los permisos que esa clave puede usar; los demás se cuentan en credential.scopesOutsideCeiling.

El diagnóstico de tu aplicación

Se calcula en el servidor, con la configuración de la aplicación, el plan de la organización y el tráfico de las últimas 24 horas, y se guarda 30 segundos. Es la misma fuente que pinta el panel: lo que ves en la pestaña Pruebas y lo que lee tu programa no se contradicen.

curl https://os.utilia.ai/api/external/v1/diagnostics \
  -H "X-Api-Key: $UTILIA_API_KEY"
 
# Las instrucciones para tu asistente de IA
curl "https://os.utilia.ai/api/external/v1/diagnostics?format=markdown" \
  -H "X-Api-Key: $UTILIA_API_KEY"

sdk.diagnostics está en los SDK a partir de la 4.6.0. Con el cliente asíncrono de Python (async with UtiliaSDK(...) as sdk:), cada llamada lleva await. Una respuesta recortada:

{
  "schemaVersion": 1,
  "generatedAt": "2026-10-21T10:00:00.000Z",
  "verdict": {
    "status": "attention",
    "title": "Falta un paso: la facturación de la aplicación está desactivada",
    "detail": "Pide a un administrador de tu organización que active la facturación de la aplicación. Mientras tanto, prueba con POST /external/v1/invoices/validate, que no emite nada."
  },
  "app": { "id": "ckapp1234567890", "name": "Tienda online", "isActive": true, "purposes": ["billing", "webhooks"] },
  "organization": { "name": "Ejemplo SL", "status": "active" },
  "responsible": { "state": "active" },
  "findings": [
    {
      "code": "BILLING_DISABLED_WITH_INVOICE_SCOPES",
      "severity": "blocking",
      "fixedBy": "organization",
      "title": "La facturación de la aplicación está desactivada",
      "detail": "Tiene permisos de facturas, pero cada factura que intente emitir se rechaza con BILLING_NOT_ENABLED. Pide a un administrador de tu organización que active la facturación de la aplicación. Mientras tanto, prueba con POST /external/v1/invoices/validate, que no emite nada.",
      "docsUrl": "https://os.utilia.ai/docs/developers/getting-started/testing#billing-disabled-with-invoice-scopes",
      "action": { "kind": "enable_billing", "label": "Activar la facturación" }
    }
  ],
  "nextSteps": [
    {
      "code": "BILLING_DISABLED_WITH_INVOICE_SCOPES",
      "fixedBy": "organization",
      "text": "Pide a un administrador de tu organización que active la facturación de la aplicación. Mientras tanto, prueba con POST /external/v1/invoices/validate, que no emite nada.",
      "docsUrl": "https://os.utilia.ai/docs/developers/getting-started/testing#billing-disabled-with-invoice-scopes"
    }
  ]
}

Las instrucciones para tu asistente

Con ?format=markdown, la misma ruta devuelve unas instrucciones sacadas del mismo diagnóstico. Nunca llevan la clave: la nombran como la variable UTILIA_API_KEY.

• Conexión: la dirección base de la API, https://os.utilia.ai/api (la que esperan los SDK y la variable UTILIA_BASE_URL de la orden doctor), la ruta completa de la API pública, la cabecera de la clave, el contrato GET /external/v1/diagnostics/openapi.json como referencia de rutas y campos, y la documentación para asistentes en https://os.utilia.ai/llms.txt.
• Estado ahora: el veredicto.
• Qué puede llamar hoy y qué no y por qué, operación por operación.
• Lo que falta, con quién lo arregla y su docsUrl.
• Primeros pasos: los de journey, hechos o pendientes, con cómo se marca cada uno.
• Reglas para probar sin romper nada.

Cómo se lee el veredicto

verdict.title empieza siempre por una de estas frases, y la pestaña Pruebas enseña la misma palabra arriba del todo. Lo que sigue a los dos puntos es el hallazgo que manda.

Las tres frases de idle siguen una sola regla. Usar la API es llamar a cualquier ruta salvo GET /external/v1/me y las del propio diagnóstico; probar la clave es recibir cualquier respuesta correcta con ella, también de esas dos. Es la misma regla que marca el paso Primera llamada correcta.

En el panel, todo attention que no es «Funciona en parte» se lee Revisar. Los mismos estados son los de la salud de la aplicación.

Por qué no se puede llamar a una operación

En access, cada operación que tu aplicación no puede llamar trae reason: la primera causa, en el orden en que la comprueba la llamada real. Cada motivo corresponde al error que daría esa llamada, así que puedes tratarlo igual que el error, sin esperar a que ocurra.

Lo que el plan no incluye y la aplicación tampoco intenta usar (no tiene su permiso) no se detalla: se cuenta en unavailable, por motivo, con MODULE_NOT_IN_PLAN, CAPABILITY_NOT_ACTIVE o COMING_SOON. Con una clave publicada, las operaciones cuyo permiso no puede usar esa clave también se cuentan ahí, con PUBLISHABLE_KEY_CEILING, aunque hoy pasen desde un servidor.

Llamadas rechazadas

La consulta admite window, con 24h (la de por defecto) o 7d; en los SDK, calls({ window: '7d' }) y calls(window="7d"). Cada grupo usa la plantilla de la ruta, nunca la dirección con sus valores, y no incluye las llamadas al propio diagnóstico ni a /me. Con una clave publicada en una web, responde 403 DIAGNOSTICS_NOT_AVAILABLE_FOR_PUBLISHABLE_KEY: esas llamadas se ven en la pestaña Pruebas.

{
  "window": "24h",
  "rejected": [
    {
      "method": "POST",
      "route": "/external/v1/invoices",
      "statusCode": 403,
      "errorCode": "INSUFFICIENT_SCOPE",
      "count": 12,
      "firstAt": "2026-10-21T08:02:11.000Z",
      "lastAt": "2026-10-21T09:58:40.000Z",
      "lastRequestId": "550e8400-e29b-41d4-a716-446655440000",
      "fixedBy": "organization",
      "title": "A la aplicación le falta un permiso de la API para esta operación.",
      "docsUrl": "https://os.utilia.ai/docs/developers/getting-started/errors-and-retries#insufficient_scope"
    },
    {
      "method": "GET",
      "route": "/external/v1/leads",
      "statusCode": 403,
      "errorCode": "MODULE_NOT_ENABLED",
      "count": 3,
      "firstAt": "2026-10-21T07:40:02.000Z",
      "lastAt": "2026-10-21T07:41:15.000Z",
      "lastRequestId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "fixedBy": "organization",
      "title": "El plan de la organización no incluye el aplicativo que usa esta operación.",
      "docsUrl": "https://os.utilia.ai/docs/developers/getting-started/errors-and-retries#module_not_enabled",
      "resolved": true
    }
  ]
}

Qué queda registrado

También las llamadas que se cortan antes de llegar a la operación:

• Las que rechaza un guard: plan, origen y freno por minuto, y también la propia clave cuando se reconoce de qué aplicación es (desactivada, sin responsable activo o llamando con la clave anterior que ya no vale).
• Las que no llegan a ninguna ruta, si traen una clave válida en X-Api-Key: una dirección que no existe (404, sin código), un método que la ruta no admite (405 METHOD_NOT_ALLOWED) y un origen que rechaza CORS (403 CORS_ORIGIN_NOT_ALLOWED). La comprobación previa que hace el navegador (OPTIONS) no lleva la clave y no deja rastro.
• Estado 499: tu programa cortó la llamada antes de recibir la respuesta, casi siempre porque su tiempo de espera es más corto de lo que tarda la ruta. No sabes si se hizo: si era una escritura, compruébalo antes de repetirla.

Se guardan como mucho 10 rechazos por segundo y aplicación, para que una clave usada en bucle no llene el registro: por encima, el recuento es una muestra.

Un grupo trae resolved: true cuando su causa ya no existe con la configuración de hoy: la facturación ya está activada, el permiso ya está concedido, el plan ya incluye el aplicativo, o la aplicación, su responsable o la organización vuelven a estar activos. Esos grupos van al final, no generan hallazgos y no cuentan en el veredicto: son de antes del arreglo.

El contrato de tu clave

Es el contrato de la API pública recortado a tu clave, con la misma decisión que el diagnóstico: permisos de la API, plan de la organización, «Próximamente» y facturación. Dáselo tal cual a tu asistente de IA o a tu generador de clientes: todo lo que hay dentro se puede llamar con esa clave. En los SDK, openApi() y open_api().

Lo que no puedes llamar no se detalla: x-utilia-unavailable, en la raíz, cuenta cuántas operaciones quedan fuera por cada motivo, sin decir cuáles. Con una clave publicada en una web, PUBLISHABLE_KEY_CEILING cuenta las operaciones cuyo permiso no puede usar esa clave y PUBLISHABLE_KEY, las pruebas que se lanzan desde el panel. Si responde 503, el contrato no está disponible en ese momento; repite más tarde.

Claves publicadas en una web

La clave de una aplicación cuenta como publicada en páginas web si la aplicación tiene dominios autorizados o si la clave vigente se ha usado desde un navegador desde su última renovación. Cualquiera puede copiarla de la página y usarla desde un servidor, sin cabecera Origin, así que para el diagnóstico esa clave es pública. Lo decide la configuración y la historia de la clave, no la petición: una cabecera Origin la pone quien quiere. Qué permisos admite una clave así, y cómo separar la web y el servidor en dos aplicaciones, está en Claves dentro de una página web.

Con esa clave, GET /external/v1/me y GET /external/v1/diagnostics responden con credential.publishable: true, para que un 0 o un null no se lean como «no hay nada», y sin lo que solo interesa a tu organización o diría para qué más sirve la clave:

• organization.status solo dice active o inactive, y los hallazgos TENANT_SUSPENDED y TENANT_CANCELLED conservan su código con un texto neutro, sin hablar de la suscripción.
• Sin recomendaciones de seguridad abiertas (security.openAdvisories a 0, sin CREDENTIAL_ADVISORY_OPEN).
• Sin el resultado de la comprobación del receptor (webhooks.lastReceiverCheck a null, sin WEBHOOK_RECEIVER_ACCEPTS_INVALID_SIGNATURE) ni los hallazgos ORIGINS_UNRESTRICTED y PUBLISHABLE_KEY_SENSITIVE_SCOPES.
• scopes y access solo llevan los permisos y las operaciones que esa clave puede usar. Lo demás se cuenta sin nombrarlo: en credential.scopesOutsideCeiling y, en cada grupo de access, en unavailable con el motivo PUBLISHABLE_KEY_CEILING.

GET /diagnostics/calls, POST /diagnostics/run, webhook-sample y webhook-receiver-check responden 403 DIAGNOSTICS_NOT_AVAILABLE_FOR_PUBLISHABLE_KEY antes de gastar ningún cupo, porque enseñan el tráfico de la aplicación, leen como ella o envían avisos firmados a su servidor. La pestaña Pruebas del panel las lanza sin usar la clave. check-request y el contrato siguen disponibles: no revelan nada de la organización y dicen lo mismo que la llamada real.

Si llegan llamadas con esa clave a rutas que la aplicación no tiene concedidas, el diagnóstico no propone conceder el permiso: pueden no venir de tu web. Lo explica scope-missing-for-observed-calls.

Siguiente paso

• Errores y reintentosQué significa cada errorCode, quién lo arregla y cuándo repetir.
• La pestaña PruebasEl mismo diagnóstico en el panel, con las pruebas sin la clave.