n8n-nodes-hundredbug

Pacote de community node para integrar o n8n com a API do CRM 100Bug.

Este pacote foi construído a partir do comportamento observado da API e
documenta apenas formatos genéricos de endpoints. Ele não inclui
credenciais reais, tokens, e-mails, telefones, nomes de leads, nomes de
imóveis ou IDs específicos de conta.

Instalação

Siga o guia oficial do n8n para community nodes:

https://docs.n8n.io/integrations/community-nodes/installation/

Para desenvolvimento local:

npm install
npm run build

Credenciais

Crie uma credencial 100Bug API no n8n com:

• Email: seu e-mail de login do 100Bug
• Password: sua senha do 100Bug
• API Base URL: https://api.100bug.app

O node faz login via POST /session na execução e usa o JWT retornado
apenas em memória. O token não é retornado no output do node.

Recursos e operações

A UI do node está totalmente em português. Os value internos das
operações são preservados em inglês para não quebrar workflows
existentes.

Contato

• Listar (GET /contatos) — filtro de servidor apenas por nome
  (telefone / e-mail são ignorados pela API)
• Obter (GET /contatos/:id)
• Buscar Por Nome (POST /busca-contatos)
• Criar (POST /contatos)

DELETE /contatos/:id retorna 500 — endpoint não implementado.

Negociação

• Listar — A API NÃO tem endpoint global. O node itera as fases do
  funil informado (1 chamada por fase) e concatena os resultados. Use
  com cuidado para funis com muitas fases.
• Listar Por Fase (GET /negocios/:funilId/:faseId)
• Obter (GET /negocios/:id)
• Criar (POST /negocios)
• Atualizar (PUT /negocios/:id)

Campos individuais expostos em Criar/Atualizar: Nome, Valor, Status,
Funil ID, Fase ID, Contatos, Responsáveis, Imóveis Revenda, Imóveis
Lançamento, Tags, Produtos, Origem de Cliente ID, Canal de Cliente ID,
Motivo de Perda ID (update), Tipo de Marcação (update) e um campo
Campos Adicionais (JSON) para extensões.

Importante: SEMPRE preencha Responsáveis ao criar. Sem
responsáveis a API cria um registro órfão que não aceita mais PUT
(bug 404 E_ROW_NOT_FOUND).

DELETE /negocios/:id não existe. Para "excluir" use Atualizar
definindo Fase ID para a fase "Perdeu" + Motivo de Perda ID +
Tipo de Marcação = Perdido.

Nota Da Negociação

• Listar (GET /negocios/notas/:negocio_id)
• Criar Nota De Texto (POST /negocios/notas)
• Criar Nota De Imagem (POST /negocios/notas, multipart)
• Atualizar Texto (PUT /negocios/notas/:id)
• Excluir (DELETE /negocios/notas/:id)

Atividade

• Listar (GET /atividades) — Filtros locais por ID de negócio e
  status (a API ignora todos os filtros de servidor)
• Obter (GET /atividades/:id)
• Criar (POST /atividades)
• Atualizar / Vincular (PUT /atividades/:id)
• Excluir (DELETE /atividades/:id)

Criar/Atualizar expõem campos individuais: Título, Descrição, Status,
Data de Início, Data de Fim, ID do Responsável, Negócios IDs, Contatos
IDs e Campos Adicionais.

POST ignora vínculos (negocios/contatos). O node faz um PUT
automático em seguida quando esses campos são informados na criação.
GET por ID não traz vínculos — use Listar para verificar.

Arquivo Da Negociação

• Listar (GET /negocios/:id/arquivos)
• Enviar Arquivo (POST /negocios/:id/arquivos, multipart)
• Excluir (DELETE /negocios/:id/arquivos/:fileId)

O upload lê uma propriedade binária do item de entrada (default data).

Imóvel

• Listar Lançamentos (GET /imoveis-lancamento) — filtros
  individuais validados: Nome, ID do Incorporador, Tipo, Status, Preço
  Mínimo/Máximo, Quartos Mínimo/Máximo, Área Mínima/Máxima, Região,
  Busca de Endereço, Cidade, Áreas/Bairros (JSON array), Datas de
  Abertura e de Lançamento.
• Obter Lançamento (GET /imoveis-lancamento/:id)
• Autocompletar Lançamento (GET /imoveis-lancamento/autocomplete)
• Listar Revenda / Aluguel (GET /imoveis-revenda) — Tipo de
  Transação (Aluguel/Revenda), Tipo, Finalidade, Cidade, Nome, Preço
  Mín/Máx, Quartos Mín/Máx, Área Mín/Máx, Bairro.
• Obter Revenda / Aluguel (GET /imoveis-revenda/:id)
• Autocompletar Revenda / Aluguel (GET /imoveis-revenda/autocomplete)
• Listar Bairros / Áreas (GET /imoveis-endereco-areas)
• Listar Incorporadores (GET /imoveis-incorporador)

Funil

• Listar (GET /funis)
• Obter (GET /funis/:id)
• Listar Motivos De Perda (GET /motivos-perda-funis/:funilId)

Catálogo

• Usuário Atual / Preferências do Usuário
• Canais de Cliente / Origens de Cliente / Etiquetas
• Painel / Saúde da API / Notificações / Notificações Não Lidas
• Categorias de Campos Personalizados / Campos Personalizados
• Integrações de Portais / Assinatura de Cobrança

Requisição Customizada

Para endpoints recém descobertos. O node continua tratando login e
Authorization automaticamente. Forneça:

• Método
• Caminho começando com /
• Parâmetros de Query (JSON)
• Body (JSON) para POST/PUT/PATCH

Observações de segurança

• Não armazene credenciais em JSON de workflow, documentação, mensagens
  de commit ou parâmetros do node. Use apenas as credenciais do n8n.
• O node redige tokens Bearer das mensagens de erro capturadas antes de
  retornar via continueOnFail.
• O README intencionalmente usa IDs e exemplos genéricos.

Quirks conhecidos da API 100Bug

• POST /session retorna status 201 e o token em token.token.
• POST /negocios exige apenas funis_id e fases_id; todos os outros
  campos são opcionais. Sempre envie responsaveis para evitar criar
  registros órfãos.
• POST /negocios aceita silenciosamente previsao_fechamento,
  data_fechamento, motivo_perda_id, origem_lead mas não os
  persiste.
• imoveisLancamento e tags funcionam tanto em POST quanto em
  PUT /negocios.
• Arrays de vínculo precisam ser array<number>. Enviar
  [{ id: 123 }] causa 500 com vazamento de stack trace.
• Filtro ?negocios_id= em /atividades é ignorado pela API. Use o
  filtro local "ID do Negócio" do node.
• POST /atividades ignora negocios/contatos. O node faz o PUT de
  vínculo automaticamente quando esses campos estão preenchidos.
• GET /atividades/:id NÃO inclui negocios/contatos vinculados.
  Use Listar para inspecionar vínculos.
• POST /negocios/notas exige negocio_id (singular). Não envie
  negocios_id.
• DELETE /negocios/notas/:id retorna 200 com mensagem (em vez de 204).
• DELETE /negocios/:id retorna 404 (endpoint não existe). Para
  "excluir" use PUT para a fase "Perdeu" com motivo_perda_id e
  tipo_marcacao: "perdido".
• DELETE /contatos/:id retorna 500 (endpoint não existe).

Compatibilidade

Construído com o n8n node starter usando @n8n/node-cli.

Licença

MIT