Documentación API — Growth54

Registra un cliente desde formulario externo (WordPress, landing page, etc.).

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

Verifica que la app, base de datos y caché respondan.

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

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

Datos del usuario autenticado.

Cambia la empresa activa. Necesario antes de usar módulos.

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

Invalida el token actual.

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

GET lista · POST crear · GET/{id} · PUT actualizar · DELETE

Al crear con owner_user_id asigna rol owner automáticamente.

Crea empresa y asigna al usuario como owner.

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

Unirse con código de invitación. Rol: collaborator.

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

Genera código de invitación. Solo owner o admin.

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

Lista keywords de la empresa activa.

Totales por dificultad, intención, etc.

Crea keyword manual. Valores: dificultad_nivel: baja/media/alta · intencion: informacional/transaccional/comercial/local

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

Dispara el agente de keyword research para la empresa activa.

Dispara generación de artículo para una keyword específica.

Lista (sin HTML). estado: borrador/revisado/publicado

Detalle completo con HTML.

Marca como publicado y asigna fecha.

Lista (sin HTML).

Detalle con HTML del reporte.

Dispara el workflow n8n. El agente guarda el resultado vía /api/agent/auditoria-inicial.

Registra nueva URL del sitio.

Descubrimiento automático de páginas.

Dispara auditoría SEO para una URL específica.

Carga masiva de competidores desde un agente externo (n8n u otro workflow). Las URLs inválidas se descartan silenciosamente sin romper el batch. Soporta modo upsert (default) o insert_only con skip_existing: true. Los registros se guardan con origen = agente.

{
  "empresa_id": 1,
  "competitors": [
    { "url": "https://competidor.com", "name": "Competidor" },
    { "url": "otro.com" }
  ],
  "skip_existing": false
}

Credenciales CMS para que el agente pueda publicar. Siempre requiere token aunque el servidor esté en modo provisional.

Activa o desactiva el agente.

Prueba la conectividad con el webhook.

Upsert — actualiza el estado completo de los canales. Cada canal puede llevar image_config: la configuración de imagen que el cliente elige por red (no es igual para Instagram que para Facebook) y que después leen los agentes generadores. Todas sus claves son opcionales; se validan contra listas fijas y se limpia lo desconocido.

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

// Con image_config por canal:
{"channels":[{
  "platform":"Instagram","is_active":true,"handle":"@miempresa","publishing_mode":"manual",
  "image_config":{
    "img_estilo":"realista",        // realista | humanos | 3d | animado | minimalista | artistico
    "img_formato":"cuadrada",       // cuadrada (1:1) | vertical (4:5) | horizontal (16:9)
    "img_texto_modo":"sin_texto"    // sin_texto | solo_titulo | titulo_subtitulo | titulo_sub_detalles | libre
  }
}]}

data: null si no existe aún.

New 17-jul: acepta y guarda fecha_inicio, fecha_fin (horizonte temporal de la estrategia) y direccion_deseada (a dónde llevar la marca). Antes estos campos no existían y se descartaban. Se mantiene una estrategia por empresa (se sobrescribe al regenerar).

-d '{
  "fecha_inicio":"2026-07-01","fecha_fin":"2026-10-01",
  "direccion_deseada":"Posicionar la marca como referente regional",
  "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"]
}'

New 29-jul (B-17): se agregaron 6 campos que el Strategist AI ya generaba y que el guardado descartaba en silencio (mismo caso que fecha_inicio/fecha_fin/direccion_deseada el 17-jul): resumen_estrategico (texto), keyword_strategy, mapa_preguntas_aeo, faqs, clusters y plan_publicacion. Los 5 últimos se guardan como JSON: se prefiere mandar arrays, pero también se acepta texto plano. Aplican igual a POST /api/agent/rrss/estrategia, que es la vía que usa el agente.

-d '{
  "resumen_estrategico":"Posicionar la marca en logística regional",
  "keyword_strategy":[{"kw":"exportar a colombia","volumen":1200,"intencion":"comercial"}],
  "mapa_preguntas_aeo":["¿Cuánto cuesta exportar a Colombia?"],
  "faqs":[{"q":"¿Hacen envíos el mismo día?","a":"Sí, según zona"}],
  "clusters":["logistica","aduanas"],
  "plan_publicacion":[{"semana":1,"posts":3,"pilar":"Educación"}]
}'

Filtros: ?status=aprobado · ?platform=Instagram

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

{"status":"aprobado"}

Edita una idea ya creada. Pensado para corregir la plataforma que asignó el Strategist AI desde el panel (Banco de Ideas), sin tener que borrar y recrear. Campos opcionales: topic, platform, keyword, New angulo.

New angulo permite actualizar la justificación editorial junto con el título cuando se regenera una idea conservando su keyword. Antes se descartaba en silencio.

-d '{"platform":"Ambas"}'

platform válido: Facebook | Instagram | Ambas.

Filtros: ?status=borrador · ?platform=LinkedIn

Edita el contenido de un post desde el editor del panel. Campos opcionales: tema, platform, copy_instagram, copy_facebook, copy_linkedin, imagen_url, New video_url, hook, cta. El hook es un texto único (la primera línea que capta la atención); se persiste internamente en el array hooks.

-d '{"hook":"¿Sabías que el 80%...","cta":"Cotiza hoy","imagen_url":"https://.../post.png"}'

New 29-jul (B-14) — video_url, habilita Reels. Antes no existía la columna y el campo se descartaba en silencio, así que un post no podía llevar video adjunto. Se acepta en POST/PUT de posts y en POST /api/agent/rrss/posts, y se devuelve en GET /rrss/posts y GET /rrss/posts/to-publish — sin alias, se llama igual dentro y fuera. Debe ser una URL directa al archivo de video.

Elimina un post desde el panel. Solo se permiten posts en estado borrador — un post aprobado, programado o publicado devuelve 422. Útil para limpiar borradores duplicados generados en pruebas del Content AI.

Al aprobar → guarda approved_by_user_id. Al publicar → guarda fecha_publicada.

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

Programa post. Cambia status a programado. La fecha debe ser futura. New La hora se interpreta en la zona horaria de la empresa (companies.timezone); se guarda en UTC. Si la empresa no tiene zona, se asume UTC. Verifica que la empresa tenga su zona horaria establecida en Editar datos de la empresa → País / Zona horaria.

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

New 29-jul (B-12) — al programar se avisa a la alarma de publicación. En el mismo momento en que se guarda la fecha, el backend hace una llamada única a la key rrss_schedule_alarm de agent_endpoints. Es dispara y olvida: el resultado no afecta la respuesta, y si el webhook falla o no está configurado el post queda programado igual (queda anotado en el log). Reemplaza al puente que revisaba cada 2 minutos.

// Lo que recibe el webhook:
{"post_id":40,"company_id":34,"fecha_programada":"2026-08-03T20:36:34Z"}

No es solo este endpoint. El aviso sale por los 4 caminos que dejan un post programado: este schedule, POST /api/rrss/posts creado ya con status:"programado", PUT /api/rrss/posts/{id} (el composer del calendario edita fecha y estado juntos) y PUT /api/rrss/posts/{id}/status.

Cuándo NO se avisa — para no mandar alarmas duplicadas ni inútiles: si solo se editó el contenido de un post ya programado (no cambió ni la fecha ni el estado); si la fecha quedó en el pasado; si el post no está en programado; o si la key rrss_schedule_alarm no está activa. Reprogramar a otra fecha sí vuelve a avisar, con la fecha nueva.

Sube una imagen desde el equipo del usuario para adjuntarla a un post (el editor del panel la usa cuando el operador arrastra o elige un archivo, como alternativa a pegar una URL). El backend optimiza la imagen: la reescala a un máximo de 1600px de ancho, la aplana sobre fondo blanco y la recomprime a JPEG (calidad 80). Devuelve una URL pública lista para guardar en imagen_url del post. multipart/form-data, campo file, máx. 10 MB, solo imágenes.

curl -s -X POST "https://api.growth54.com/api/images/upload" \
  -H "Authorization: Bearer <token>" \
  -F "file=@/ruta/imagen.png"

// Respuesta 201:
{"ok":true,"url":"https://.../storage/ai-images/<uuid>.jpg","bytes":184320}

Resumen de cuenta por plataforma. Filtros: ?platform=Instagram · ?from=2026-05-01 · ?to=2026-05-31

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

Cambió el 17-jul: (1) los números salen como número; antes eran texto ("5000") y el panel los concatenaba en vez de sumarlos (mostraba 050003200). (2) El agregado ahora excluye las filas con social_post_id: guardar métricas de un post ya no infla el total de la cuenta. Esas métricas siguen en top-posts.

Si el GET "no refleja lo que acabas de guardar": no es caché. Devuelve la suma del período, no el último valor — 16 sobre un histórico de 5000 da 5016. Además el guardado por agente usa el company_id del body y esta lectura usa la empresa activa de la sesión: si no coinciden, miras otra empresa.

Top 10 posts por engagement.

New 17-jul: métricas de cuenta agrupadas por número de semana relativo al fecha_inicio de la estrategia vigente. Sin estrategia con fecha responde has_strategy_dates:false y data:[]. Filtro opcional ?platform=Instagram.

// Respuesta:
{"data":[{"semana":1,"alcance_total":1000,"clics_total":50,"leads_total":5}],
 "has_strategy_dates":true,"fecha_inicio":"2026-07-01","fecha_fin":"2026-10-01"}

Histórico de la empresa activa, del más reciente al más viejo. No devuelve el html a propósito: un reporte mensual pesa cientos de KB y el listado cargaría megas por gusto.

// Respuesta:
{"data":[{"id":7,"titulo":"Reporte julio 2026","periodo_inicio":"2026-07-01",
  "periodo_fin":"2026-07-31","modo":"completo","generated_by":"n8n","updated_at":"..."}]}

El reporte con su html completo, para mostrarlo o compartirlo. Un reporte de otra empresa devuelve 403.

Envía el reporte por correo a uno o varios destinatarios (máximo 20). Usa el SMTP de la propia empresa, el que ya está configurado en Ajustes → Correo electrónico, así el cliente lo recibe desde la dirección de su marca y no desde una de Growth54.

-d '{"destinatarios":["cliente@empresa.com","socio@empresa.com"],
     "mensaje":"Hola, te comparto el reporte del mes."}'

// 200: {"ok":true,"message":"Reporte enviado."}
// 422: {"ok":false,"message":"Falta configurar el correo de la empresa..."}

El reporte viaja de dos formas a la vez: como cuerpo HTML (se ve al abrir el correo) y como archivo .html adjunto. El adjunto está porque Gmail y Outlook recortan CSS moderno, y así el reporte siempre se puede abrir intacto en el navegador. Se incluye también una versión en texto plano y una copia oculta al remitente, para que quede constancia en su bandeja.

Errores: 422 si la empresa no tiene correo configurado o activo, o si el servidor SMTP rechaza el envío (el mensaje incluye el motivo que devolvió el servidor). 403 si el reporte es de otra empresa. Un destinatario mal formado devuelve 422 de validación.

Borra un reporte del histórico. Un reporte de otra empresa devuelve 403.

// Respuesta (un objeto por paso):
{"data":[{"key":"rrss_analytics","nombre":"Analytics AI","disponible":true,
  "configurado":true,"estado":"listo","valor":"129.671","unidad":"de alcance acumulado",
  "detalle":"2 lecturas de métricas.","accion":"analytics","ultima_actividad":"..."}],
 "resumen":{"listos":4,"total_disponibles":6}}

estado: listo (ya produjo algo) · pendiente (configurado, sin usar) · sin_configurar (falta el webhook_url) · proximamente (el agente no existe todavía en agent_endpoints).

New Community AI y Sales AI dejan de estar clavados en "Próximamente". Antes su estado estaba escrito a mano en el código; ahora se deriva de agent_endpoints igual que el resto: si existen las keys rrss_community_ai / rrss_sales_ai activas y con webhook, las tarjetas pasan a estado real. Su actividad se mide con los contactos (wa_contacts) y deals (crm_deals) cuyo origen es facebook o instagram.

New Analytics AI mostraba 0 de alcance acumulado teniendo métricas reales. Contaba social_post_id distintos, y las métricas de cuenta se guardan con ese campo en NULL — COUNT(DISTINCT NULL) da 0 y escondía el total. Ahora cuenta filas y agrega el alcance con el mismo criterio que GET /api/rrss/metricas (solo filas de cuenta, para no duplicar), con las filas por post como respaldo si no hay ninguna de cuenta. Los dos números ahora coinciden.

Key: rrss_strategist

New · 6-ago (I-1) Acepta el brief del cliente, ambos campos opcionales: horizonte_meses (solo 1, 3, 6 u 8; otro valor da 422) y direccion_deseada (texto libre, máx. 2000). El panel los pide en un modal antes de disparar el agente. Cuando llega horizonte_meses, el backend calcula además el bloque periodo con las fechas ya resueltas, para que el agente no tenga que hacer aritmética de calendario. Sin brief el payload sale idéntico a como salía antes.

-d '{"horizonte_meses": 6, "direccion_deseada": "Posicionar la marca como referente"}'

# lo que recibe n8n:
{
  "company_id": 19,
  "trigger": {"source": "ui", "user_id": 1},
  "horizonte_meses": 6,
  "periodo": {"fecha_inicio": "2026-08-07", "fecha_fin": "2027-02-07"},
  "direccion_deseada": "Posicionar la marca como referente"
}

Key: rrss_content_ai. mode: ideas | post. idea_id se reenvía a n8n.

New 17-jul (I-5): el botón "Regenerar" de una idea llama a este endpoint con mode:"ideas" y el idea_id de esa idea. Acción para Sol: el flujo ideas-ai-g54 debe, cuando llega idea_id, regenerar esa idea conservando su keyword (en vez de generar un lote nuevo).

New 29-jul — por qué ideas-ai-g54 no registra ejecuciones: el botón sí dispara. El panel nunca llama a un webhook de n8n directamente: llama a este endpoint y el backend reenvía a la URL guardada en agent_endpoints para la key rrss_content_ai. Si esa fila apunta a otro webhook, el flujo ideas-ai-g54 no ve nada. Además el contrato es el de arriba (mode/ideas), no modo/regenerar: los nombres deben coincidir. Para conectarlo hay que alinear ambas cosas — la URL de la fila y los nombres de campos.

-d '{"mode":"ideas","idea_id":null}'   // genera lote nuevo
-d '{"mode":"ideas","idea_id":5}'      // regenera la idea 5 con su keyword
-d '{"mode":"post","idea_id":5}'

Key: rrss_analytics

Lista todas las empresas.

Perfil de empresa (sin datos sensibles).

Filtros: ?estado=activa · ?origen=manual

Solo keywords sin artículo.

Detalle con HTML del reporte.

Canales activos con handle, objetivo, frecuencia y rol en el embudo.

null si no existe.

Solo ideas con status aprobado.

Posts con status aprobado o programado.

Traduce un page_id de Meta a la empresa dueña. Meta manda el page_id en el webhook pero no el company_id; esta es la vía para resolverlo (Community AI multiempresa). Devuelve 404 si el page_id no está registrado.

{"company_id": 19, "fb_access_token": "EAA...", "ig_user_id": "17841446392201293"}

Inserta o actualiza keywords en bulk. skip_existing: true no toca las existentes.

-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"}]}'

Guarda o actualiza la auditoría inicial (upsert por empresa).

New 17-jul: acepta fecha_inicio, fecha_fin y direccion_deseada (igual que el PUT del panel). Sigue haciendo updateOrCreate por empresa.

New 29-jul (B-17): acepta también resumen_estrategico, keyword_strategy, mapa_preguntas_aeo, faqs, clusters y plan_publicacion. Ver el ejemplo completo en RRSS — Estrategia.

-d '{"company_id":3,"fecha_inicio":"2026-07-01","fecha_fin":"2026-10-01",
  "direccion_deseada":"...","objetivo":"...","audiencia":"...","tono":"...",
  "plataformas":["Instagram","LinkedIn"],"pilares":["Educación"],"kpis":["Alcance"]}'

Bulk. Respuesta: {"ok":true,"created":N}

New Ahora acepta y guarda angulo (justificación de la idea, texto — se muestra al cliente bajo el tema) y es_tendencia (booleano — pinta el badge "Tendencia" en el panel). Ambos opcionales; si no se mandan, la idea queda sin justificación y sin marca.

-d '{"company_id":3,"ideas":[{"topic":"5 errores PYME","platform":"Instagram","keyword":"marketing","angulo":"Aborda el dolor #1 de las PYMEs este trimestre","es_tendencia":true}]}'

Bulk. Llegan con status = borrador.

-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...",
  "hook":"¿Sabías que el 80% de las PYMEs comete este error?",
  "cta":"Comenta o DM para auditoría gratuita.",
  "imagen_prompt":"Minimalist flat design 5 warning signs PYME"
}]}'

Campo hook (singular) New — El Content AI puede enviar hook como un solo texto (la primera línea del post). Se guarda y se edita igual desde el panel. Sigue aceptándose hooks (array) por compatibilidad, pero se recomienda hook.

New 29-jul (B-14): acepta posts.*.video_url para posts con video (Reels). Ver RRSS — Posts.

New 29-jul (B-10). Guarda el reporte HTML de un período para que quede disponible en el panel. Es upsert por company_id + periodo_inicio + periodo_fin + modo: regenerar el reporte de un mes reemplaza el anterior en vez de acumular copias. Devuelve 201 si lo creó y 200 si lo actualizó.

-d '{"company_id":3,"titulo":"Reporte julio 2026",
  "periodo_inicio":"2026-07-01","periodo_fin":"2026-07-31",
  "modo":"completo","html":"<html><body>...</body></html>"}'

// Respuesta 201 (no devuelve el html de vuelta):
{"ok":true,"data":{"id":7,"titulo":"Reporte julio 2026",
  "periodo_inicio":"2026-07-01","periodo_fin":"2026-07-31","modo":"completo"}}

Obligatorios: company_id, titulo, periodo_inicio, periodo_fin, html. modo es opcional y sirve para guardar varias versiones del mismo período (por ejemplo resumen y completo) sin que una sobrescriba a la otra. Un periodo_fin anterior al inicio devuelve 422. El HTML se guarda en longText: probado con 360 KB sin truncar. Las rutas de lectura están en RRSS — Reportes HTML.

Borra un post (limpieza de duplicados de pruebas). Solo borradores: un post aprobado/programado/publicado devuelve 422 con {"ok":false,"error":"..."}.

Lo llama el Distribution AI después de intentar publicar. Cambió el 17-jul: antes el external_post_id se validaba pero nunca se guardaba, y un fallo dejaba el post atascado en programado sin aviso.

// Éxito:
-d '{"external_post_id":"17912345678901234",
     "link_url":"https://www.instagram.com/p/ABC123/"}'
// → status=publicado · guarda post_id_platform + link_url · limpia error_message
// → {"ok":true,"data":{...post...}}

// Fallo:
-d '{"error_message":"Instagram requiere imagen: el post no tiene imagen_url"}'
// → el post VUELVE a `aprobado` y guarda el motivo (el cliente lo ve en el panel)
// → {"ok":false,"message":"..."}

link_url es un parámetro nuevo, opcional. Un post ya publicado no se revierte. Enviar external_post_id:"" no borra un ID ya guardado; llamar dos veces es seguro.

⚠️ Para reportar fallos usa esta ruta. PUT /api/rrss/posts/{id}/status no acepta el AGENT_TOKEN (da 401) y seguirá así: resuelve la empresa desde el usuario de la sesión, y un agente no tiene usuario. Si reportas el fallo por ahí, el post se queda atascado y el cliente no ve nada.

Acumula, no sobrescribe: cada llamada inserta una fila nueva con su período. Manda social_post_id para métricas de un post; omítelo para las de cuenta. New Desde el 17-jul las métricas por post ya no inflan el agregado de cuenta.

-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
}]}'

Corregido el 17-jul: telefono y origen ya se pueden editar. Antes la ruta respondía 200 pero ignoraba esos dos campos en silencio (no estaban en la validación), así que un dato mal guardado ahí era incorregible.

-d '{"telefono":"+593999888777","origen":"agente"}'
// → 200 y ahora sí persiste

// Campos editables:
// nombre · etapa · valor_estimado · responsable · lead_score
// temperatura · notas · posicion · telefono (New) · origen (New)

Solo afecta a deals de la empresa activa; el de otra empresa devuelve 404.

Valores válidos de origen: whatsapp · web · manual · agente · importacion · New facebook · instagram. Es un enum de base de datos. 17-jul (B-5): se agregaron facebook e instagram vía migración; antes no existían. En contactos de WhatsApp el enum es distinto: rrss · web · qr · ai · direct · New facebook · instagram.

New 17-jul: un origen fuera del enum, o un telefono de más de 30 caracteres, ahora devuelven 422 con el campo señalado. Antes reventaban con 500 y el SQL crudo (1265 Data truncated / 1406 Data too long).

Lo llama Telegram, no una persona. Se protege con dos cosas a la vez: el {secret} de la URL, que identifica a la empresa, y la cabecera X-Telegram-Bot-Api-Secret-Token, comparada en tiempo constante. Si algo no cuadra responde 404 sin dar pistas.

Siempre responde 200, incluso si algo falla al guardar: si devolviera error, Telegram reintentaría y acabaría duplicando el mensaje. Los updates que no son texto (fotos, stickers) se ignoran con {"ok":true,"ignorado":true}.

{
  "update_id": 1,
  "message": {
    "chat": { "id": 555001, "type": "private" },
    "from": { "id": 555001, "first_name": "Walter", "username": "waltergz" },
    "text": "Hola, quiero información"
  }
}

curl -s -X POST "https://api.growth54.com/api/agent/whatsapp/inbound" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "empresa_id": 1,
    "phone": "+50588001234",
    "name": "Carlos Medina",
    "estado": "hot",
    "origen": "rrss",
    "datos_calificacion": {
      "carga": "maquina industrial",
      "destino": "Colombia",
      "peso_lbs": 300
    },
    "messages": [
      { "rol": "bot",  "contenido": "Hola, ¿en qué te ayudo?",       "sent_at": "2026-05-13 10:32:00" },
      { "rol": "user", "contenido": "Quiero cotizar una exportación", "sent_at": "2026-05-13 10:33:00" },
      { "rol": "sys",  "contenido": "Lead clasificado como CALIENTE" }
    ],
    "followup": {
      "tipo": "24h",
      "scheduled_at": "2026-05-14 10:33:00",
      "mensaje": "Hola Carlos, ¿sigues interesado en la cotización?"
    }
  }'

Comportamiento: si el contacto (empresa_id + phone) ya existe, actualiza nombre/estado/origen/calificación. Si la conversación activa ya existe, agrega los mensajes a ella. Si se envía followup, crea un registro en wa_followups.

Campos obligatorios: empresa_id, phone, messages (mínimo 1).

Valores válidos: estado: hot | warm | cold — origen: rrss | web | qr | ai | direct | New facebook | instagram — messages.*.rol: bot | user | sys — followup.tipo: 24h | 72h | 30d | custom.

New 29-jul (B-15): facebook e instagram devolvían 422 aunque el enum de wa_contacts ya los aceptaba desde el 17-jul: faltaba agregarlos a la validación de esta ruta. Ya corregido — se pueden volver a mandar.

El phone va url-encoded (ej. %2B17867880417 para +17867880417).

curl -s "https://api.growth54.com/api/n8n/companies/1/wa/leads?phone=%2B17867880417" \
  -H "Authorization: Bearer $N8N_TOKEN"

# Respuesta (lead existente):
{
  "data": [{
    "id": 7,
    "contact_name": "Carlos Medina",
    "phone": "+17867880417",
    "estado": "hot",
    "historial": "Agente: Hola, ¿en qué te ayudo?\nCliente: Quiero cotizar",
    "datos": { "producto": "cajones cerrados", "medidas": "40x30x20" },
    "created_at": "2026-06-20T14:08:00Z",
    "updated_at": "2026-06-26T14:08:00Z"
  }]
}

# Sin lead para ese teléfono:
{ "data": [] }

Flujo: llega mensaje → GET wa/leads. Si data[0] existe → carga historial y datos (el bot recuerda). Si data[] vacío → cliente nuevo, saluda desde cero. Al responder → POST /api/agent/whatsapp/inbound actualiza historial y datos.

Notas: estado es del contacto (hot | warm | cold); la calificación fina vive en datos (de wa_contacts.datos_calificacion). El historial rotula los turnos como Cliente / Agente / Sistema (mapeo de user / bot / sys).

Borra de golpe todos los leads de WhatsApp de la empresa. Ideal para resetear entre pruebas.

curl -s -X DELETE "https://api.growth54.com/api/agent/companies/1/whatsapp/leads" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"confirm":"DELETE"}'

# Respuesta:
{
  "ok": true,
  "company_id": 1,
  "deleted": { "contacts": 12, "deals": 4 },
  "message": "Todos los leads de WhatsApp de la empresa fueron eliminados (contactos, conversaciones, mensajes, followups y deals)."
}

Borra un lead puntual (por id de contacto). No requiere confirm. Devuelve 404 si el contacto no existe o no pertenece a esa empresa.

curl -s -X DELETE "https://api.growth54.com/api/agent/companies/1/whatsapp/leads/7" \
  -H "Authorization: Bearer $AGENT_TOKEN"

# Respuesta:
{
  "ok": true,
  "company_id": 1,
  "contact_id": 7,
  "deleted_deals": 1,
  "message": "Lead de WhatsApp eliminado (contacto, conversaciones, mensajes, followups y deals asociados)."
}

Totales del panel: conversaciones, leads (hot+warm), hot, cotizaciones y ventas_cerradas. Los dos últimos provienen del módulo CRM (deals en etapa proposal+ y closed) — solo lectura, no afectan a los agentes.

Lista paginada de conversaciones con datos del contacto y último mensaje. Ordenadas por updated_at descendente.

Conversación completa: datos del contacto + todos los mensajes ordenados por sent_at.

Follow-ups activos (estado: pendiente | programado | activo) ordenados por scheduled_at. Incluye nombre y teléfono del contacto.

curl -s -X POST "https://api.growth54.com/api/whatsapp/reply" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": 12,
    "message": "Hola, te confirmo la cotización."
  }'

Respuesta manual del operador desde el panel. Guarda el mensaje saliente (rol: bot) en la conversación de la empresa activa y lo reenvía a n8n como transporte hacia WhatsApp (Graph API). La conversación debe pertenecer a la empresa activa.

Devuelve New: siempre 201 cuando el mensaje se guarda, con { ok, sent, data, message }. El mensaje guardado incluye ahora estado (enviado | fallido | pendiente) y transporte_detalle (código HTTP y respuesta de n8n, o el error de red). ok y sent valen false si el transporte no aceptó el envío. Antes, si el webhook no estaba configurado se devolvía 422; ahora el mensaje se guarda y se marca fallido.

⚠️ Alcance de sent: significa que n8n aceptó el POST, no que Meta haya entregado el mensaje al cliente. Los acuses reales de Meta (sent → delivered → read) aún no se reciben.

curl -s -X DELETE "https://api.growth54.com/api/whatsapp/leads/45" \
  -H "Authorization: Bearer $TOKEN"

Reset total de un lead de WhatsApp (herramienta de debugging para limpiar pruebas). El {id} es el contact.id que devuelve GET /api/whatsapp/conversations. Borra el contacto y todo lo que cuelga de él: conversaciones, mensajes, follow-ups y su(s) ficha(s) del CRM (con sus actividades y eventos). No hay UI: es solo API a propósito, por ser destructivo.

Aislado por empresa activa: solo borra leads de la empresa del token; un id de otra empresa devuelve 404. Respuesta 200: { ok, contact_id, deleted_deals, message }.

POST https://n8n.mdarthurdigital.com/webhook/wa-reply-g54
Content-Type: application/json
Authorization: Bearer $N8N_WA_REPLY_WEBHOOK_TOKEN   # solo si el env está definido

{
  "phone": "+5215512345678",
  "message": "Hola, te confirmo la cotización.",
  "company_id": "20",
  "phone_number_id": "1083260611538246"
}

Contrato de salida. Growth54 envía exactamente esos cuatro campos. El destino se configura en agent_endpoints (key wa_reply) o en el env N8N_WA_REPLY_WEBHOOK_URL. Timeout: 12 s (6 s de conexión). Cualquier respuesta 2xx se interpreta como aceptada.

New phone_number_id: el número de Meta de la empresa activa, tomado de wa_configs. Sirve para resolver las credenciales de forma dinámica, sin cablearlas por empresa: pasarlo a GET /api/agent/wa/empresa-by-phone/{phone_number_id}, que devuelve company_id, wa_access_token y el resto de la config.
Si la empresa no tiene WhatsApp configurado, Growth54 no llama al webhook y marca el mensaje como fallido.

⚠️ n8n (lado Solange) — cuatro condiciones:

1. Solo transporte. Enviar a WhatsApp por Graph API, pero NO volver a guardar el mensaje en G54: el panel ya lo persiste y se duplicaría. (La API solo acepta rol bot, user o sys; agent/agente devuelve 422.)
2. Nombres de campos. El flujo debe leer phone, message, company_id y phone_number_id tal cual (no telefono, texto, mensaje ni to).
3. Credenciales dinámicas. Resolver el token con empresa-by-phone usando el phone_number_id recibido. No cablear tokens por empresa: no escala multiempresa.
4. Autenticación. Si el webhook exige token, avisar para definir N8N_WA_REPLY_WEBHOOK_TOKEN; hoy no se envía cabecera Authorization.

Responder 2xx solo si el envío a Meta salió bien. Si n8n responde 200 antes de llamar a Graph API, el panel marcará enviado un mensaje que nunca llegó.