n8n-nodes-tcplus

Nodes nativos n8n para a 3C Plus (plataforma de telefonia do Grupo 3C). Substitui o copia-cola de nós Code/HTTP entre os clientes — os gotchas validados em produção (CLAUDE.md) já vêm embutidos.

O que vem

• Credencial 3C Plus API — api_token (não expira) ou Bearer (12h); injeção automática na query ou no header (gotcha #2). Teste via GET /me.
• Node 3C Plus (Resource + Operation) — pensado como integração CRM: tudo apontável, nada de caçar ID.
  • Mailing (núcleo): Subir Mailing (mailing_sync.json, single ou lote com chunk + relatório imported/filtered[].motive, gotcha #17) — campanha e lista por dropdown, com opção de criar lista nova na hora / Criar Lista / Remover do Mailing
  • Chamada: Classificar (call-history → bucket canônico, transformação pura) / Buscar por SID (poll de qualificação pré-ACW)
  • Agente: Listar Agentes (id/nome/email/ramal, sem api_token — gotcha #11) / Casar de-para com CRM (mapa agent_id 3C → ID do CRM por e-mail, fim do SDR_MAP na mão; reporta não-casados)
  • Campanha (setup): Screen-Pop URL / Peso da Lista (gotcha #20) — roda 1x por campanha

Dropdowns dinâmicos. Campanha, lista (encadeada à campanha) e qualificação são carregadas da API (GET /campaigns, /campaigns/{id}/lists, /lists/qualifications) — você escolhe pelo nome, o node resolve o ID.

Sem Resource Agent (desde v0.4). Login/dial/hangup/qualify são operação de softphone em tempo real, não integração CRM — discagem/eventos vivem no Socket.IO / extensão click2call.

Sem Trigger por design. Eventos via Socket.IO (relay → Webhook node nativo do n8n).

Gotchas embutidos

| # | Onde | |---|---| | #2 auth dupla (query / Bearer) | credencial | | #6 erros em 2 formatos | shared/errors.ts | | #17 mailing_sync.json (array, phone 11 díg) + chunk + parse de filtered[].motive | Mailing > Upload | | #18 204 ≠ concluído | avisos nas ações de Agent | | #20 peso da lista > 0 | Campaign > Set List Weight | | #9/#22/#24 classificação por qualification > status_id > hangup_cause | shared/classify.ts (reaproveitável em Code nodes) |

Não resolvido por design: listener Socket.IO 24/7 (n8n não mantém conexão persistente). Use /webhook_events apontando para o Trigger, ou um relay Socket.IO → URL do Trigger.

204 ≠ concluído (gotcha #18): as ações de Agent retornam 204 (aceito, assíncrono). Confirme o efeito real pelo evento correspondente no Trigger antes de seguir.

Build & instalação (n8n auto-hospedado)

npm install
npm run build        # compila TS -> dist/ e copia ícones

Instalar no nosso n8n:

• Via UI: Settings → Community Nodes → Install → n8n-nodes-tcplus (após publicar/empacotar).
• Via volume (Docker): montar o dist/ em ~/.n8n/custom/n8n-nodes-tcplus e reiniciar.
• Via npm link (dev local):

  npm link
  cd ~/.n8n/custom && npm link n8n-nodes-tcplus

Não precisa publicar no NPM — tudo roda no n8n-produto.3c.plus. Versionar o repo Git interno basta.

Status

0.1.0 — v1 com Agent/Call/Campaign/Mailing/Trigger. Não testado em runtime n8n ainda (faltam: instalar deps, npm run build, smoke test num workflow real).