# La API de la consola La API que usa la consola de desarrolladores: cómo se autentica una clave de API de la cuenta, qué hace a propósito y qué no, y las rutas principales de aplicaciones, fichas, empresas de prueba e instalaciones. Todo lo que ves en la consola lo sirve la misma API. Sus rutas propias empiezan por `https://os.utilia.ai/api/developer/v1` y solo responden a una cuenta de desarrollador: con una cuenta de empresa, `403 DEVELOPER_ACCOUNT_REQUIRED`. Tus aplicaciones se consultan en las rutas de Integraciones, `https://os.utilia.ai/api/integrations/apps`, las mismas que usa una empresa con las suyas. Hay tres formas de llamarla, y cada una sirve para algo: **Quién llama a la API de la consola** ## Tu integración continua (Clave de API de la cuenta) Una clave `utk_` creada en Cuenta › Claves de API. Para scripts y pipelines: consultar, preparar fichas y gestionar empresas de prueba. ## Tu asistente de IA (Servidor MCP con OAuth) Trabaja con tus permisos y lo autorizas tú: lo cuenta Conectar tu asistente de IA a la consola. ## Tú en la consola (Tu sesión) Todo lo que tu rol permite, incluido lo que solo hace una persona. Esta página es la de la clave. Para crearla, mira [Claves de API de la cuenta](https://os.utilia.ai/docs/developers/console/api-keys); para el asistente, [Conectar tu asistente de IA a la consola](https://os.utilia.ai/docs/developers/console/mcp). ## Autenticarse con una clave Envía la clave en la cabecera `Authorization`, con `Bearer` delante, en cada petición y desde un servidor. No vale en la dirección ni en `X-Api-Key`, y UTILIA OS rechaza las peticiones con clave que salen de un navegador. ```http Authorization: Bearer utk_… ``` Antes de nada, comprueba la clave. Estas dos rutas solo responden a una clave y no tocan ningún dato: **`GET /api/v2/organization-api-keys/current`** Quién es la clave: persona responsable, permisos efectivos en developer-apps y developer-sandboxes, caducidad y cupo que le queda esta hora. **`GET /api/v2/organization-api-keys/current/diagnostics`** Si funciona y qué le falta: veredicto, permisos por módulo, llamadas rechazadas en 24 horas y hallazgos con quién los arregla. En una cuenta de desarrollador, organization.kind vale developer. ### curl ```bash curl 'https://os.utilia.ai/api/developer/v1/listings' \ -H "Authorization: Bearer $UTILIA_API_KEY" ``` ### fetch ```javascript // Node.js 18 o posterior, desde tu integración continua. const res = await fetch('https://os.utilia.ai/api/developer/v1/listings', { headers: { Authorization: `Bearer ${process.env.UTILIA_API_KEY}` }, }); const body = await res.json(); if (!res.ok) { throw new Error(`${body.errorCode}: ${body.message}`); } console.log(body); ``` ### python ```python import os import requests res = requests.get( "https://os.utilia.ai/api/developer/v1/listings", headers={"Authorization": f"Bearer {os.environ['UTILIA_API_KEY']}"}, timeout=30, ) res.raise_for_status() print(res.json()) ``` Cada petición cuenta en el cupo por hora de la clave y se comprueba de nuevo: si revocas la clave o cambias el rol de su persona responsable, la petición siguiente ya lo nota. ## Lo que hace a propósito y lo que no Con una clave, la API de la consola hace lo que una integración continua necesita y nada que deje credenciales vivas, comprometa a la cuenta o mueva dinero. - **Sí**: consultar tus aplicaciones y todo lo que cuentan de sí mismas; preparar fichas, sus imágenes y la conversación con la revisión; crear, restablecer y borrar empresas de prueba, leer sus correos y simular suscripciones en ellas. - **No, a propósito**: crear, cambiar o borrar aplicaciones y renovar sus claves, porque fabricaría credenciales que sobreviven a la clave; enviar una ficha a revisión, que acepta las Normas del catálogo; poner precios y planes; instalar para probar y abrir una empresa de prueba, que son de una persona en su sesión; y el equipo, los datos fiscales, la vinculación con tu empresa y la confirmación de operaciones críticas. - **El dinero, solo con la sesión de una persona**: ingresos, extractos, ventas de cada aplicación, cuenta de cobro y dejar de vender no admiten clave ni asistente de IA. ## Aplicaciones Tus aplicaciones son las de Integraciones. Con `developer-apps:read` se consultan; crearlas y cambiarlas lo hace una persona en la consola o tu asistente de IA. **`GET /api/integrations/apps`** Tus aplicaciones, con su estado. **`GET /api/integrations/apps/:id`** Una aplicación: sus permisos, sus avisos, su inicio de sesión y su clave, sin secretos. Parámetro de ruta: `id`. **`GET /api/integrations/apps/:id/metrics`** Peticiones, latencia, errores, rutas más usadas y avisos enviados (también por partes: /metrics/requests, /latency, /errors, /endpoints y /webhooks). Parámetro de ruta: `id`. **`GET /api/integrations/apps/:id/webhook-deliveries`** Los avisos enviados a tu servidor, con su respuesta; /:deliveryId, el detalle de uno. Parámetro de ruta: `id`. **`GET /api/integrations/apps/:id/diagnosis`** La comprobación de la conexión de la aplicación (en la consola, Registros › Llamadas a la API), con /calls y /brief. Su flujo en tiempo real no admite clave. Parámetro de ruta: `id`. **`GET /api/integrations/apps/:appId/errors`** Los errores de la aplicación agrupados, con /stats, /events, /:hash y la exportación /export.csv. Parámetro de ruta: `appId`. ## Fichas La ficha es lo que ven las empresas en el catálogo. Leer va con `developer-apps:read`; preparar, con `developer-apps:write`. **`GET /api/developer/v1/options`** Lo que puede llevar una ficha: permisos, avisos, categorías, modelos de precio, ubicación de los datos y límites de textos e imágenes. **`GET /api/developer/v1/listings`** Las fichas de la cuenta, con su estado y sus instalaciones. **`POST /api/developer/v1/listings`** Crea la ficha y su primer borrador para una de tus aplicaciones. Si ya la tiene, devuelve la que hay. **`GET /api/developer/v1/listings/:id`** La ficha, su borrador, el historial de versiones y decisiones, y sus imágenes. Parámetro de ruta: `id`. **`PATCH /api/developer/v1/listings/:id/draft`** Guarda el borrador; admite guardados parciales. Parámetro de ruta: `id`. **`GET /api/developer/v1/listings/:id/checks`** La lista «Antes de enviar», control a control. Parámetro de ruta: `id`. **`POST /api/developer/v1/listings/:id/media`** Sube el icono o una captura; DELETE /media/:mediaId la quita y GET /media/:mediaId la enseña. Parámetro de ruta: `id`. **`POST /api/developer/v1/listings/:listingId/revisions/:revisionId/messages`** Responde a la revisión o recurre su decisión; el GET de la misma ruta trae el hilo. Parámetros de ruta: `listingId`, `revisionId`. **`GET /api/developer/v1/listings/:id/plans`** Los planes y el precio de la ficha, solo para leer: cambiarlos lo hace una persona o tu asistente de IA. Parámetro de ruta: `id`. También con `developer-apps:write`: `POST /listings/:id/withdraw-submission` cancela un envío, `POST /listings/:id/unpublish` retira la ficha del catálogo y `POST /listings/:id/republish` vuelve a publicar la última versión aprobada. `POST /listings/:id/submit`, el envío a revisión, responde `403 APP_CATALOG_HUMAN_SESSION_REQUIRED` con una clave: lo hace una persona desde la consola, porque acepta las Normas del catálogo. ## La cuenta Con `developer-apps:read` se consulta el resumen de la cuenta y el perfil público; cambiar el perfil pide `developer-apps:write`. **`GET /api/developer/v1/account`** Resumen de la cuenta: perfil, si los datos fiscales están completos, dominio, condiciones, empresas de prueba y vinculación. Con una clave nunca lleva los saldos de Ingresos. **`GET /api/developer/v1/profile`** El perfil público: nombre, web, correo de soporte, dominio y su verificación. PUT lo cambia. Aceptar las Condiciones para desarrolladores y las condiciones de venta lo hace la persona titular desde la consola: con una clave, `403 APP_CATALOG_HUMAN_SESSION_REQUIRED`. ## Empresas de prueba Con `developer-sandboxes:write`. Una empresa recién creada se prepara en segundo plano: pide su ficha hasta que su estado sea `READY`. **`GET /api/developer/v1/sandboxes`** Las empresas de prueba de la cuenta. También responde con developer-apps:read. **`POST /api/developer/v1/sandboxes`** Crea una empresa de prueba con datos de demostración. **`GET /api/developer/v1/sandboxes/:id`** Su ficha: estado, datos de demostración, caducidad e instalaciones de prueba. Parámetro de ruta: `id`. **`PATCH /api/developer/v1/sandboxes/:id`** Le cambia el nombre. Parámetro de ruta: `id`. **`POST /api/developer/v1/sandboxes/:id/reset`** Restablece los datos de demostración. Parámetro de ruta: `id`. **`POST /api/developer/v1/sandboxes/:id/delete`** La borra con todos sus datos. No se puede deshacer: lleva su nombre exacto en confirmName. Parámetro de ruta: `id`. **`GET /api/developer/v1/sandboxes/:id/emails`** Los correos que ha capturado; /:emailId, uno entero. Parámetro de ruta: `id`. `POST /sandboxes/:id/open`, abrir la empresa de prueba, responde `403 SANDBOX_HUMAN_SESSION_REQUIRED` con una clave: entra una persona. ## Instalaciones **`GET /api/developer/v1/listings/:id/installations`** Las empresas que tienen instalada la ficha, con developer-apps:read. Parámetro de ruta: `id`. **`GET /api/developer/v1/sandboxes/:id/installations/:installationId/subscription`** La suscripción de una instalación de prueba. Parámetros de ruta: `id`, `installationId`. **`POST /api/developer/v1/sandboxes/:id/installations/:installationId/subscription/simulate-renewal`** Simula una renovación en una empresa de prueba; también simulate-payment-failure, simulate-trial-end y simulate-refund. Nada se cobra de verdad. Parámetros de ruta: `id`, `installationId`. `POST /listings/:id/test-install`, instalar tu aplicación en una empresa de prueba, responde `403 APP_CATALOG_HUMAN_SESSION_REQUIRED` con una clave: la instalación la hace una persona desde la consola. ## Lo que una clave no puede llamar | Rutas | Con una clave | Por qué | | - | - | - | | `/api/developer/v1/team` | `403 API_KEY_PERMISSION_NOT_GRANTED` o `API_KEY_ROUTE_NOT_AVAILABLE` | El equipo lo gestionan las personas. | | `/api/developer/v1/account/fiscal-data` | `403 API_KEY_PERMISSION_NOT_GRANTED` | Los datos fiscales los decide una persona. | | `/api/developer/v1/account/security`, `/account/close` | `403` | La seguridad es de cada persona, y cerrar la cuenta, de la persona titular. | | `/api/developer/v1/earnings`, `/payouts`, `/listings/:id/sales`, `/listings/:id/subscriptions` | `403 API_KEY_ROUTE_NOT_AVAILABLE` | El dinero, solo con una persona presente. | | `/api/developer/v1/links` | `403 API_KEY_ROUTE_NOT_AVAILABLE` | La vinculación con tu empresa la empieza y la aprueba una persona. | | `/api/developer/v1/approvals` | `403 API_KEY_ROUTE_NOT_AVAILABLE` | Confirmar una operación crítica es de una persona. | | Escrituras en `/api/integrations/apps` | `403 API_KEY_ROUTE_NOT_AVAILABLE` | Crear o cambiar una aplicación fabrica credenciales que sobreviven a la clave. | ## Errores Una ruta de la consola responde como el resto de la API: `errorCode` y `message` en el cuerpo. Los que más verás con una clave: - **`API_KEY_PERMISSION_NOT_GRANTED`**: la clave no tiene marcado ese acceso. Lo que falta va en `permissions`. - **`API_KEY_RESPONSIBLE_PERMISSION_MISSING`**: lo tiene marcado, pero el rol de su persona responsable no lo permite. - **`API_KEY_ROUTE_NOT_AVAILABLE`**: esa ruta no admite claves. - **`APP_CATALOG_HUMAN_SESSION_REQUIRED`**, **`SANDBOX_HUMAN_SESSION_REQUIRED`**: lo hace una persona desde la consola. - **`DEVELOPER_ACCOUNT_REQUIRED`**: la clave es de una empresa, no de una cuenta de desarrollador. La tabla completa de errores de una petición con clave está en [Hacer peticiones con una clave](https://os.utilia.ai/docs/developers/organization-api-keys/first-request#errores-de-una-petición), y qué significa cada hallazgo de la comprobación, en [Comprobar una clave](https://os.utilia.ai/docs/developers/organization-api-keys/diagnostics).