n8n-nodes-fastway

Node comunitário para n8n que integra com a API Fastway Expressa v2.

Permite automatizar operações de CRM, Meet, Help & Service, Field Service Management e Relatórios diretamente em workflows n8n.

Recursos disponíveis

| Módulo | Resource | Operations | Endpoint | |--------|----------|------------|----------| | CRM | Company | getAll, get, create, update, delete | /api/v2/crm/company/ | | CRM | Person | getAll, get, create, update, delete | /api/v2/crm/person/ | | CRM | Deal | getAll, get, create, update, delete | /api/v2/crm/deal/ | | CRM | Task | getAll, get, create, update, delete | /api/v2/crm/task/ | | Meet | Evento | getAll, get, create, update, delete | /api/v2/meet/evento/ | | HS | Recurso | getAll | /api/v2/hs/recurso/ | | HS | Agendamento | uploadXml | /api/v2/hs/agendamento/ | | FSM | Ordem de Serviço | getAll, get, create, update, delete | /api/v2/fsm/ordem_servico/ | | FSM | OS Histórico | getAll, get, create, update, delete | /api/v2/fsm/ordem_servico_historico/ | | FSM | OS Visita | getAll, get, create, update, delete | /api/v2/fsm/ordem_servico_visita/ | | Relatórios | Relatório | getEstatisticaHora | /api/v2/relatorios/ |

Autenticação

A API utiliza Bearer Token. Ao configurar a credencial no n8n, informe:

• Base URL: URL da sua instância Fastway (ex: https://sua-instancia.fastway.com.br)
• API Token: Token de autenticação fornecido pela Fastway

Todos os requests são feitos via POST com form-data.

Estrutura do projeto

n8n-nodes-fastway/
├── credentials/
│   └── FastwayApi.credentials.ts        # Credencial Bearer Token + Base URL
├── nodes/
│   └── Fastway/
│       ├── Fastway.node.ts              # Node principal (orchestrator)
│       ├── GenericFunctions.ts          # Helper para chamadas API
│       ├── CompanyDescription.ts        # CRM > Company
│       ├── PersonDescription.ts         # CRM > Person
│       ├── DealDescription.ts           # CRM > Deal
│       ├── TaskDescription.ts           # CRM > Task
│       ├── EventoDescription.ts         # Meet > Evento
│       ├── RecursoDescription.ts        # HS > Recurso
│       ├── AgendamentoDescription.ts    # HS > Agendamento (Upload XML)
│       ├── OrdemServicoDescription.ts   # FSM > Ordem de Serviço
│       ├── OsHistoricoDescription.ts    # FSM > OS Histórico
│       ├── OsVisitaDescription.ts       # FSM > OS Visita
│       ├── RelatorioDescription.ts      # Relatórios
│       └── fastway.svg                  # Ícone do node
├── package.json
├── tsconfig.json
├── gulpfile.js
└── README.md

Desenvolvimento

Pré-requisitos

• Node.js >= 18
• npm >= 9

Setup

# Clonar o repositório
git clone <repo-url>
cd n8n-nodes-fastway

# Instalar dependências
npm install

# Compilar o projeto
npm run build

Testar localmente com npx n8n

A forma mais rápida de testar durante o desenvolvimento:

# 1. Compilar o projeto
npm run build

# 2. Instalar na pasta de custom nodes do n8n
mkdir -p ~/.n8n/custom
cd ~/.n8n/custom
npm init -y
npm install /opt/dev_fastway/n8n-nodes-fastway

# 3. Iniciar o n8n apontando para o pacote
export N8N_CUSTOM_EXTENSIONS="$HOME/.n8n/custom/node_modules/n8n-nodes-fastway"
npx n8n

Acesse http://localhost:5678, crie um workflow e busque por "Fastway".

Testar localmente com Docker

# 1. Compilar o projeto
npm run build

# 2. Copiar para dentro do container
docker cp . <CONTAINER_ID>:/tmp/n8n-nodes-fastway

# 3. Instalar no container
docker exec -it <CONTAINER_ID> sh -c \
  "cd /usr/local/lib/node_modules/n8n && npm install /tmp/n8n-nodes-fastway"

# 4. Reiniciar o container
docker restart <CONTAINER_ID>

Ou via docker-compose.yml:

services:
  n8n:
    image: n8nio/n8n
    ports:
      - "5678:5678"
    volumes:
      - n8n_data:/home/node/.n8n
      - /caminho/para/n8n-nodes-fastway:/home/node/.n8n/custom-nodes/n8n-nodes-fastway
    environment:
      - N8N_CUSTOM_EXTENSIONS=/home/node/.n8n/custom-nodes

Modo watch (desenvolvimento contínuo)

# Terminal 1: compilar automaticamente ao salvar
npm run dev

# Terminal 2: rodar o n8n (reiniciar manualmente após mudanças)
export N8N_CUSTOM_EXTENSIONS="$HOME/.n8n/custom/node_modules/n8n-nodes-fastway"
npx n8n

Após cada alteração, é necessário reiniciar o n8n para que as mudanças sejam carregadas.

Publicação no npm

Primeira publicação

# 1. Criar conta no npm (se ainda não tiver)
npm adduser

# 2. Verificar se o nome do pacote está disponível
npm search n8n-nodes-fastway

# 3. Compilar
npm run build

# 4. Verificar o conteúdo que será publicado
npm pack --dry-run

# 5. Publicar
npm publish

Atualizações

# 1. Atualizar a versão no package.json
npm version patch   # 0.1.0 → 0.1.1 (correções)
npm version minor   # 0.1.1 → 0.2.0 (novas features)
npm version major   # 0.2.0 → 1.0.0 (breaking changes)

# 2. Compilar e publicar
npm run build
npm publish

Instalação pelo usuário final

Após publicado no npm, qualquer usuário n8n pode instalar:

1. No editor do n8n: Settings > Community Nodes > Install
2. Buscar por n8n-nodes-fastway
3. Clicar em Install

Ou via CLI:

# Em instalações self-hosted
cd ~/.n8n
npm install n8n-nodes-fastway

Operações detalhadas

CRUD padrão (Company, Person, Deal, Task, Evento, Ordem de Serviço, OS Histórico, OS Visita)

| Operation | Campos | Descrição | |-----------|--------|-----------| | Get Many | search (opcional) | Lista registros, com filtro opcional | | Get | id (obrigatório) | Busca um registro pelo UUID | | Create | campos obrigatórios + Additional Fields | Cria um novo registro | | Update | id (obrigatório) + Update Fields | Atualiza campos de um registro | | Delete | id (obrigatório) | Remove um registro |

Recurso (HS)

| Operation | Descrição | |-----------|-----------| | Get Many | Lista todos os recursos disponíveis |

Agendamento (HS)

| Operation | Campos | Descrição | |-----------|--------|-----------| | Upload XML | recursoId, binaryPropertyName | Envia arquivo XML de agendamento |

Relatório

| Operation | Campos | Descrição | |-----------|--------|-----------| | Get Estatística por Hora | dataInicial, dataFinal, formato (JSON/XLS/CSV) + filtros opcionais | Gera relatório de estatísticas por hora |

Licença

MIT