Está tardando más de lo normal. Tu conexión parece débil.
KelluDesarrolladores
Referencia interactivaOpenAPIManual UTCP

Guías

  • Inicio
  • Inicio rápido
  • Autenticación
  • Permisos
  • Paginación y errores
  • Recursos y operaciones
  • Webhooks
  • WhatsApp por webhook
  • Agentes de IA, OpenAPI y UTCP
  • Conector de IA (Claude y ChatGPT)
  • Guía: usar Kellu desde Claude y ChatGPT
  • Kellu AI connector: user guide (English)

Agentes de IA, OpenAPI y UTCP

La API se describe en dos documentos públicos (no necesitan clave), pensados para que un agente de IA descubra y use las operaciones por sí solo:

DocumentoURL
OpenAPI 3.0https://api.kellu.co/api/v1/openapi.json
Manual UTCPhttps://api.kellu.co/utcp
Referencia interactivahttps://api.kellu.co/api/v1/reference

Cada operación tiene un operationId estable (por ejemplo list_clients o get_sale_note) y una descripción en inglés: qué devuelve, qué filtros acepta y qué permiso requiere. La lista completa está en Recursos y operaciones.

Dale al agente una clave propia, solo con los permisos que necesita (ver Permisos). Sin clients:read, por ejemplo, el agente nunca ve el correo ni el teléfono de tus clientes. Como las claves son de solo lectura, un agente con clave no puede modificar datos.

Si quieres que un asistente como Claude o ChatGPT también cree, edite o envíe (clientes, trabajos, cotizaciones, notas de venta, recordatorios, tickets), usa el conector de IA: se conecta con la cuenta de un usuario, con sus mismos permisos, y sus herramientas de escritura no están en el documento OpenAPI ni en el manual UTCP.

Manual UTCP

UTCP (Universal Tool Calling Protocol) permite que un agente llame a la API directamente, sin un servidor intermedio. El manual de Kellu (/utcp) trae una herramienta por operación: su nombre es el operationId, sus entradas son los parámetros de la operación y sus salidas, la respuesta.

Ejemplo con el cliente TypeScript (@utcp/sdk y @utcp/http):

import { UtcpClient, UtcpClientConfigSerializer } from '@utcp/sdk'
import '@utcp/http' // registra el tipo de llamada "http"

// La clave se lee de la variable <nombre del manual>_API_KEY → kellu_API_KEY.
// export kellu_API_KEY=kellu_sk_TU_CLAVE

const config = new UtcpClientConfigSerializer().validateDict({
  manual_call_templates: [
    { name: 'kellu', call_template_type: 'http', http_method: 'GET', url: 'https://api.kellu.co/utcp' },
  ],
})
const client = await UtcpClient.create(process.cwd(), config)

const tools = await client.getTools()
console.log(tools.map((tool) => tool.name)) // ["kellu.get_api_key_info", "kellu.list_clients", …]

const clients = await client.callTool('kellu.list_clients', { search: 'andes', limit: 5 })

Dos detalles del cliente UTCP:

  • La variable de la clave lleva el nombre del manual como prefijo. El manual pide la variable API_KEY; registrado como kellu, el cliente la busca como kellu_API_KEY, sin probar el nombre sin prefijo. Si lo registras con otro nombre, la variable cambia (erp → erp_API_KEY).
  • Los nombres de las herramientas llevan el mismo prefijo: kellu.list_clients, kellu.get_work_order, etc.

Conversores OpenAPI → herramientas

Si tu framework de agentes convierte documentos OpenAPI en herramientas, apúntalo a https://api.kellu.co/api/v1/openapi.json:

  • Cada operación tiene operationId, summary y description.
  • La autenticación está declarada como esquema bearer: configura el encabezado Authorization: Bearer kellu_sk_….
  • Los esquemas no usan oneOf, anyOf ni allOf, y solo tienen referencias internas, para que los conversores los traduzcan sin pérdida.

Ejemplo con el conversor de @utcp/http:

import { OpenApiConverter } from '@utcp/http'

const specUrl = 'https://api.kellu.co/api/v1/openapi.json'
const spec = (await (await fetch(specUrl)).json()) as Record<string, unknown>
const manual = new OpenApiConverter(spec, { specUrl, callTemplateName: 'kellu' }).convert()
console.log(manual.tools.length) // 19

Errores para el agente

Los errores tienen siempre la forma { "error": { "code", "message", "requestId", "details"? } }. Indícale al agente que decida por code (por ejemplo, ante insufficient_scope debe informar qué permiso falta, que viene en details.requiredScope) y que respete Retry-After ante un 429. Detalle en Paginación y errores.