EmmiaEmmia developers

Documentación

Guía de integración

Publica una herramienta y los agentes de IA de Emmia podrán llamar a tu API durante una conversación para responder con tus datos o ejecutar acciones en tu sistema.

Introducción

Una herramienta es un endpoint HTTPS tuyo que Emmia invoca cuando el agente lo necesita. Tú la describes (qué hace y qué parámetros recibe); el modelo decide cuándo llamarla. No necesitas un SDK: todo se gestiona con llamadas HTTP autenticadas por OAuth2, o desde este portal.

Inicio rápido

Autenticación (OAuth2)

La gestión de herramientas usa el flujo client_credentials. Intercambia tus credenciales por un access_token (válido 1 hora) y úsalo como Bearer en cada llamada.

cURL
curl -X POST https://api.emmia.io/api/dev/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=emmia_app_xxxx" \
  -d "client_secret=yyyy" \
  -d "scope=tools:read tools:write tools:publish"
JSON
{
  "access_token": "eat_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "tools:read tools:write tools:publish"
}

Scopes disponibles: tools:read, tools:write, tools:publish.

Crear una herramienta

La descripción corta es lo que el modelo lee para decidir cuándo usarla: sé claro y específico. El endpoint debe ser HTTPS.

HTTP
POST /api/dev/tools
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "name": "buscar_producto",
  "description": "Busca productos en el catálogo de ACME por nombre o categoría.",
  "endpoint": "https://api.acme.com/emmia/buscar",
  "method": "POST",
  "authType": "none",
  "category": "ecommerce",
  "parameters": [
    { "name": "query", "type": "string", "required": true,
      "description": "Término de búsqueda" }
  ]
}

Parámetros

Cada parámetro tiene name, type (string, number,boolean o array), description y required. El modelo completa estos valores a partir de la conversación y los envía a tu endpoint.

Recibir llamadas

Emmia hace una petición a tu endpoint con los parámetros del modelo más un objeto _emmia_contextcon el agente y la organización que originaron la llamada. Responde en JSON; el contenido se entrega al modelo.

JavaScript
// Express.js — tu servidor
app.post('/emmia/buscar', (req, res) => {
  const { query, _emmia_context } = req.body;
  // _emmia_context = { agentId, orgId, timestamp }
  const results = miBase.buscar(query);
  res.json({ results }); // se entrega tal cual al modelo
});

Autenticar tu endpoint

Si tu API requiere credenciales, cada negocio las ingresa al instalar la herramienta. Emmia las guarda cifradas y las envía en cada llamada según el tipo que elijas:

Verificación de la firma HMAC en tu servidor:

JavaScript
const crypto = require('crypto');

const ts  = req.header('X-Emmia-Timestamp');
const sig = req.header('X-Emmia-Signature'); // "sha256=..."
const expected = 'sha256=' + crypto
  .createHmac('sha256', MI_CLAVE)
  .update(`${ts}.${JSON.stringify(req.body)}`)
  .digest('hex');

const ok = sig.length === expected.length &&
  crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
if (!ok) return res.status(401).end();

Publicar

Mientras está en draft, solo tú la ves. Al publicarla pasa a published y aparece en el catálogo para que cualquier negocio la habilite. Publica desde el panel o con POST /api/dev/tools/{toolId}/publish (requiere el scope tools:publish).

Referencia de la API

POST/api/dev/oauth/tokenObtener access_token · client_id/secret
POST/api/dev/toolsCrear herramienta · tools:write
GET/api/dev/toolsListar tus herramientas · tools:read
GET/api/dev/tools/{id}Obtener una herramienta · tools:read
PUT/api/dev/tools/{id}Actualizar · tools:write
POST/api/dev/tools/{id}/publishPublicar · tools:publish
DELETE/api/dev/tools/{id}Eliminar · tools:write

Límites y buenas prácticas

Crear cuenta y empezar →