CChat369

API, webhooks e integraciones

Alcance

Chat369 ofrece una API REST versionada y webhooks salientes para integrar n8n, Make, Zapier, CRMs, ERPs, data warehouses y aplicaciones propias. Todo token, consulta y entrega pertenece a una sola empresa. La administración está en /developers y requiere ser propietario o tener permiso de configuración.

Reservas

Los tokens pueden recibir bookings.read y bookings.write. La empresa debe tener la capacidad incluida en su plan y haber activado reservas automáticas.

  • GET /api/v1/bookings: lista paginada y aislada por empresa.
  • GET /api/v1/booking-availability?service_id=ID&date=YYYY-MM-DD: cupos reales con recurso, inicio y fin ISO 8601.
  • POST /api/v1/bookings: crea una cita con service_id, resource_id, starts_at, customer_name y datos opcionales de contacto.
  • POST /api/v1/bookings/{public_id}/cancel: cancela respetando el plazo configurado.
  • PUT /api/v1/bookings/{public_id}/reschedule: reprograma con resource_id y starts_at.

Las respuestas usan identificadores públicos. Los eventos booking.created, booking.cancelled, booking.rescheduled, booking.completed y booking.no_show pueden seleccionarse en los webhooks salientes.

Autenticación

Las claves comienzan con c369_, se muestran una sola vez y la base de datos conserva únicamente SHA-256. Envíe siempre:

Authorization: Bearer c369_...
Accept: application/json
Content-Type: application/json

No coloque claves en JavaScript público, URLs, repositorios ni workflows exportados. Use credenciales protegidas o secretos del sistema de automatización. Revoque inmediatamente una clave expuesta.

Permisos disponibles:

Permiso Uso
assistants.read Listar asistentes
conversations.read Listar y consultar conversaciones
messages.read Leer mensajes dentro de una conversación
messages.write Enviar una respuesta humana/automatizada
leads.read Consultar contactos capturados
contacts.read Consultar perfiles, identidades e historial agregado
contacts.write Crear y actualizar contactos e identidades
products.read Consultar catálogo y variaciones

Endpoints API v1

Base: https://TU-DOMINIO/api/v1. Las listas usan paginación Laravel y aceptan per_page entre 1 y 100.

GET  /assistants
GET  /conversations?status=active&assistant_id=1&per_page=25&page=1
GET  /conversations/{id}
POST /conversations/{id}/messages
GET  /leads?per_page=25&page=1
GET  /contacts?status=active&per_page=25&page=1
GET  /contacts/{id-publico}
POST /contacts
PUT  /contacts/{id-publico}
GET  /products?assistant_id=1&per_page=25&page=1

Alta de contacto (las identidades se normalizan, cifran y se deduplican dentro de la empresa):

{
  "name": "María Cliente",
  "company": "Empresa Demo",
  "identities": [
    {"type": "email", "value": "maria@example.com"},
    {"type": "phone", "value": "+51999888777", "verified": true}
  ],
  "custom_fields": {"crm_id": "C-1024"}
}

Respuesta desde un sistema externo:

curl -X POST 'https://TU-DOMINIO/api/v1/conversations/123/messages' \
  -H 'Authorization: Bearer c369_REEMPLAZAR' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Hola, ya estamos revisando tu solicitud.",
    "idempotency_key": "7b594eed-b7f8-42c2-a9ef-690eb6216bf3"
  }'

idempotency_key evita duplicar el mensaje si n8n reintenta. La clave debe pertenecer a un usuario activo capaz de tomar la conversación. Las reglas del canal siguen vigentes; por ejemplo, WhatsApp conserva su ventana oficial de atención.

Respuestas comunes: 401 clave inválida/expirada, 403 permiso insuficiente o empresa suspendida, 404 recurso de otra empresa o inexistente, 422 validación/regla de negocio y 429 límite de solicitudes.

Webhooks salientes

Eventos disponibles:

message.created
conversation.handoff_requested
conversation.assigned
conversation.closed
lead.created
contact.created
contact.updated
contact.merged
contact.consent.updated

Formato:

{
  "id": "UUID_DEL_EVENTO",
  "event": "message.created",
  "created_at": "2026-07-15T12:00:00-05:00",
  "data": {
    "conversation_id": "UUID_PUBLICO",
    "message": {}
  }
}

Encabezados:

X-Chat369-Event
X-Chat369-Event-Id
X-Chat369-Timestamp
X-Chat369-Signature: v1=HEX

La firma es HMAC-SHA256(secreto, timestamp + "." + cuerpo_json_exacto). Verifique primero que la diferencia del timestamp sea menor de cinco minutos, calcule la firma sobre los bytes originales y compare en tiempo constante. Use X-Chat369-Event-Id como clave de idempotencia.

Ejemplo PHP:

$body = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_CHAT369_TIMESTAMP'] ?? '';
$received = $_SERVER['HTTP_X_CHAT369_SIGNATURE'] ?? '';
$expected = 'v1='.hash_hmac('sha256', $timestamp.'.'.$body, getenv('CHAT369_WEBHOOK_SECRET'));

if (abs(time() - (int) $timestamp) > 300 || ! hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}
http_response_code(200);

Chat369 considera éxito cualquier HTTP 2xx. El trabajo usa la cola integrations, timeout configurable y hasta cinco intentos con espera progresiva. El panel conserva estado, intentos, HTTP y una respuesta acotada. No se siguen URLs locales por defecto y producción exige HTTPS.

n8n: recibir eventos

  1. Cree un workflow y agregue el nodo Webhook con método POST.
  2. Copie su Production URL, no la Test URL.
  3. En Chat369 abra /developers, agregue el endpoint HTTPS y seleccione eventos.
  4. En n8n agregue un nodo Code para verificar firma usando el cuerpo original, o coloque la verificación en un proxy/API Gateway antes de n8n.
  5. Procese el evento, por ejemplo crear/actualizar el contacto en HubSpot, Airtable, Google Sheets o su CRM.
  6. Responda rápidamente 2xx; delegue trabajo lento a otros nodos/colas.
  7. Publique/active el workflow y use Enviar prueba en Chat369.

Documentación oficial: Webhook node.

n8n: consultar o responder mediante API

  1. Cree una clave con los permisos mínimos.
  2. En n8n use HTTP Request.
  3. Seleccione autenticación Header/Bearer y guarde la clave como credencial, no como texto en el nodo.
  4. Use la URL https://TU-DOMINIO/api/v1/... y habilite JSON.
  5. Para escribir mensajes genere un UUID estable por ejecución y envíelo como idempotency_key.

Documentación oficial: HTTP Request node.

Otras herramientas

  • Make/Zapier/Pipedream: disparador webhook para recibir eventos y módulo HTTP con Bearer para API.
  • CRM/ERP propio: consumidor HTTPS que verifique HMAC e idempotencia.
  • Slack/Teams/email: n8n recibe el evento y usa el conector correspondiente.
  • BI/data warehouse: proceso programado consulta listas paginadas; los webhooks sirven para actualización incremental.

Operación y seguridad

  • Mantenga Horizon consumiendo la cola integrations.
  • Configure INTEGRATION_WEBHOOK_TIMEOUT_SECONDS=10.
  • Mantenga INTEGRATION_ALLOW_PRIVATE_WEBHOOK_URLS=false en producción.
  • Rote/revoque claves y secretos por incidente o cambio de proveedor.
  • Pruebe primero con un endpoint que no contenga datos reales.
  • Supervise entregas failed, failed_jobs, Horizon y logs sin registrar claves ni secretos.
  • Un receptor debe tolerar duplicados, eventos fuera de orden y reintentos.