vixdados

Node do n8n para a API pública do VixDados: consulta de CNPJ com histórico (sócios, capital, alterações mês a mês), busca de CNPJs por endereço e saldo da conta. Dados oficiais da Receita Federal.

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.1.0
Author: VixDados

Documentation

@vixnegocios/n8n-nodes-vixdados

Node do n8n para a API pública do VixDados: consulta de CNPJ com histórico (sócios, capital social, razão social, endereço e situação, mês a mês), busca de todos os CNPJs de um endereço e saldo da conta. Dados oficiais da Receita Federal.

Site: https://vixdados.com.br · Documentação da API: https://vixdados.com.br/api-docs.html

Instalação

n8n próprio (self-hosted): Configurações → Community Nodes → Install → informe @vixnegocios/n8n-nodes-vixdados. Precisa da variável N8N_COMMUNITY_PACKAGES_ENABLED=true (padrão) na instância.

Ou pela linha de comando, na pasta do n8n:

npm install @vixnegocios/n8n-nodes-vixdados

e reinicie o n8n.

n8n Cloud: só aceita community nodes verificados pelo n8n. Enquanto este pacote não for verificado, use o node HTTP Request com uma credencial Header Auth (X-API-Key).

Credencial

Crie uma credencial VixDados API com a chave gerada no portal, em Minha conta → Chaves de API (começa com vxd_ e é mostrada uma única vez). O botão Test chama GET /v1/public/conta, que não consome créditos.

A API Key está nos planos Profissional e Empresarial.

Operações

Recurso Operação Endpoint Custo
Empresa (CNPJ) Consultar CNPJ GET /v1/public/cnpj/{cnpj} 1, 3 ou 5 créditos conforme o nível. Consultar de novo o mesmo CNPJ em 30 dias não custa; subir de nível cobra só a diferença
Endereço Listar CNPJs do endereço GET /v1/public/endereco Preço do nível × CNPJs devolvidos. O campo Limite de CNPJs (1 a 500) controla o gasto. Nenhum CNPJ (404) ou saldo insuficiente (402) não cobram
Conta Saldo e limites GET /v1/public/conta Grátis

Níveis

Nível Custo Conteúdo
Simples 1 CNPJ, razão social; estabelecimentos com nome fantasia, situação e motivo, data de abertura, endereço completo e município
Intermediária 3 + porte, capital social, natureza jurídica e responsável, CNAE principal e secundários, telefones e e-mail, Simples Nacional/MEI, até 20 concorrentes, score
Auditoria 5 + quadro de sócios (QSA), linha do tempo das alterações (parâmetro Histórico desde), endereço inteligente (até 50 empresas no mesmo CEP + número)

Saída da busca por endereço

  • Uma empresa por item (padrão): cada CNPJ vira um item do n8n, pronto para o próximo node.
  • Resposta completa em um item: inclui total_encontrado, total_retornado, parcial, creditos_consumidos e creditos_restantes.

Limites

100 requisições por minuto por chave; 500 por hora no Profissional e 2.000 por hora no Empresarial. Acima disso a API responde 429.

Erros

A API responde JSON com error e message. 401 chave inválida; 402 créditos insuficientes; 404 CNPJ não encontrado ou nenhum CNPJ no endereço (não cobra); 429 limite de requisições.

Desenvolvimento

npm install
npm run build        # compila para dist/ e copia o ícone
npm run typecheck

Para testar numa instância local do n8n, aponte N8N_CUSTOM_EXTENSIONS para esta pasta (depois do build) ou instale o .tgz gerado por npm pack.

Publicação (mantenedores)

O pacote é da organização vixnegocios no npm. O package.json já traz "publishConfig": { "access": "public" }, então basta:

npm login
npm run build
npm publish

Pacote com escopo nasce privado no npm; o publishConfig garante que ele saia público (pacote privado exige plano pago).

Licença

MIT.

Discussion