> ## Documentation Index
> Fetch the complete documentation index at: https://developers.gyramais.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Integração com n8n
> Automatize análises de crédito com n8n, workflows prontos para importar e conectar seu ERP, CRM, Google Sheets e e-mail.
O n8n é uma plataforma de automação de workflows que permite integrar a GYRA+ com qualquer sistema sem escrever código. Use os templates abaixo para acelerar sua integração.
Os templates foram desenhados para uso real. Basta importar, preencher suas credenciais no nó **⚙️ CONFIGURE AQUI** e ativar, sem variáveis de ambiente, sem configuração de servidor.
***
## Arquitetura recomendada
A integração GYRA+ com n8n segue um padrão simples de dois momentos:
```
Seu Sistema → [Workflow 1] → GYRA+ API (solicita análise)
GYRA+ API → [Workflow 2 ou 3] → Seu Sistema (recebe decisão)
```
O Workflow 1 é **síncrono**: seu sistema chama e recebe o `reportId` imediatamente. Os Workflows 2 e 3 são **assíncronos**: a GYRA+ envia a decisão via webhook quando o processamento terminar (geralmente 60–180 segundos para COMPLETO, até 5 min para COMPLETO+).
***
## Templates disponíveis
Recebe uma chamada do seu ERP/CRM e cria o relatório na GYRA+. Retorna o `reportId` imediatamente.
⬇️ Baixar JSON
Recebe a decisão via webhook e atualiza o CRM com base em APPROVED / ALERT / DENIED. Notifica a equipe.
⬇️ Baixar JSON
Recebe a decisão, busca o relatório completo e registra na planilha + envia e-mail formatado ao analista.
⬇️ Baixar JSON
Clique em **⬇️ Baixar JSON** no card correspondente. O arquivo será salvo no seu computador. Em seguida, importe no n8n em **Workflows → Import from file**.
***
## Como importar os templates
Clique no link de download do workflow desejado nos cards acima.
Links diretos caso os cards não funcionem no seu navegador:
* gyra-1-solicitar-analise.json
* gyra-2-decisao-rotear-crm.json
* gyra-3-decisao-sheets-email.json
No seu n8n, clique em **Workflows → Import from file** e selecione o arquivo `.json` baixado.
Abra o workflow importado e localize o nó laranja **⚙️ CONFIGURE AQUI**. Preencha os campos com suas credenciais. Cada campo tem uma instrução clara de onde encontrar o valor.
Para o Workflow 3, configure também as credenciais do Google Sheets e SMTP em **Settings → Credentials** no n8n. Os nós correspondentes mostrarão um aviso enquanto as credenciais não estiverem vinculadas.
Copie a URL **Production URL** do webhook gerada pelo n8n e registre na GYRA+ (veja [Configurar Webhook](/guides/configurar-webhook)).
Clique no toggle **Active** no canto superior direito. Pronto.
***
## Workflow 1, Solicitar Análise de Crédito
**Arquivo:** `gyra-1-solicitar-analise.json`
Este workflow expõe um endpoint HTTP que o seu ERP ou CRM pode chamar para solicitar uma análise de crédito. Ideal para integrar o botão "Analisar Cliente" do seu sistema diretamente com a GYRA+.
### Fluxo
```
POST /webhook/gyra-solicitar-analise (seu n8n)
→ ⚙️ CONFIGURE AQUI (credenciais)
→ 🔐 Autenticar na GYRA+ (POST /auth/authenticate)
→ 📄 Criar Relatório (POST /v2/report)
→ ✅ Retornar { reportId, status: "PENDING" } ao chamador
```
### Payload de entrada
```json theme={null}
{
"document": "43591367000130",
"type": "CNPJ",
"reportType": "COMPLETO",
"externalId": "NEGOCIO-2024-001"
}
```
| Campo | Obrigatório | Descrição |
| ------------ | ----------- | ---------------------------------------------------------------- |
| `document` | ✅ | CNPJ (14 dígitos) ou CPF (11 dígitos), sem formatação |
| `type` | ✅ | `CNPJ` ou `CPF` |
| `reportType` | ❌ | Usa o padrão configurado no nó ⚙️ se não informado |
| `externalId` | ❌ | ID do registro no seu sistema, devolvido no webhook de resultado |
| `policyId` | ❌ | Sobrescreve a política padrão configurada |
### Resposta (HTTP 202)
```json theme={null}
{
"success": true,
"reportId": "64f1a2b3c4d5e6f7a8b9c0d1",
"document": "43591367000130",
"status": "PENDING",
"message": "Análise de crédito solicitada com sucesso. Você receberá a decisão via webhook quando o relatório for processado.",
"estimatedTimeSeconds": 90
}
```
### O que configurar no nó ⚙️ CONFIGURE AQUI
| Campo | Descrição | Onde encontrar |
| -------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `clientId` | Client ID da GYRA+ | Solicite por e-mail em `atendimento@gyramais.com` |
| `clientSecret` | Client Secret da GYRA+ | Solicite por e-mail em `atendimento@gyramais.com` |
| `policyId` | ID da sua política ativa | Toolbox → Políticas de Crédito → \[sua política] → Copiar ID, ou `GET /credit-policy/policy` |
| `reportType` | Tipo padrão de relatório (definido pela política) | A política já carrega o nível; este campo é informativo |
| `apiBaseUrl` | URL base da API | `https://gyra-core.gyramais.com.br` (não altere) |
***
## Workflow 2, Receber Decisão e Rotear para CRM
**Arquivo:** `gyra-2-decisao-rotear-crm.json`
Este workflow recebe o webhook da GYRA+ quando um relatório é concluído, extrai a decisão e atualiza o CRM automaticamente em 3 caminhos: APROVADO, EM ANÁLISE ou REPROVADO.
### Fluxo
```
POST /webhook/gyra-decisao (GYRA+ → seu n8n)
→ ⚙️ CONFIGURE AQUI
→ 📊 Extrair policyStatus + score + externalId
→ 🔀 Switch por policyStatus
├── APPROVED → ✅ Atualizar CRM + 🔔 Notificar vendedor
├── ALERT → ⚠️ Atualizar CRM + 🔔 Notificar analista
└── DENIED → ❌ Atualizar CRM + 🔔 Notificar equipe
```
### Payload recebido da GYRA+
```json theme={null}
{
"reportId": "64f1a2b3c4d5e6f7a8b9c0d1",
"document": "43591367000130",
"type": "CNPJ",
"status": "COMPLETED",
"policyStatus": "APPROVED",
"score": 720,
"externalId": "NEGOCIO-2024-001"
}
```
### O que configurar no nó ⚙️ CONFIGURE AQUI
| Campo | Descrição | Exemplo |
| ------------------------ | --------------------------- | ------------------------------- |
| `crmWebhookUrl` | URL do webhook do seu CRM | `https://app.pipedrive.com/...` |
| `crmApiKey` | API Key do seu CRM | `abc123xyz` |
| `notificationWebhookUrl` | Slack, Teams ou outro canal | `https://hooks.slack.com/...` |
### Payload enviado ao CRM (branch APPROVED)
Adapte o `jsonBody` nos nós de HTTP conforme o contrato da API do seu CRM:
```json theme={null}
{
"externalId": "NEGOCIO-2024-001",
"document": "43591367000130",
"reportId": "64f1a2b3c4d5e6f7a8b9c0d1",
"creditStatus": "APROVADO",
"score": 720,
"action": "MOVE_TO_PROPOSAL",
"notes": "Análise GYRA+ aprovada automaticamente. Score: 720/1000"
}
```
Substitua `crmWebhookUrl` por `https://api.hubapi.com/crm/v3/objects/deals/{dealId}` e adicione o header `Authorization: Bearer {seu_token_hubspot}`. Use o campo `externalId` para identificar o deal. Mapeie `creditStatus` para uma propriedade personalizada do deal.
Use `https://api.pipedrive.com/v1/deals/{dealId}?api_token={seu_token}`. Mapeie `creditStatus` para um campo personalizado de status de crédito. Use `externalId` como o `{dealId}`.
Envie para `https://crm.rdstation.com/api/v1/deals/{id}` com header `Authorization: Bearer {token}`. Atualize o estágio do funil com base no `creditStatus`.
O campo `notificationWebhookUrl` aceita diretamente o Incoming Webhook do Slack. Crie em **Slack → Apps → Incoming Webhooks** e cole a URL no nó ⚙️ CONFIGURE AQUI. A mensagem já está formatada com emoji, score e link para o relatório.
***
## Workflow 3, Receber Decisão, Registrar em Sheets e Enviar E-mail
**Arquivo:** `gyra-3-decisao-sheets-email.json`
Perfeito para equipes financeiras e cooperativas que precisam de registro histórico auditável e notificação por e-mail para o analista de crédito. Este workflow busca o relatório completo para extrair dados enriquecidos além do que o webhook já traz.
### Fluxo
```
POST /webhook/gyra-decisao-sheets (GYRA+ → seu n8n)
→ ⚙️ CONFIGURE AQUI
→ 🔐 Autenticar na GYRA+
→ 📑 Buscar Relatório Completo (GET /v2/report/:id)
→ 📊 Extrair Campos (razão social, situação cadastral, processos; PEFIN/protestos só se a política estiver no nível COMPLETO ou superior)
→ 📊 Registrar nova linha no Google Sheets
→ 📧 Enviar E-mail HTML ao analista
```
### Colunas criadas na planilha
| Coluna | Conteúdo |
| ------------------ | ------------------------------------------ |
| Data | Data da análise |
| Documento | CNPJ ou CPF |
| Razão Social | Nome da empresa ou pessoa |
| Tipo | CNPJ / CPF |
| Score | Score 0–1000 |
| Decisão | APPROVED / ALERT / DENIED |
| PEFIN (R\$) | Total de pendências PEFIN |
| Protestos | Quantidade de protestos em cartório |
| Processos Passivos | Quantidade de processos judiciais passivos |
| Situação Cadastral | Ativa / Inapta / Baixada / Suspensa |
| Report ID | ID do relatório GYRA+ |
| Link Toolbox | Link direto para o relatório completo |
### O que configurar no nó ⚙️ CONFIGURE AQUI
| Campo | Descrição | Onde encontrar |
| ---------------- | ------------------------------------ | ------------------------------------------------- |
| `clientId` | Client ID da GYRA+ | Solicite por e-mail em `atendimento@gyramais.com` |
| `clientSecret` | Client Secret da GYRA+ | Solicite por e-mail em `atendimento@gyramais.com` |
| `emailDestino` | E-mail do analista de crédito | , |
| `emailRemetente` | E-mail remetente configurado no SMTP | , |
| `planilhaId` | ID da planilha Google Sheets | URL: `docs.google.com/spreadsheets/d/**ID**/edit` |
| `abaName` | Nome da aba | Ex: `Análises de Crédito` |
### Configurar credenciais Google Sheets e SMTP
Em **Settings → Credentials → Add Credential → Google Sheets OAuth2 API**. Conecte com a conta Google que tem acesso de edição à planilha. Compartilhe a planilha com o e-mail da conta de serviço se usar Service Account.
Em **Settings → Credentials → Add Credential → SMTP**. Configure com os dados do seu servidor. Para Gmail, use um **App Password** (não a senha normal da conta).
Nos nós **📊 Registrar na Planilha** e **📧 Enviar E-mail**, clique em **Credential for...** e selecione as credenciais recém-criadas.
***
## Registrar o URL do webhook na GYRA+
Para que a GYRA+ envie os resultados para os Workflows 2 ou 3, registre a URL gerada pelo n8n:
```bash theme={null}
curl -X POST https://gyra-core.gyramais.com.br/webhook \
-H "Authorization: Bearer {seu_access_token}" \
-H "Content-Type: application/json" \
-d '{
"url": "https://seu-n8n.com/webhook/gyra-decisao"
}'
```
Use sempre a **Production URL** do webhook do n8n em produção. A Test URL só funciona quando o workflow está aberto no editor em modo de teste.
Você pode registrar **múltiplos webhooks** na GYRA+ e usar os Workflows 2 e 3 simultaneamente para ter integração CRM e registro em planilha ao mesmo tempo.
***
## Casos de uso por segmento
**Objetivo:** Automatizar a concessão de prazo para novos clientes durante a abertura de conta.
**Setup recomendado:**
* Workflow 1 → acionado quando vendedor marca lead como "Em Análise de Crédito" no CRM
* Workflow 2 → `APPROVED` move para "Proposta Enviada" com limite de crédito; `DENIED` arquiva por 90 dias; `ALERT` atribui ao gerente comercial
* Use o `externalId` com o ID do negócio no CRM para correlacionar automaticamente
**Relatório sugerido:** `COMPLETO` com política de prazo de pagamento
**Objetivo:** Decisão automática de crédito para PF e PJ com rastreabilidade total.
**Setup recomendado:**
* Workflow 1 → acionado pela jornada de crédito digital (app/site)
* Workflow 3 → registro em Sheets para compliance + e-mail para comitê de crédito em casos `ALERT`
* Workflow 2 → `APPROVED` dispara oferta de crédito automaticamente; `DENIED` envia carta de negativa
**Relatório sugerido:** `COMPLETO+` para PJ (inclui certidões); `COMPLETO` para PF
**Objetivo:** Validar automaticamente novos parceiros, fornecedores ou clientes no onboarding.
**Setup recomendado:**
* Workflow 1 → acionado ao submeter formulário de cadastro
* Workflow 3 → registra tudo em Sheets para auditoria LGPD + notifica compliance por e-mail
* Para sanções e PEP (OFAC, CEIS, CEPIM): use `COMPLETO+` com política de Background Check
**Relatório sugerido:** `COMPLETO+` (cobre sanções internacionais e certidões em tempo real)
***
## Suporte à integração
Precisa de ajuda para adaptar os templates ao seu sistema?
* **Documentação da API:** [Referência de Endpoints](/reference/endpoints)
* **Guia de Webhooks:** [Configurar Webhook](/guides/configurar-webhook)
* **Interpretar Decisões:** [Interpretar a Decisão](/guides/interpretar-decisao)
* **Suporte:** [atendimento@gyramais.com.br](mailto:atendimento@gyramais.com.br)