Documentación de integración

Conecta SARI con todo tu negocio

API REST + webhooks en tiempo real. Automatiza con n8n, Make, Zapier o tu propio sistema: recibe leads, responde por WhatsApp, otorga puntos, y reacciona a cada pago confirmado.

Autenticación

Genera tu API key en /crm/integrations dentro de tu panel SARI. Cada petición lleva el header Authorization:

Base URL:  https://v2.mysari.ai/api/v1
Header:    Authorization: Bearer sk_live_xxxxxxxx...

# Healthcheck sin auth:
GET /api/v1/ping

Permisos por key: read < write < admin. Todo queda aislado a tu cuenta (multi-tenant estricto).

Pagos automáticos

Recibe pagos con SPIDI

Tus clientes pagan en Bs. y cripto desde cualquier banco o billetera, directamente en el chat o en tu tienda. Cuando un pago se confirma, SARI dispara el evento spidi.payment_paid a tu sistema para que sigas el flujo: despachar el producto, activar el servicio, facturar.

1. El cliente paga

Por el chat (WhatsApp/IG/FB), tu tienda online, un link manual o un cobro programado.

2. La confirmación llega

SARI recibe la confirmación de SPIDI (webhook firmado + doble verificación).

3. SARI te avisa

Emite spidi.payment_paid a tu URL con el monto, la referencia y el origen del pago.

4. Tu flujo continúa

Tu n8n / Make / ERP recibe el evento y dispara la automatización que quieras.

// Payload del evento spidi.payment_paid
{
  "event": "spidi.payment_paid",
  "timestamp": "2026-06-16T20:00:00-04:00",
  "merchant_id": 123,
  "data": {
    "session_id": "ec4a3c64-...",
    "amount": 25.00,
    "currency": "USD",
    "status": "paid",
    "paid_at": "2026-06-16T20:00:00-04:00",
    "reference": "Plan Premium",
    "origin": "chat"
  },
  "idempotency_key": "uuid-v4"
}

Paga en Bs. y Cripto — desarrollado por SPIDI ⚡

API REST

Endpoints generales

POST /leads write

Crea un lead: contacto + conversación (canal WhatsApp, IA activa) + deal en el pipeline. Emite el evento lead.created.

POST /contacts write

Upsert de contacto (identidad global + canal). No pisa datos existentes, solo completa vacíos.

POST /messages/whatsapp write

Envía WhatsApp por el path real: window-aware (Cloud API fuera de la ventana de 24h cae al template aprobado) y respetando el warming del gateway.

GET /conversations/{phone} read

Estado de la conversación (status, modo IA, canal, contacto) + últimos 50 mensajes.

POST /otp/send write

Verificación por WhatsApp desde TU propio número. Envía un código de 6 dígitos al usuario final. Nunca devuelve el código.

POST /otp/verify write

Valida el código que recibió el usuario. Marca el teléfono verificado por 30 minutos.

Fidelización y SariCuotas

Puntos, carnets y financiamiento

Otorga puntos por compra, emite carnets de membresía y gestiona el crédito propio de tu negocio (SariCuotas) — todo desde tu sistema.

GET /loyalty/members/{phone} read

Datos del miembro: número, nivel, puntos, acumulado de por vida, progreso al siguiente nivel.

GET /loyalty/members/{phone}/history read

Historial de puntos (últimos 100 movimientos).

GET /loyalty/rewards read

Catálogo de recompensas activas que el cliente puede canjear.

POST /loyalty/members/{phone}/points write

Otorgar puntos por una compra. Idempotente por reference (un mismo pedido no acredita dos veces).

POST /loyalty/cards write

Emitir carnet de membresía (número de miembro automático). Body: phone, name, cédula, fecha de nacimiento.

POST /loyalty/redemptions/{code}/consume write

Validar y consumir un cupón de canje en mostrador/POS.

GET /financing/members/{phone}/status read

SariCuotas: estado del financiamiento del cliente (saldo, próxima cuota, vencida).

GET /financing/portfolio read

SariCuotas: KPIs de la cartera (financiado, por cobrar, en mora).

POST /financing/members/{phone}/report-payment write

SariCuotas: reportar el pago de una cuota. Estricto (referencia/método reales). No marca pagado — el dueño confirma.

Webhooks en tiempo real

Eventos salientes

Configura tu URL en /crm/integrations → Webhooks salientes y marca los eventos que quieras escuchar. SARI hace un POST JSON firmado a tu sistema cada vez que ocurren.

spidi.payment_paid

Un pago con SPIDI se confirmó (pago en chat, tienda, link manual o pago programado). Tu sistema sigue el flujo: despachar producto, activar servicio, facturar.

message.received

Cada mensaje entrante del cliente. Alto volumen — requiere suscripción explícita. Entrega asíncrona.

conversation.created

Nueva conversación (cualquier canal).

deal.created · deal.won · deal.lost

Deal creado / ganado / perdido (payload completo del deal).

lead.created

Lead entrante (API, HubSpot, TikTok Ads).

loyalty.points_granted · loyalty.card_issued · loyalty.redemption

Fidelización: puntos otorgados, carnet emitido, recompensa canjeada.

financing.payment_reported · financing.payment_confirmed · financing.defaulted

SariCuotas: pago reportado, pago confirmado, financiamiento en mora.

Verifica la firma (anti-suplantación)

Cada POST trae el header X-SARI-Signature. Valídalo con el secret de tu webhook:

X-SARI-Signature: sha256={hmac_sha256(raw_body, secret)}

// n8n Function node / Node.js
const crypto = require('crypto');
const expected = 'sha256=' + crypto
  .createHmac('sha256', SECRET)
  .update(rawBody)
  .digest('hex');
const valid = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(req.headers['x-sari-signature'])
);

Responde 2xx rápido y procesa async. Usa idempotency_key para no duplicar. Tras 15 fallos seguidos el webhook se desactiva (reactívalo en tu panel).

Guía rápida

Conecta con n8n, Make o Zapier

SARI → tu sistema (recibir eventos)

Crea un nodo Webhook en tu n8n/Make y copia su URL.
En SARI /crm/integrations → Webhooks salientes, pega la URL y marca los eventos (ej. spidi.payment_paid).
Guarda el secret y valida X-SARI-Signature.

Tu sistema → SARI (llamar la API)

Nodo HTTP Request: método POST.
Header Authorization: Bearer sk_live_...
Ej. responder por WhatsApp: POST /messages/whatsapp con {phone, text}.

Probar 14 días gratis O habla con ventas por WhatsApp

Sin tarjeta · Sin permanencia · Cancela cuando quieras · Soporte en español