Documentación API — Growth54

Reglas que aplican a todas las llamadas, independientemente del módulo o tipo de acceso. Leer esto antes de integrar cualquier endpoint.

Headers obligatorios en toda llamada

Accept: application/json
Content-Type: application/json

Códigos de error comunes

La API distingue cuatro tipos de caller, cada uno con su propio prefijo de ruta y mecanismo de autenticación. La separación es intencional: un agente de IA solo puede escribir datos de resultados, no acceder a la configuración del usuario; un workflow de n8n solo puede leer, no modificar.

Estos endpoints no requieren autenticación. Están diseñados para recibir leads desde formularios externos — una landing page en WordPress, un anuncio con formulario, etc. El rate limiting de 5 solicitudes por minuto evita que se use como vector de spam. Al registrar un cliente, el sistema crea el usuario en estado pendiente y lo asigna al flujo de onboarding.

curl -s -X POST "https://api.growth54.com/api/public/register-client" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"name":"Juan García","email":"juan@empresa.com"}' | jq

curl -s "https://api.growth54.com/api/health" | jq

El flujo estándar para el panel web. El login devuelve un token Bearer de Laravel Sanctum que se incluye en todas las llamadas posteriores. El token no expira automáticamente — se invalida llamando a logout. Después del login, el primer paso es llamar a switch-company para activar la empresa con la que se quiere trabajar.

curl -s -X POST "https://api.growth54.com/api/auth/login" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"email":"user@demo.com","password":"secret"}' | jq

curl -s -X POST "https://api.growth54.com/api/auth/switch-company" \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"company_id": 1}' | jq

El proceso que sigue un usuario recién registrado. Tiene dos caminos: crear una empresa nueva (y quedar como owner) o unirse a una empresa existente usando un código de invitación (y quedar como collaborator). Los códigos de invitación los generan los owners o admins de la empresa, y se pueden limitar en número de usos y fecha de expiración.

curl -s -X POST "https://api.growth54.com/api/onboarding/companies" \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"name":"Mi Empresa","industry":"Legal","website":"https://mi.com"}' | jq

-d '{"code":"ABC123"}'

-d '{"max_uses": 10, "expires_in_days": 30}'

Las keywords son el punto de partida del motor de contenido SEO. Cada empresa mantiene un banco de palabras clave clasificadas por dificultad, intención de búsqueda y fuente de origen. Los agentes de IA usan este banco para generar artículos relevantes y posicionar el sitio de la empresa. Las keywords pueden agregarse manualmente desde el panel o en bulk desde un workflow de n8n que haya hecho keyword research.

-d '{"keyword":"abogado laboral","dificultad_nivel":"media","intencion":"comercial","fuente":"Google"}'

Los artículos son el contenido SEO generado por los agentes a partir de las keywords. Cada artículo parte de una keyword, el agente genera el HTML completo y lo guarda como borrador. Desde el panel, el equipo lo revisa, edita si necesita y lo marca como revisado. Luego puede publicarse directamente en WordPress mediante la integración CMS. El listado no incluye el HTML para no sobrecargar la respuesta — se obtiene con el endpoint de detalle.

Las auditorías son reportes de análisis completos generados por agentes. A diferencia de la auditoría inicial (que es única por empresa), aquí puede haber múltiples auditorías acumuladas — por ejemplo, un análisis competitivo mensual, una revisión técnica post-migración, etc. Cada auditoría contiene un reporte HTML completo que se muestra en el panel.

Cada empresa tiene exactamente una auditoría inicial: el diagnóstico de punto de partida que se hace cuando el cliente comienza a usar Growth54. Analiza el sitio web, evalúa el SEO técnico, identifica oportunidades y genera un score. Este score sirve como línea base para medir el progreso en el tiempo. El agente n8n la genera automáticamente; si se vuelve a ejecutar, sobreescribe la anterior (upsert).

Registro de las URLs del sitio web de la empresa. Permite hacer seguimiento del posicionamiento por página individual y auditar cada URL de forma independiente. Las páginas se pueden agregar manualmente o descubrirse automáticamente mediante un crawl del sitio. Una vez registradas, el agente de auditoría SEO puede analizar cada URL y devolver recomendaciones específicas.

Catálogo de lo que vende la empresa. Los agentes de IA leen este catálogo antes de generar contenido para que los artículos, posts e ideas mencionen los productos reales del negocio y no generen texto genérico. Por ejemplo, un agente de RRSS que sabe que la empresa ofrece "auditoría gratuita de 30 minutos" puede incluirlo como CTA en los posts. Sin este catálogo, el agente genera contenido sin contexto comercial.

Conexiones con el sitio web de la empresa para publicar contenido directamente desde Growth54. Por ahora soporta WordPress vía su API REST. El flujo es: el equipo guarda las credenciales WordPress de la empresa (URL, usuario, application password) → el agente generador de artículos las usa para hacer un POST directo al CMS y publicar el artículo sin intervención manual. Las credenciales siempre requieren token aunque el servidor esté en modo provisional.

Registro global de los webhooks de n8n disponibles en la plataforma. Cada agente tiene una key única (por ejemplo rrss_strategist) y una URL de webhook. Cuando el usuario hace clic en "Ejecutar agente" en el panel, el backend busca la key correspondiente en esta tabla, obtiene el webhook y lo llama. Si el webhook no está registrado o el agente está inactivo, la llamada falla con 422 y el panel muestra un mensaje indicando que hay que configurarlo en esta sección. Esto permite cambiar o actualizar los workflows de n8n sin tocar el código del backend.

El módulo RRSS gestiona toda la operación de redes sociales de la empresa: desde la estrategia hasta la publicación y las métricas. Esta primera sección configura qué plataformas usa la empresa y con qué cuenta. Es el dato de partida que leen todos los agentes RRSS: sin canales configurados, los agentes no saben en qué plataformas generar contenido ni qué handle mencionar.

-d '{"channels":[{"platform":"instagram","active":true,"handle":"@miempresa"},{"platform":"linkedin","active":true}]}'

Una empresa tiene exactamente una estrategia RRSS. El PUT es upsert.

-d '{
  "objetivo":"Generar leads calificados","audiencia":"Dueños PYME 28-45 LATAM",
  "tono":"Profesional pero cercano","frecuencia":"6 posts semanales",
  "cta_principal":"Agendar llamada gratuita","embudo":"RRSS → Website → Lead → CRM",
  "plataformas":["Facebook","Instagram","LinkedIn"],
  "pilares":["Educación","Casos de éxito","Detrás de cámaras"],
  "kpis":["Alcance orgánico","Engagement","Leads generados"]
}'

El banco de ideas es el primer paso del pipeline de contenido social. Una idea es simplemente un tema propuesto: "5 errores que cometen las PYMEs en Instagram". Puede crearla manualmente el equipo, o puede generarlas el agente Content AI en bulk. El equipo revisa el banco y aprueba las que le parecen buenas — las aprobadas son las que el agente luego convierte en posts completos. Las descartadas quedan registradas para no proponer el mismo tema de nuevo.

-d '{"topic":"5 errores de PYMEs en Instagram","platform":"Instagram","keyword":"marketing PYME"}'

Un post es el contenido final listo para publicar. Cada post tiene copy adaptado para cada plataforma (Instagram, Facebook, LinkedIn), hooks alternativos para el inicio del texto, un CTA específico y opcionalmente una imagen o prompt para generarla con IA. El ciclo de vida es: el agente genera el borrador → el equipo lo revisa en el panel → lo aprueba → le asigna una fecha → queda programado. Cuando se publica, el sistema registra automáticamente quién lo aprobó y la fecha de publicación.

-d '{"status":"aprobado"}'

-d '{"fecha_programada":"2026-05-20T10:00:00"}'

El cierre del ciclo: después de publicar, el agente Analytics AI recoge los números reales de cada plataforma (alcance, impresiones, engagement, clics a perfil, leads generados) y los carga en la base de datos. La vista de métricas del panel muestra estos datos agrupados por plataforma y calcula promedios. También muestra el top 10 de posts por engagement, lo que permite al equipo identificar qué tipo de contenido funciona mejor para esa empresa.

// Respuesta:
{"data":[{"platform":"Instagram","alcance_total":12430,"impresiones_total":38000,
  "engagement_total":584,"engagement_rate_avg":4.7,"clics_total":384,"leads_total":17}]}

Cuando el usuario hace clic en "Ejecutar agente" en el panel, el frontend llama uno de estos endpoints. El backend busca la key del agente en la tabla agent_endpoints, obtiene la URL del webhook de n8n y lo dispara pasándole el company_id. Si el webhook no está configurado, responde con 422 y un mensaje indicando que hay que configurarlo en Panel › Configuración › Agentes. El agente trabaja de forma asíncrona: el webhook responde inmediatamente con 200 y n8n procesa en segundo plano.

-d '{"mode":"ideas","idea_id":null}'
-d '{"mode":"post","idea_id":5}'

Estos endpoints existen para que los workflows de n8n puedan leer el contexto de la empresa antes de generar contenido. Un agente que va a escribir artículos necesita saber la industria de la empresa, sus keywords, sus productos. Un agente RRSS necesita saber en qué plataformas está activa la empresa y cuál es su tono de comunicación. Todos son de solo lectura — los agentes leen desde aquí y escriben los resultados a través de los endpoints /api/agent/*.

Base: /api/n8n/companies/{id}/rrss/

Una vez que el agente termina su trabajo (generar keywords, escribir artículos, crear auditorías), usa estos endpoints para guardar los resultados en Growth54. Se identifican por el AGENT_API_TOKEN, distinto al token de usuario, lo que significa que el agente puede escribir datos sin tener una sesión de usuario activa. Todos los registros creados por esta vía quedan marcados con generated_by = 'n8n' para distinguirlos de los creados manualmente.

-d '{"empresa_id":1,"skip_existing":true,"keywords":[
  {"keyword":"abogado laboral","dificultad_nivel":"media","intencion":"comercial","fuente":"Google"}
]}'

-d '{"empresa_id":1,"articulos":[{"keyword_id":10,"titulo":"Guía de contrato","contenido_html":"<h1>...","estado":"borrador"}]}'

Todos los registros creados quedan con generated_by = 'n8n' automáticamente.

-d '{"company_id":3,"objetivo":"...","audiencia":"...","tono":"...",
  "plataformas":["Instagram","LinkedIn"],"pilares":["Educación"],"kpis":["Alcance"]}'

-d '{"company_id":3,"ideas":[{"topic":"5 errores PYME","platform":"Instagram","keyword":"marketing"}]}'

-d '{"company_id":3,"posts":[{
  "tema":"5 errores PYME","platform":"Instagram","social_idea_id":5,
  "copy_instagram":"¿Tu negocio está en IG pero no consigue resultados?\n...",
  "copy_linkedin":"En 2026, producir sin estrategia es el error más común...",
  "hooks":["Hook alternativo 1","Hook alternativo 2"],
  "cta":"Comenta o DM para auditoría gratuita.",
  "imagen_prompt":"Minimalist flat design 5 warning signs PYME"
}]}'

-d '{"company_id":3,"metricas":[{
  "platform":"Instagram","period_start":"2026-05-01","period_end":"2026-05-31",
  "social_post_id":12,"alcance":3420,"impresiones":10500,
  "engagement_count":212,"engagement_rate":6.2,"clics":89,"leads":4
}]}'

Todos los workflows empiezan con un nodo Set llamado Config.

BASE_URL    = https://api.growth54.com     ← producción
              https://xxx.ngrok-free.app   ← local con ngrok
AGENT_TOKEN = (AGENT_API_TOKEN del .env)
N8N_TOKEN   = (N8N_API_TOKEN del .env)
COMPANY_ID  = {{ $json.company_id }}      ← viene del trigger del panel

Lee perfil y canales, genera estrategia RRSS completa, la guarda. El equipo puede editarla desde el panel.

Eres un estratega RRSS experto en PYMEs latinoamericanas.
Empresa: {nombre} — {industria} — {país}
Canales activos: {plataforma, handle, objetivo, frecuencia}
Estrategia actual: {existente o "ninguna"}

Responde SOLO en JSON:
{"objetivo":"...","audiencia":"...","tono":"...","frecuencia":"...",
 "cta_principal":"...","embudo":"...","plataformas":[],"pilares":[],"kpis":[]}

Genera 10 ideas basadas en la estrategia y canales. Llegan con status = idea para revisión del equipo.

Genera 10 ideas de contenido para {nombre} ({industria}, {país}).
Objetivo: {objetivo} | Pilares: {pilares} | Canales: {plataformas}
Sé específico. Fechas: próximos 30 días.

Responde SOLO en JSON:
{"ideas":[{"topic":"...","platform":"Instagram|Facebook|LinkedIn",
           "keyword":"...","fecha_propuesta":"YYYY-MM-DD"}]}

Toma una idea aprobada y genera el post completo: copy por plataforma, hooks y CTA. Llega como borrador.

Eres copywriter experto en RRSS para PYMEs de LATAM.
Empresa: {nombre} | Tono: {tono} | CTA: {cta_principal}
Tema: {topic} | Plataforma: {platform} | Keyword: {keyword}

Responde SOLO en JSON:
{"copy_instagram":"texto con emojis y hashtags","copy_facebook":"texto conversacional",
 "copy_linkedin":"tono profesional","hooks":["hook1","hook2"],
 "cta":"llamada a la acción","imagen_prompt":"descripción en inglés para DALL-E"}

Lee métricas de las plataformas y las carga al backend.

Documentación completa de los planes disponibles en Growth54: funcionalidades incluidas, límites por plan y comparativa. Relevante para el equipo comercial y para entender qué módulos están disponibles para cada cliente.