API para desarrolladores

Conecta tu negocio en The Club Academy con tus herramientas: lee comunidades, cursos, inscripciones y órdenes, captura leads y recibe webhooks en tiempo real.

Autenticación

Crea una API key en el panel. Se muestra una sola vez; The Club Academy solo guarda su hash. Envíala en cada petición:

curl https://escuela.theclubcoffe.com/api/v1/communities \
  -H "Authorization: Bearer trb_live_XXXXXXXX"

También se acepta la cabecera X-API-Key. Cada key tiene permisos (scopes) y puede revocarse en cualquier momento.

Recursos

EndpointDescripción
GET /api/v1/communitiesTus comunidades
GET /api/v1/members?community_id=Miembros de una comunidad
GET /api/v1/coursesTus cursos (?status=published)
GET /api/v1/enrollmentsInscripciones (?course_id=)
GET /api/v1/ordersÓrdenes, solo lectura (?status=paid)
GET · POST /api/v1/leadsListar / crear o actualizar leads (upsert por email)

Paginación, límites y errores

Las listas usan cursor: ?limit=25&cursor=.... La respuesta trae data, has_more y next_cursor.

{ "data": [ ... ], "has_more": true, "next_cursor": "eyJ0Ijoi..." }

Límite por defecto: 60 solicitudes por minuto por key (ventana deslizante). Revisa X-RateLimit-Remaining; con 429 respeta Retry-After.

Los errores siempre tienen la misma forma:

{ "error": { "code": "insufficient_scope", "message": "...", "request_id": "..." } }

Ejemplo: capturar un lead

curl -X POST https://escuela.theclubcoffe.com/api/v1/leads \
  -H "Authorization: Bearer trb_live_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"email":"ana@ejemplo.com","name":"Ana","source":"landing","tags":["webinar"]}'

Webhooks salientes

Registra una URL https y elige eventos. The Club Academy envía un POST JSON firmado y reintenta con espera exponencial (hasta 8 intentos) si no recibe un 2xx.

Eventos: order.paidorder.refundedsubscription.canceledmember.joinedpost.createdcomment.createdreaction.receivedlesson.completedcourse.completedenrollment.created

POST https://tu-servidor.com/hook
Tribia-Event: order.paid
Tribia-Delivery: 7c1e...        # id único, úsalo para deduplicar
Tribia-Signature: t=1767225600,v1=5257a869...

{ "id": "...", "type": "order.paid", "created_at": "...", "creator_id": "...", "data": { "orderId": "...", ... } }

Verifica la firma: HMAC-SHA256 de `${t}.${cuerpo_crudo}` con tu secreto (whsec_...) y compara en tiempo constante. Rechaza timestamps con más de 5 minutos.

import { createHmac, timingSafeEqual } from "node:crypto";
function verify(raw, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const exp = createHmac("sha256", secret).update(t + "." + raw).digest("hex");
  return v1.length === exp.length && timingSafeEqual(Buffer.from(v1), Buffer.from(exp));
}

Guía: Zapier

  1. Crea una API key con los scopes que necesites en el panel.
  2. Recibir eventos (disparador): en Zapier elige Webhooks by Zapier → Catch Hook, copia la URL generada y regístrala como endpoint en The Club Academy. Pulsa Enviar prueba para que Zapier detecte los campos.
  3. Enviar datos a The Club Academy (acción): Webhooks by Zapier → Custom Request, método POST, URL https://escuela.theclubcoffe.com/api/v1/leads, Data Pass-Through = No, cabeceras Authorization: Bearer trb_live_... y Content-Type: application/json, cuerpo JSON con email, name…
  4. Leer datos: el mismo Custom Request con GET a cualquier recurso (por ejemplo /api/v1/orders?status=paid).

Guía: Make (Integromat)

  1. Disparador: módulo Webhooks → Custom webhook; copia su URL y regístrala en The Club Academy. Ejecuta Enviar prueba y luego Re-determine data structure.
  2. Acciones: módulo HTTP → Make a request con URL https://escuela.theclubcoffe.com/api/v1/..., cabecera Authorization: Bearer trb_live_..., Body type Raw / JSON y Parse response activado.
  3. Paginar: repite la petición con cursor=next_cursor mientras has_more sea true (Repeater o iterador).
  4. Opcional: importa openapi.json en Postman/Insomnia para explorar la API.