Glosario

El glosario está dividido en bloques: consumo y facturación, agentes y orquestación, modelos, seguridad y control, integración (API, webhooks, conectores) y operación (multi-tenant, auditoría, licencias). Los términos marcados con un enlace tienen una guía dedicada; el resto se define aquí de forma autocontenida.

Consumo y facturación

SHARA factura por consumo abstracto: nunca pagas «tokens de un proveedor», sino una unidad propia y estable. Esto desacopla tu factura del modelo concreto que se use por debajo y de los cambios de precio del mercado.

Regla mental: cuota es lo que ya pagaste, excedente es lo que pagas de más si te pasas, y rollover es lo que rescatas de un mes flojo. El kill-switch es el freno que evita sorpresas.

Agentes y orquestación

SHARA no es un único chatbot: es un equipo de agentes especializados coordinados por un orquestador. El cliente habla con uno solo; el resto trabaja en segundo plano. Ver Agentes y Arquitectura.

Modelos (alias) y sin lock-in

SHARA nunca expone el proveedor real de un modelo. Trabaja con alias estables que abstraen la potencia y el coste, de modo que podemos cambiar de proveedor por debajo sin que tu integración ni tu factura se enteren. Ver Sin lock-in.

Seguridad y control de gasto

El control no es opcional: SHARA está diseñado para que nunca se ejecute algo importante sin supervisión ni se dispare el gasto sin un freno. Ver Seguridad.

Integración: API pública

La API pública es la superficie que usa un desarrollador externo para integrar SHARA con sus sistemas. Se autentica con API key y aplica límites de uso. Ver API y Conectores.

# Ejemplo de llamada autenticada con API key (cabecera Authorization)
curl -X POST https://api.shara.aiginer.com/v1/messages \
  -H "Authorization: Bearer sk_live_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Resume el último ticket de soporte y propón respuesta.",
    "idempotency_key": "req_2026-06-16_001"
  }'

Integración: webhooks entrantes firmados

SHARA expone webhooks entrantes firmados: un sistema externo (tu CRM, un formulario, n8n…) firma un evento y lo POSTea a SHARA, que verifica la firma y se lo entrega al agente configurado. No existen webhooks salientes por suscripción de eventos: el modelo es externo → SHARA, no al revés.

El endpoint público y sus cabeceras canónicas:

POST /webhooks/inbound/{slug}
Content-Type: application/json
X-SHARA-Signature: <hmac-hex>      # firma del cuerpo crudo (HMAC-SHA256 por defecto)
X-SHARA-Timestamp: <unix-seconds>  # anti-replay (±300 s); obligatoria si el webhook la declara
X-SHARA-Event-Id: <id-único>       # idempotencia (también se aceptan X-Event-Id, X-Request-Id…)

Ejemplo de cuerpo (lo defines tú; SHARA lo verifica, lo audita y lo entrega al agente):

{
  "event": "lead.created",
  "id": "evt_9f2c1ab7",
  "occurred_at": "2026-06-16T09:30:00Z",
  "contact": {
    "name": "Marta Ruiz",
    "email": "marta@example.com",
    "phone": "+34600111222",
    "company": "Example SL"
  },
  "source": "landing-form"
}

Respuesta correcta (200) y variante idempotente cuando reenvías el mismo X-SHARA-Event-Id:

// 200 — evento aceptado y encolado para el agente
{ "ok": true, "code": "ok", "eventId": "8b1d…-uuid", "runId": "run_…-uuid" }

// 200 — duplicado: SHARA ya lo procesó, no ejecuta de nuevo
{ "ok": true, "code": "duplicate", "eventId": "8b1d…-uuid" }

Errores posibles (sin filtrar internals):

Cómo firmar desde el lado emisor (Node). El HMAC se calcula sobre el cuerpo crudo exacto que vas a enviar, no sobre un JSON re-serializado:

import { createHmac } from 'node:crypto';

const secret = process.env.SHARA_WEBHOOK_SECRET;     // secreto por tenant, nunca en el cliente
const rawBody = JSON.stringify(payload);             // los MISMOS bytes que envías
const timestamp = Math.floor(Date.now() / 1000);     // unix-seconds, para anti-replay

const signature = createHmac('sha256', secret)
  .update(rawBody)
  .digest('hex');                                    // hex en minúsculas, 64 chars

await fetch('https://api.shara.aiginer.com/webhooks/inbound/mi-slug', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-SHARA-Signature': signature,
    'X-SHARA-Timestamp': String(timestamp),
    'X-SHARA-Event-Id': payload.id,                  // idempotencia
  },
  body: rawBody,
});

Reintentos: SHARA no reintenta la entrada; responde síncrono. Si recibes un 5xx o un *timeout*, reintenta tú reusando el mismo X-SHARA-Event-Id: la idempotencia garantiza que no se duplique la ejecución.

Integración: conectores

Operación: multi-tenant y licencias

¿Buscas un concepto más a fondo? Empieza por Arquitectura, STU y cuotas, API, Conectores o Seguridad.