> For the complete documentation index, see [llms.txt](https://ajuda.digitalsac.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.digitalsac.io/digicrm/configuracao/modulo-n8n-automacao.md).

# 🔄 Módulo N8N (Automação)

Integração oficial do DigiCrm Digitalsac com o [n8n](https://n8n.io): um **Community Node verificado** que executa ações da plataforma (mensagens, tickets, agenda, WABA e mais) sem montar chamadas HTTP manualmente.

| Item               | Valor                                                                                                  |
| ------------------ | ------------------------------------------------------------------------------------------------------ |
| Nome no n8n        | **DigiCrm Digitalsac**                                                                                 |
| Pacote npm         | [`n8n-nodes-digitalsac`](https://www.npmjs.com/package/n8n-nodes-digitalsac)                           |
| Versão documentada | **1.2.3+** (rebrand DigiCrm; workflows antigos continuam válidos)                                      |
| Repositório        | [github.com/digitalsac-io/n8n-nodes-digitalsac](https://github.com/digitalsac-io/n8n-nodes-digitalsac) |
| Credencial no n8n  | **Digitalsac DigiCrm API**                                                                             |

{% hint style="info" %}
Se a sua instância n8n ainda mostrar o nome antigo **Digitalsac Izing Pro**, atualize o Community Node para a versão **1.2.3** ou superior. O pacote e o tipo de credencial (`digitalsacApi`) são os mesmos.
{% endhint %}

### Como o n8n se conecta ao Digitalsac

O node não inventa uma API paralela: ele chama as rotas já expostas pelo backend Digitalsac, autenticadas com o token Bearer da **API externa** do tenant.

```
Evento no n8n (webhook, cron, CRM, planilha…)
        ↓
Node DigiCrm Digitalsac (operação escolhida)
        ↓
HTTP + Authorization: Bearer <token da API>
        ↓
Digitalsac backend
  ├─ /v1/api/external/:apiId/...   → envio de mensagens e distribuição
  └─ /typebot/...                  → tickets, tags, kanban, agenda, WABA, SMS, validações
        ↓
Resposta JSON volta ao fluxo n8n
```

#### Duas famílias de endpoints

| Família                 | Prefixo                   | Uso típico no node                                                                                                                       |
| ----------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **API externa**         | `/v1/api/external/:apiId` | Enviar texto/mídia, botões, lista, carrossel; próximo atendente / transferir para o próximo                                              |
| **Typebot / automação** | `/typebot/...`            | Filas, atendentes, fechar/transferir ticket, tags, carteiras, kanban, agendamentos, mensagens agendadas, templates WABA, SMS, validações |

Para operações de **mensagem** e **próximo responsável**, o campo **Parameter** do node deve receber o **UUID da configuração de API** (`apiId`) criada em **Configurações → API** no Digitalsac. Esse UUID identifica a conexão WhatsApp (sessão) vinculada àquela API.

### Pré-requisitos no Digitalsac

1. Tenant com canal WhatsApp (ou WABA) ativo, conforme o tipo de envio.
2. Em **Configurações → API**, criar uma integração apontando para a sessão/conexão desejada.
3. Copiar:
   * **URL base** da instância (ex.: `https://suaempresa.digitalsac.com.br`) — sem `/` no final;
   * **Token Bearer** gerado pela API;
   * **UUID da API** (id da configuração) — necessário nas operações de envio via `/v1/api/external/...`.
4. Opcional: consultar a documentação interativa em **Configurações → API Typebot** (`/configuracoes/typebotapi`) para ver os endpoints `/typebot` disponíveis no ambiente.

{% hint style="warning" %}
O token é sensível. Não publique em prints, vídeos ou repositórios. Renove em Configurações → API se houver vazamento.
{% endhint %}

### Instalação no n8n

#### Pelo painel (recomendado)

1. Abra **Settings → Community Nodes**.
2. Busque por `n8n-nodes-digitalsac` ou **DigiCrm Digitalsac**.
3. Instale e reinicie o n8n se a instância pedir.

#### Via CLI (self-hosted)

```bash
cd ~/.n8n
npm install n8n-nodes-digitalsac
```

Ou, globalmente:

```bash
npm install -g n8n-nodes-digitalsac
```

O node está publicado como pacote de Community Node compatível com o processo de verificação do n8n (UI em inglês, autenticação via helper oficial, ícones e provenance no npm).

### Credenciais

No n8n, crie uma credencial **Digitalsac DigiCrm API**:

| Campo            | Descrição                                        |
| ---------------- | ------------------------------------------------ |
| **API Base URL** | URL da sua instância Digitalsac, sem barra final |
| **Bearer Token** | Token da API criada em Configurações → API       |

O node envia automaticamente `Authorization: Bearer <token>` e `Accept: application/json`. O teste de credencial chama `GET /typebot/listar_filas`.

### Operações disponíveis

Nomes abaixo são os que aparecem no seletor **Operation** do node (interface em inglês).

#### Validação

| Operação          | Função                                   |
| ----------------- | ---------------------------------------- |
| Validate WhatsApp | Verifica se o número tem WhatsApp        |
| Validate CPF      | Valida CPF                               |
| Validate Date     | Valida data (`{ "data": "YYYY-MM-DD" }`) |

#### Filas, atendentes e tickets

| Operação                  | Função                                                       |
| ------------------------- | ------------------------------------------------------------ |
| List Queues               | Lista filas do tenant                                        |
| List Agents               | Lista atendentes (JSON completo ou texto de compatibilidade) |
| Transfer to Queue         | Transfere ticket para fila                                   |
| Transfer to Agent         | Transfere ticket para usuário                                |
| Close Ticket              | Fecha ticket                                                 |
| Next Assignee in Queue    | Consulta próximo responsável da fila                         |
| Transfer to Next Assignee | Transfere para o próximo responsável                         |

Exemplos de body (JSON):

```json
{ "ticketId": 123, "queueId": 5 }
```

```json
{ "ticketId": 123, "userId": 10 }
```

```json
{ "ticketId": 123 }
```

Para **Next Assignee** / **Transfer to Next Assignee**, preencha **Parameter** com o UUID da API e o body, por exemplo:

```json
{ "queueId": 3, "ticketId": 1201, "method": "S", "allowOffline": false }
```

#### Mensagens (API externa)

| Operação                | Função                                                    |
| ----------------------- | --------------------------------------------------------- |
| Send Message            | Texto e/ou arquivo (binário do n8n vira upload multipart) |
| Send Buttons            | Botões interativos (quick reply, URL, copy, call)         |
| Send List               | Lista com seções                                          |
| Send Carousel           | Carrossel de cards                                        |
| Send Media With Caption | Mídia com legenda (binário)                               |
| Send Base64 File        | Arquivo em base64 + MIME + nome                           |

Campos comuns: **Parameter** = UUID da API; telefone com DDI (ex.: `5511999999999`); **External Key** para correlacionar o envio no seu sistema.

#### Tags, carteiras e Kanban

| Operação                          | Função                                                                                 |
| --------------------------------- | -------------------------------------------------------------------------------------- |
| List Tags / Create Tag / Link Tag | Listar, criar e vincular tag ao ticket                                                 |
| List Wallets / Link Wallet        | Listar e vincular carteira                                                             |
| List Kanbans / Link Kanban        | Listar (por `userId`) e vincular ao ticket (payload v2 com valor, probabilidade, etc.) |

#### Agendamentos

| Operação                      | Função                                                          |
| ----------------------------- | --------------------------------------------------------------- |
| List Services                 | Serviços de agenda                                              |
| List Available Users          | Usuários disponíveis para serviço + data                        |
| List Available Slots          | Horários livres                                                 |
| List Schedules                | Agendamentos do dia                                             |
| Create Schedule               | Cria agendamento (pode criar contato e fechar ticket de origem) |
| Cancel Schedule               | Cancela por `scheduleId`                                        |
| Generate Calendar Link (.ics) | Link `.ics` para o cliente                                      |

#### Mensagens agendadas (Typebot)

| Operação                          | Função                                        |
| --------------------------------- | --------------------------------------------- |
| List Scheduled Messages (Typebot) | Lista envios agendados (filtros opcionais)    |
| Schedule Message (Typebot)        | Agenda mensagem (`/typebot/agendar_mensagem`) |
| Cancel Scheduled Message          | Cancela pelo `messageId`                      |

Exemplo de agendamento:

```json
{
  "number": "5511999999999",
  "name": "João",
  "body": "Olá João, lembrete do seu atendimento.",
  "date": "29/05/2026",
  "time": "10:00"
}
```

`timezone` é opcional; se omitido, usa o fuso do tenant.

#### WABA e SMS

| Operação            | Função                                                                   |
| ------------------- | ------------------------------------------------------------------------ |
| List WABA Templates | Templates da conexão WABA (`whatsappId`)                                 |
| Send WABA Template  | Envio com variáveis de body, header (texto/mídia) e botões URL dinâmicos |
| Send Short SMS      | SMS curto via `/typebot/enviar_sms`                                      |

**Send WABA Template** aceita, entre outros: `templateId`, `whatsappId`, telefone, `templateParams`, `mediaUrl`, `headerParams`, `buttonParams`. Campos opcionais vazios usam o padrão do template salvo no Digitalsac.

### Exemplos de fluxo

#### Novo lead → mensagem WhatsApp

1. Trigger (formulário / webhook).
2. **Validate WhatsApp**.
3. **Send Message** (UUID da API + telefone + texto).

#### Pedido aprovado → template WABA

1. Webhook do e-commerce.
2. **Send WABA Template** com `templateParams` (nome, pedido, total) e, se precisar, `mediaUrl` / `buttonParams`.

#### Agendar atendimento

1. **List Services** → **List Available Slots**.
2. **Create Schedule**.
3. **Generate Calendar Link (.ics)** → **Send Message** com o link.

#### Classificar ticket após compra

1. **Create Tag** ou **List Tags** → **Link Tag**.
2. **Link Wallet** / **Link Kanban** conforme o processo comercial.

### Boas práticas

1. Um workflow por processo de negócio; nomes claros (`Digitalsac - Lead - Enviar boas-vindas`).
2. Validar telefone antes de disparos; testar com poucos contatos antes de volume.
3. Respeitar janela e políticas do WhatsApp / WABA (templates aprovados).
4. Tratar erro no n8n (`continue on fail` / branches de erro) em fluxos críticos.
5. Conferir se a sessão da API está conectada e se o tenant tem o módulo/recurso habilitado.
6. Não reutilizar o mesmo token em ambientes não confiáveis; rotacione tokens periodicamente.

### Referências

* Pacote npm: [n8n-nodes-digitalsac](https://www.npmjs.com/package/n8n-nodes-digitalsac)
* Código e changelog: [n8n-nodes-digitalsac no GitHub](https://github.com/digitalsac-io/n8n-nodes-digitalsac)
* No Digitalsac: **Configurações → API** (token e UUID) e **Configurações → API Typebot** (referência dos endpoints `/typebot`)

### Resumo

O Community Node **DigiCrm Digitalsac** (`n8n-nodes-digitalsac`) conecta workflows do n8n às APIs reais do Digitalsac — mensagens pela API externa e automação operacional pelas rotas `/typebot` — usando apenas a URL da instância e o Bearer token da API do tenant.