Probar tu integración

Con la clave de tu aplicación, UTILIA OS te dice qué puede llamar, qué le falta y quién lo arregla, y si una petición pasaría antes de enviarla. Nada de esto escribe datos ni emite documentos: solo la llamada real del paso 4 tiene efectos.

Antes de empezar

• La clave de tu aplicación externa (utl_...) en la variable de entorno UTILIA_API_KEY. Nunca en el código.
• Ningún permiso de la API: el diagnóstico responde también a una aplicación sin permisos.
• Para los ejemplos del SDK, la 4.6.0 o posterior. Si todavía no se puede instalar (Versiones y compatibilidad), usa curl: las rutas responden igual.

Prueba en cinco pasos

1. Diagnostica tu clave

   Una llamada te dice qué puede y qué no puede hacer tu aplicación, por qué y cuál es el siguiente paso.

   curlSDK JavaScriptSDK Python

   curl https://os.utilia.ai/api/external/v1/diagnostics \
     -H "X-Api-Key: $UTILIA_API_KEY"

   Lee dos campos. verdict es el estado en una línea; nextSteps, los pasos en orden. Por ejemplo, para una aplicación que factura:

   JSON

   {
     "verdict": {
       "status": "attention",
       "title": "Falta un paso: la facturación de la aplicación está desactivada"
     },
     "nextSteps": [
       {
         "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"
       }
     ]
   }

   Los pasos con fixedBy: "developer" son tuyos. Los de organization, pídeselos a un administrador con el texto tal cual. Cada docsUrl lleva a la explicación de su hallazgo.

2. Comprueba la petición

   Antes de la primera llamada de una operación, pásala por check-request con el cuerpo que vas a mandar. Dice si pasaría y por qué no, con el mismo errorCode que daría la llamada real. No ejecuta nada ni guarda el cuerpo (todo lo que comprueba).

   curlSDK JavaScriptSDK Python

   curl -X POST https://os.utilia.ai/api/external/v1/diagnostics/check-request \
     -H "X-Api-Key: $UTILIA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "method": "POST",
       "path": "/external/v1/tickets",
       "body": {
         "user": { "externalId": "user_1234" },
         "title": "No puedo entrar",
         "descripcion": "No me deja iniciar sesión desde ayer."
       }
     }'

   El campo se llama description. La respuesta, recortada, lo dice antes de enviar nada:

   JSON

   {
     "matched": true,
     "wouldPass": false,
     "validation": {
       "ignoredFields": ["descripcion"],
       "missingRequired": ["description"]
     },
     "nextStep": {
       "text": "Arregla primero esto: falta el campo obligatorio `description`.",
       "docsUrl": "https://os.utilia.ai/docs/developers/getting-started/errors-and-retries#validation_error"
     }
   }

   ignoredFields es el fallo más traicionero: la llamada real respondería 201 y descartaría ese campo sin avisar.

3. Ensaya sin escribir

   La prueba activa hace, con cada permiso de lectura, la lectura mínima de su ruta, como tu aplicación. Devuelve pass, fail o skip por permiso, nunca los datos. Admite 6 al minuto.

   curlSDK JavaScriptSDK Python

   curl -X POST https://os.utilia.ai/api/external/v1/diagnostics/run \
     -H "X-Api-Key: $UTILIA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{}'

   Las escrituras no se prueban escribiendo: writeScopesNotProbed dice cómo comprobar cada una sin efectos. Para facturas, el ensayo es POST /external/v1/invoices/validate, con el mismo cuerpo que la emisión (Probar la facturación sin emitir facturas). Para los avisos a tu servidor, Probar los avisos a tu servidor.

4. Llama a la ruta real

   Con el cuerpo corregido, la llamada de verdad.

   curlSDK JavaScriptSDK Python

   curl -X POST https://os.utilia.ai/api/external/v1/tickets \
     -H "X-Api-Key: $UTILIA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "user": { "externalId": "user_1234" },
       "title": "No puedo entrar",
       "description": "No me deja iniciar sesión desde ayer."
     }'

   Si una ruta mueve dinero o emite un documento, manda una clave de idempotencia que salga de tu pedido, nunca una nueva en cada intento. Después de cada escritura, mira la cabecera X-Utilia-Ignored-Fields: si llega, se descartó algún campo.

5. Lee el error

   Si la llamada falla, el error dice qué pasa y quién lo arregla. Un ejemplo, recortado:

   JSON

   {
     "statusCode": 403,
     "errorCode": "INSUFFICIENT_SCOPE",
     "requiredScopes": ["support:tickets:write"],
     "fixedBy": "organization",
     "docsUrl": "https://os.utilia.ai/docs/developers/getting-started/errors-and-retries#insufficient_scope",
     "retryable": false,
     "requestId": "550e8400-e29b-41d4-a716-446655440000"
   }

   SDK JavaScriptSDK Python

   import { UtiliaSDKError } from '@utilia-os/sdk-js';
    
   try {
     await sdk.tickets.create(nuevoTicket);
   } catch (error) {
     if (!(error instanceof UtiliaSDKError)) throw error;
     console.log(error.errorCode, error.fixedBy, error.docsUrl, error.requestId);
   }

   Decide siempre por errorCode. Si fixedBy es organization, no lo rodees desde el código: pídeselo a un administrador. Repite solo con retryable: true, y en un 429 espera lo que diga Retry-After. Al pedir ayuda, cita el requestId, nunca la clave. Cada código está explicado en Errores y reintentos.

En el panel y en la consola

La pestaña Pruebas de cada aplicación, en Gestión de proyectos, Aplicaciones externas, enseña el mismo diagnóstico y lanza las mismas pruebas sin pedirte la clave. Cómo se usa está en Panel de aplicaciones externas. Además, UTILIA OS vigila la salud de la aplicación y avisa cuando deja de funcionar.

Desde la consola, npx @utilia-os/sdk-js doctor (o utilia-doctor en Python) hace el diagnóstico completo y sale con 0, 1 o 2 para tu integración continua. Ver La orden doctor.

Si algo falla

• 401 API_KEY_WRONG_HEADER: la clave va en la cabecera X-Api-Key, no en Authorization.
• 403 APP_DISABLED o 403 APP_RESPONSIBLE_INACTIVE, también en el diagnóstico: la aplicación está desactivada o no tiene persona responsable activa. Lo arregla un administrador en la ficha de la aplicación.
• 403 DIAGNOSTICS_NOT_AVAILABLE_FOR_PUBLISHABLE_KEY: la clave está publicada en una web. La prueba activa, las llamadas rechazadas y los avisos de prueba se lanzan desde la pestaña Pruebas (por qué).
• 429 DIAGNOSTICS_RATE_LIMITED: la prueba activa admite 6 al minuto y los avisos de prueba, 5. Espera lo que diga Retry-After.
• sdk.diagnostics no existe: tu SDK es anterior a la 4.6.0. Llama a las rutas con curl o con tu cliente HTTP.

Cada ruta, con todos sus campos, está en Rutas del diagnóstico.

Siguiente paso

• Integrar con un asistente de IALa instrucción y las reglas para que tu asistente programe sin romper nada.
• Probar la facturaciónValidar facturas, PDF y rectificativas sin emitir nada.