🚀 n8n Trustic API Node

Um node customizado do n8n para integração com a API Trustic, focado em análises de compliance e antifraude. Desenvolvido pela CORLABS seguindo as melhores práticas do ecossistema n8n.

📋 Índice

• Sobre
• Funcionalidades
• Instalação
• Configuração
• Uso
• Operações Disponíveis
• Exemplos
• Desenvolvimento
• Contribuição
• Suporte

🎯 Sobre

A Trustic é uma plataforma brasileira de análises de compliance e antifraude que oferece diversos serviços como:

• Consultas de CPF e CNPJ
• Análises de crédito
• Verificação de documentos
• Reconhecimento facial
• E muito mais...

Este node permite integrar facilmente esses serviços em seus workflows do n8n.

✨ Funcionalidades

🔐 Autenticação Flexível

• ✅ Email e Senha: Login automático com cache de token
• ✅ API Key: Usar chave diretamente como Bearer Token
• ✅ Ambientes: Suporte a Sandbox e Produção

🛡️ Validações Robustas

• ✅ Validação de CPF: Incluindo dígitos verificadores
• ✅ Limpeza Automática: Remove caracteres especiais
• ✅ Tratamento de Erros: Mensagens claras e acionáveis

⚡ Performance

• ✅ Cache de Token: Evita logins desnecessários
• ✅ Compatível com LLMs: Suporte a agentes AI (usableAsTool: true)
• ✅ TypeScript: Tipos completos para melhor DX

🚀 Instalação

Via NPM (Recomendado)

# Instalar globalmente
npm install -g @corlabs-holding/n8n-nodes-trustic

# Ou no diretório custom do n8n
cd ~/.n8n/custom
npm install @corlabs-holding/n8n-nodes-trustic

Via n8n Community Nodes

1. Acesse Settings → Community Nodes no seu n8n
2. Digite: @corlabs-holding/n8n-nodes-trustic
3. Clique em Install

Para Desenvolvimento

git clone https://github.com/corlabs-holding/n8n-nodes-trustic.git
cd n8n-nodes-trustic
npm install
npm run build
npm link

⚙️ Configuração

1. Criar Credenciais

1. No n8n, vá em Credentials → Create New
2. Procure por "Trustic API"
3. Configure os campos:

🔧 Configuração por Email/Senha

Ambiente: Sandbox (para testes) ou Produção
Tipo de Autenticação: Email e Senha
Email: [email protected]
Senha: sua-senha-trustic

🔧 Configuração por API Key

Ambiente: Sandbox (para testes) ou Produção  
Tipo de Autenticação: API Key
API Key: sua-chave-da-trustic

2. URLs Automáticas

O node configura automaticamente as URLs baseadas no ambiente:

• Sandbox: https://sandbox.api.trustic.com.br/antifraud
• Produção: https://api.trustic.com.br/antifraud

🎮 Uso

Passo a Passo Básico

1. Adicione o Node: Procure por "Trustic API" na paleta
2. Selecione Credenciais: Escolha as credenciais configuradas
3. Configure Operação: Selecione "Consulta Básica de Pessoa Física"
4. Informe CPF: Digite o CPF (com ou sem formatação)
5. Execute: O node fará a consulta automaticamente

📊 Fluxo de Dados

graph LR
    A[Input: CPF] --> B[Validação]
    B --> C[Login/Token]
    C --> D[API Trustic]
    D --> E[Dados PF]
    E --> F[Output n8n]

🔍 Operações Disponíveis

👤 Consulta Básica de Pessoa Física

Endpoint: GET /v1/compliance/pf/{cpf}/basic-info

Input:

• CPF: 11 dígitos (formatação automática)

Output:

• Dados básicos da pessoa física
• Informações de compliance
• Status da consulta

Exemplo de Input:

{
  "cpf": "123.456.789-00"
}

Exemplo de Output:

{
  "nome": "João Silva",
  "cpf": "12345678900",
  "status": "regular",
  "dados_basicos": {
    // ... dados retornados pela Trustic
  }
}

💡 Exemplos

Exemplo 1: Workflow Simples

# Trigger: Webhook
# Input: { "cpf": "123.456.789-00" }
↓
# Node: Trustic API
# Operation: Consulta Básica PF
# CPF: {{$json.cpf}}
↓  
# Output: Dados da pessoa física

Exemplo 2: Com Validação

# Trigger: Form/Manual
↓
# Node: Set (validar se CPF está presente)
↓
# Node: Trustic API (consulta)
↓
# Node: IF (verificar se pessoa existe)
↓
# Node: Slack/Email (notificar resultado)

Exemplo 3: Integração com AI Agent

// O node é compatível com LLMs/Agents
const result = await n8n.invoke("trustic-api", {
  operation: "pfBasicInfo",
  cpf: "12345678900"
});

🛠 Desenvolvimento

Pré-requisitos

• Node.js 18+
• npm ou pnpm
• TypeScript
• n8n (para testes)

Setup Local

# Clone o repositório
git clone https://github.com/corlabs-holding/n8n-nodes-trustic.git
cd n8n-nodes-trustic

# Instalar dependências
npm install

# Desenvolvimento (watch mode)
npm run dev

# Build
npm run build

# Linting
npm run lint:fix

# Formatação
npm run format

Estrutura do Projeto

n8n-nodes-trustic/
├── credentials/                        # Definições de credenciais
│   └── GenericApiCredentialsApi.credentials.ts
├── nodes/                             # Implementação do node
│   └── GenericApi/
│       ├── TrusticApi.node.ts         # Node principal
│       ├── GenericApiHelpers.ts       # Funções auxiliares
│       └── icon.svg                   # Ícone do node
├── dist/                              # Build output
├── package.json                       # Configuração do projeto
├── tsconfig.json                      # Config TypeScript
├── todo.md                           # Planejamento detalhado
└── README.md                         # Esta documentação

Scripts Disponíveis

npm run dev         # Watch mode para desenvolvimento
npm run build       # Build para produção  
npm run lint        # Verificar código
npm run lint:fix    # Corrigir automaticamente
npm run format      # Formatar código
npm run prepublishOnly  # Build + Lint (antes de publicar)

🤝 Contribuição

Contribuições são muito bem-vindas!

Como Contribuir

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/MinhaFeature)
3. Commit suas mudanças (git commit -m 'feat: Adiciona MinhaFeature')
4. Push para a branch (git push origin feature/MinhaFeature)
5. Abra um Pull Request

Padrões de Commit

Seguimos Conventional Commits:

• feat: Nova funcionalidade
• fix: Correção de bug
• docs: Mudanças na documentação
• style: Formatação de código
• refactor: Refatoração de código
• test: Adição de testes
• chore: Manutenção geral

Roadmap

Próximas funcionalidades planejadas:

🚀 v1.1 - Mais Operações PF

• [ ] Pesquisa Federal
• [ ] Renda Estimada
• [ ] Histórico Profissional
• [ ] Consulta de Dívidas

🚀 v1.2 - Pessoa Jurídica

• [ ] Consulta Básica PJ
• [ ] Receita Federal
• [ ] Histórico de Alterações

🚀 v2.0 - Recursos Avançados

• [ ] Reconhecimento Facial
• [ ] Análise de Documentos
• [ ] Webhooks
• [ ] Operações em Lote

📞 Suporte

🐛 Reportar Bugs

Se encontrar um bug, por favor abra uma issue.

💡 Solicitar Features

Para solicitar novas funcionalidades, abra uma issue de feature request.

💬 Comunidade

• GitHub Discussions: Discussões do projeto
• n8n Community: Forum oficial n8n
• CORLABS: Site oficial

📚 Documentação Adicional

• Trustic API: docs.trustic.com.br
• n8n Docs: docs.n8n.io
• Desenvolvimento de Nodes: Creating Nodes

📄 Licença

Este projeto está licenciado sob a MIT License - veja o arquivo LICENSE para detalhes.

🏢 Sobre a CORLABS

A CORLABS é uma empresa especializada em automação e integrações, focada em soluções no-code/low-code. Desenvolvemos ferramentas e integrações para otimizar processos empresariais.

• Website: corlabs.dev
• GitHub: @corlabs
• Email: [email protected]

⭐ Se este projeto foi útil, deixe uma estrela no GitHub!

Desenvolvido com ❤️ pela equipe CORLABS