La API de Horneross te permite integrar agentes de IA en cualquier aplicación, automatizar flujos de trabajo y gestionar conversaciones de manera programática.
Capacidades
Chat con Agentes Envía mensajes y recibí respuestas de tus agentes desde cualquier sistema
Gestión de Conocimiento Agregá, actualizá y consultá documentos en tus datastores
Conversaciones Accedé al historial completo y gestioná el estado de conversaciones
Webhooks Recibí eventos en tiempo real cuando algo importante sucede
Configuración inicial 1. Obtener tu API Key
Accedé a Settings
Navegá a Settings → API Keys en el menú lateral
Creá una nueva key
Click en “Nueva API Key” y asignale un nombre descriptivo
Guardá la key
Copiá y guardá la key en un lugar seguro. Solo se muestra una vez.
Seguridad : Nunca expongas tu API key en código del lado del cliente (frontend).
Usala únicamente en tu backend.
2. Obtener el Agent ID El agentId lo encontrás de dos formas:
En la URL : app.horneross.com/agents/[AGENT_ID]/...En el Dashboard : Andá a tu agente → Configuración → General → Agent ID
3. Tu primera request curl -X POST https://app.horneross.com/api/v2/agent/TU_AGENT_ID/chat \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "Hola, necesito ayuda con mi pedido", "conversationId": "conv_nuevo" }'
const response = await fetch ( 'https://app.horneross.com/api/v2/agent/TU_AGENT_ID/chat' , { method: 'POST' , headers: { 'Authorization' : 'Bearer TU_API_KEY' , 'Content-Type' : 'application/json' , }, body: JSON . stringify ({ query: 'Hola, necesito ayuda con mi pedido' , conversationId: 'conv_nuevo' }), } ); const data = await response . json (); console . log ( data . answer );
import requests response = requests.post( 'https://app.horneross.com/api/v2/agent/TU_AGENT_ID/chat' , headers = { 'Authorization' : 'Bearer TU_API_KEY' , 'Content-Type' : 'application/json' , }, json = { 'query' : 'Hola, necesito ayuda con mi pedido' , 'conversationId' : 'conv_nuevo' } ) data = response.json() print (data[ 'answer' ])
4. Respuesta { "answer" : "¡Hola! Con gusto te ayudo con tu pedido. ¿Podrías darme el número de orden?" , "conversationId" : "conv_nuevo" , "messageId" : "msg_abc123xyz" , "sources" : [ { "source" : "Políticas de envío" , "score" : 0.92 } ], "usage" : { "promptTokens" : 150 , "completionTokens" : 45 } }
Conceptos clave Concepto Descripción agentIdIdentificador único de cada agente conversationIdAgrupa mensajes de una misma conversación visitorIdIdentifica a un usuario único (para agrupar conversaciones) contactDatos del contacto (email, nombre, teléfono) datastoreIdIdentificador de una base de conocimiento
Mantener contexto en conversaciones Para que el agente recuerde mensajes anteriores, usá el mismo conversationId:
// Primera pregunta const primera = await chat ({ query: "¿Cuáles son los horarios de atención?" , conversationId: "conv_usuario_123" }); // El agente responde con los horarios // Segunda pregunta (el agente recuerda el contexto) const segunda = await chat ({ query: "¿Y los sábados?" , conversationId: "conv_usuario_123" }); // El agente sabe que estás preguntando por horarios del sábado
Identificar usuarios Usá visitorId para agrupar todas las conversaciones de un mismo usuario:
const response = await chat ({ query: "Quiero información sobre precios" , visitorId: "usuario_456" , contact: { email: "cliente@ejemplo.com" , firstName: "María" , lastName: "García" , phoneNumber: "+5491123456789" } });
Esto crea o actualiza el contacto en tu CRM interno de Horneross.
Base URL Todas las requests van a:
https://app.horneross.com/api
Autenticación Incluí tu API key en el header Authorization:
Authorization: Bearer TU_API_KEY
Rate Limits Plan Requests/min Requests/día Free 10 1,000 Starter 60 10,000 Pro 300 100,000 Enterprise Custom Custom
Si necesitás más capacidad, contactanos para un plan Enterprise.
Códigos de error comunes Código Problema Solución 401API key inválida o expirada Verificá que la key sea correcta y esté activa 403Sin permisos para este recurso Verificá que tu plan tenga acceso al endpoint 404Recurso no encontrado Verificá el agentId, datastoreId, etc. 429Rate limit excedido Esperá antes de reintentar o upgradea tu plan 500Error interno del servidor Reintentá en unos segundos
Próximos pasos 