Horneross - Automatización de Operaciones

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

Ingresá al Dashboard

Andá a app.horneross.com e iniciá sesión

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
JavaScript
Python

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
`agentId`	Identificador único de cada agente
`conversationId`	Agrupa mensajes de una misma conversación
`visitorId`	Identifica a un usuario único (para agrupar conversaciones)
`contact`	Datos del contacto (email, nombre, teléfono)
`datastoreId`	Identificador 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
`401`	API key inválida o expirada	Verificá que la key sea correcta y esté activa
`403`	Sin permisos para este recurso	Verificá que tu plan tenga acceso al endpoint
`404`	Recurso no encontrado	Verificá el `agentId`, `datastoreId`, etc.
`429`	Rate limit excedido	Esperá antes de reintentar o upgradea tu plan
`500`	Error interno del servidor	Reintentá en unos segundos

Próximos pasos

Chat API

Endpoint principal para conversar con agentes

Datastores API

Gestionar bases de conocimiento

MCP Integration

Conectá herramientas externas via MCP

Webhooks

Recibí eventos en tiempo real

Empezar

Guías

Industrias

Developers

Soporte

Legal

Empezar con la API

Capacidades

Chat con Agentes

Gestión de Conocimiento

Conversaciones

Webhooks

Configuración inicial

1. Obtener tu API Key

2. Obtener el Agent ID

3. Tu primera request

4. Respuesta

Conceptos clave

Mantener contexto en conversaciones

Identificar usuarios

Base URL

Autenticación

Rate Limits

Códigos de error comunes

Próximos pasos

Chat API

Datastores API

MCP Integration

Webhooks

​Capacidades

Chat con Agentes

Gestión de Conocimiento

Conversaciones

Webhooks

​Configuración inicial

​1. Obtener tu API Key

​2. Obtener el Agent ID

​3. Tu primera request

​4. Respuesta

​Conceptos clave

​Mantener contexto en conversaciones

​Identificar usuarios

​Base URL

​Autenticación

​Rate Limits

​Códigos de error comunes

​Próximos pasos

Chat API

Datastores API

MCP Integration

Webhooks

Capacidades

Configuración inicial

1. Obtener tu API Key

2. Obtener el Agent ID

3. Tu primera request

4. Respuesta

Conceptos clave

Mantener contexto en conversaciones

Identificar usuarios

Base URL

Autenticación

Rate Limits

Códigos de error comunes

Próximos pasos