Construye sobre Granetra
Una API REST limpia y webhooks firmados para tus agentes de soporte AI. Crea una clave en la página de Desarrolladores de tu panel y comienza a construir en minutos.
https://granetra.com/api/v1API REST
Lista bots, lee conversaciones y transcripciones, envía mensajes de chat y gestiona acciones agénticas, todo con una clave bearer específica.
Webhooks firmados
Recibe un POST HMAC con marca de tiempo en el momento en que comienza una conversación, un visitante solicita un humano o se captura un lead, con reintentos y un registro de entrega.
Construido para la automatización
Rota claves, bloquea su uso a las IPs de tu servidor y gestiona la configuración del bot desde CI/CD. Todo lo que hace el panel, a través de la API.
Referencia de API
URL base: https://granetra.com/api/v1
Autenticación
Pasa tu clave API como un token bearer en cada solicitud:
Authorization: Bearer gk_your_key_here
Las claves son específicas. Una solicitud a un endpoint para el cual tu clave no está autorizada devuelve 403 insufficient_scope. Alcances disponibles: bots:read, conversations:read, chat:write, actions:read, actions:write.
Endpoints
| GET | /bots | Lista tus bots |
| GET | /bots/:id | Un solo bot |
| GET | /bots/:id/conversations | Lista conversaciones |
| GET | /conversations/:id | Una transcripción de conversación |
| POST | /chat | Enviar un mensaje, recibir una respuesta |
| GET | /bots/:id/actions | Lista las acciones agénticas de un bot |
| POST | /bots/:id/actions | Crear una acción |
| PATCH | /bots/:id/actions/:actionId | Actualizar una acción |
| DEL | /bots/:id/actions/:actionId | Eliminar una acción |
Enviar un mensaje de chat
curl -X POST https://granetra.com/api/v1/chat \
-H "Authorization: Bearer gk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"bot_id": "00000000-0000-0000-0000-000000000000",
"message": "What are your opening hours?"
}'
# → { "conversation_id": "…", "message_id": "…", "fallback": false, "reply": "We're open 9–5 Mon–Fri." }
# Pass the returned conversation_id back to continue the same thread.Gestionar acciones agenticas
Registra tus propios endpoints HTTPS como herramientas que el bot puede llamar durante la conversación — gestionálos desde CI/CD en lugar del panel de control. Requiere el alcance actions:write y un bot en el plan Scale.
curl -X POST https://granetra.com/api/v1/bots/BOT_ID/actions \
-H "Authorization: Bearer gk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "lookup_order",
"description": "Look up an order status by number",
"url": "https://api.yourstore.com/orders",
"method": "GET",
"parameters": [
{ "name": "order_number", "type": "string", "description": "The order #", "required": true }
]
}'
# → { "ok": true, "id": "…" }Eventos de webhook
Cada entrega es un POST JSON con este sobre:
{
"id": "delivery-uuid",
"type": "handoff.requested",
"created": "2026-07-20T12:00:00.000Z",
"data": { "bot_id": "…", "conversation_id": "…" }
}Tipos de eventos: conversation.created, handoff.requested, lead.captured.
Verificación de firmas
Cada webhook lleva un encabezado X-Granetra-Signature de la forma t=<unix>,v1=<hmac>. Recalcula el HMAC-SHA256 de `${t}.${rawBody}` con el secreto de firma de tu endpoint y compara:
import crypto from "node:crypto";
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = crypto
.createHmac("sha256", secret)
.update(`${parts.t}.${rawBody}`)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}Responde con cualquier 2xx para confirmar. Un código no 2xx o un tiempo de espera se reintentará con retroceso; una larga serie de fallos desactiva automáticamente el endpoint.
Bloqueando una clave a tus IPs
Una clave puede llevar una lista de permitidos de IP opcional (direcciones IPv4 individuales o rangos CIDR). Cuando se establece, las solicitudes de cualquier otra dirección son rechazadas con 403 ip_not_allowed. Adminístralo por clave en el panel de control.