Telemetría ligera del widget y del SDK

POST /external/v1/tickets/client-errors recibe, en lotes de hasta 10, los fallos que el widget de soporte y sdk.ai.reportError (report_error) detectan en el navegador: una lista de tickets que no carga, una nota de voz que no se transcribe. Así tu equipo ve en la pestaña Errores que la integración falla sin esperar a que alguien lo cuente.

Este endpoint no captura los errores de tu aplicación, ni siquiera con el widget instalado: el widget solo avisa de los suyos. Para los de tu aplicación, en el navegador o en tu servidor, usa install y capture del SDK (Capturar los errores de tu aplicación), que van al registro de errores completo.

Plan y permisos

Hace falta el aplicativo Integraciones en el plan de tu organización y el permiso analytics:errors:write en la aplicación, el mismo que el registro de errores. El endpoint admite 30 peticiones por minuto por aplicación y no gasta el cupo por hora de la clave.

Enviar fallos

Cabeceras

X-Api-Keystringobligatorio

Clave de la aplicación externa (utl_...).

Content-Typestringobligatorio

application/json

x-request-idstring

Identificador para seguir la petición.

Cuerpo

{ "errors": [...] }, con hasta 10 fallos. Una lista vacía es válida y devuelve received: 0. Cada fallo:

Todos los fallos de esta ruta se registran en el módulo sdk-client; code, component, url y userAgent se guardan en su contexto. Un campo que no está en la lista, como context, se descarta sin error.

Qué pasa con cada fallo del lote

Respuesta

201 cuando UTILIA OS ha procesado el lote entero, en orden:

{ "received": 3, "accepted": 2, "discarded": 1 }

• received: fallos que traía la petición.
• accepted: los registrados.
• discarded: los que no se registraron, sea por un 4xx esperado, por los límites de ritmo y de cupo del registro de errores, por saturación o por un fallo al guardar. Siempre received = accepted + discarded.

La respuesta no dice qué fallo concreto se descartó ni por qué. Si lo necesitas, usa el registro de errores, que responde por cada uno.

Errores

Ejemplos

curl -X POST 'https://os.utilia.ai/api/external/v1/tickets/client-errors' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: utl_tu_clave_de_api' \
  -d '{
    "errors": [
      {
        "message": "No se pudo cargar la lista de tickets",
        "code": "NETWORK_TIMEOUT",
        "severity": "high",
        "endpoint": "/api/external/v1/tickets",
        "method": "GET",
        "component": "TicketList",
        "url": "https://mi-app.com/soporte",
        "release": "1.1.0",
        "environment": "production"
      }
    ]
  }'

Qué gravedad poner

Siguiente paso

• Capturar los errores de tu aplicacióninstall y capture en el navegador, en Node.js y en Python.
• Widget de soporteQué hace el widget y cómo se inserta en tu web.