n8n-nodes-sensedata

Este é um pacote de nodes para n8n que permite integração completa com a API SenseData V2.

Sobre

O SenseData é uma plataforma de Customer Success que permite gerenciar clientes, contratos, atividades, KPIs e muito mais. Este pacote fornece nodes completos para integrar o n8n com todas as funcionalidades da API SenseData V2.

Instalação

Via n8n Community Nodes

1. Acesse seu n8n
2. Vá em Settings > Community Nodes
3. Selecione Install e digite: n8n-nodes-sensedata
4. Clique em Install

Via npm (manual)

npm install n8n-nodes-sensedata

Configuração

Credenciais

1. Acesse seu n8n
2. Vá em Credentials > New
3. Procure por SenseData API
4. Preencha:
   • API Token: Seu token de API do SenseData
   • Base URL: https://api.sensedata.io/v2 (padrão)

Para obter seu token de API, acesse a documentação oficial do SenseData.

Nodes Disponíveis

Recursos Principais

1. SenseData Customer (Clientes)

Gerencia clientes na plataforma SenseData.

Operações:

• Get: Buscar cliente por ID
• Get All: Listar todos os clientes com filtros
• Create/Update: Criar ou atualizar clientes
• Update: Atualização parcial de clientes
• Update Custom Field: Atualizar campos customizados

Filtros principais: ID, CNPJ, Status, CS, CSM, Localização, Datas

2. SenseData Contact (Contatos)

Gerencia contatos de clientes.

Operações:

• Get: Buscar contato por ID
• Get All: Listar todos os contatos
• Create/Update: Criar ou atualizar contatos
• Update: Atualização parcial
• Update Custom Field: Atualizar campos customizados

Filtros principais: Customer, Email, Phone, Type, Is Main Sponsor

3. SenseData Task (Atividades)

Gerencia atividades e tarefas.

Operações:

• Get: Buscar atividade por ID
• Get All: Listar todas as atividades
• Create/Update: Criar ou atualizar atividades
• Update: Atualização parcial
• Update Custom Field: Atualizar campos customizados

Filtros principais: Customer, Contact, Owner, Status, Type, Priority, Datas, Playbook

4. SenseData Billing (Títulos Financeiros)

Gerencia títulos financeiros.

Operações:

• Get: Buscar título por ID
• Get All: Listar todos os títulos
• Create/Update: Criar ou atualizar títulos
• Update: Atualização parcial

Filtros principais: Customer, Status, Datas de vencimento/pagamento/faturamento

5. SenseData Contract (Contratos)

Gerencia contratos de clientes.

Operações:

• Get: Buscar contrato por ID
• Get All: Listar todos os contratos
• Create/Update: Criar ou atualizar contratos
• Update: Atualização parcial

Filtros principais: Customer, Status, Datas de vigência

6. SenseData Customer Note (Notas de Clientes)

Gerencia notas de clientes.

Operações:

• Get: Buscar nota por ID
• Get All: Listar todas as notas
• Create/Update: Criar ou atualizar notas
• Update: Atualização parcial
• Delete: Remover nota da visualização

Filtros principais: Customer, Deleted, Created By, Deleted By

Recursos de Leitura (Read-Only)

7. SenseData KPI

Acessa indicadores de performance.

Operações:

• Get: Buscar KPI específico (por tipo/data/cliente)
• Get All: Listar KPIs

Nota: Use sempre os filtros de data (ref_date:start e ref_date:end) para melhor performance.

8. SenseData Playbook

Acessa playbooks configurados.

Operações:

• Get: Buscar playbook por ID
• Get All: Listar playbooks

Recursos Auxiliares

9. SenseData Custom Data (Dados Customizados)

Gerencia dados customizados.

Operações:

• Get: Buscar por ID
• Get All: Listar dados
• Create/Update: Criar ou atualizar

10. SenseData Usage Time (Tempo de Uso)

Gerencia registros de tempo de uso.

Operações:

• Get: Buscar por ID
• Get All: Listar registros
• Create/Update: Criar ou atualizar

11. SenseData Default Usage (Uso Padrão)

Gerencia dados de uso padrão.

Operações:

• Get: Buscar por ID
• Get All: Listar dados
• Create/Update: Criar ou atualizar

12. SenseData Status (Status Multifuncional)

Node unificado para gerenciar status de diferentes recursos.

Recursos disponíveis:

• Customer Status
• Billing Status
• Contract Status
• Task Status (somente leitura)
• Task Types (somente leitura)

Operações (Customer/Billing/Contract Status):

• Get: Buscar por ID
• Get All: Listar
• Create/Update: Criar ou atualizar

Exemplos de Uso

Exemplo 1: Listar todos os clientes ativos

1. Adicione o node SenseData Customer
2. Selecione operação: Get All
3. Configure filtro: status = "Ativo"
4. Marque Return All ou defina um limite

Exemplo 2: Criar ou atualizar um cliente

1. Adicione o node SenseData Customer
2. Selecione operação: Create/Update
3. No campo Data, insira o JSON:

{
  "data": [
    {
      "id_legacy": "CLIENTE-001",
      "name": "Empresa XYZ Ltda",
      "name_contract": "Empresa XYZ",
      "dt_register": "2025-10-02",
      "cs": {"email": "cs@example.com"},
      "csm": {"email": "csm@example.com"},
      "status": {"description": "Ativo"}
    }
  ]
}

Exemplo 3: Buscar KPIs de um período

1. Adicione o node SenseData KPI
2. Selecione operação: Get All
3. Configure filtros:
   • ref_date:start: "2025-09-01"
   • ref_date:end: "2025-09-30"
   • customer:id: 123

Exemplo 4: Criar uma atividade

1. Adicione o node SenseData Task
2. Selecione operação: Create/Update
3. No campo Data, insira:

{
  "data": [
    {
      "customer": {"id": 123},
      "id_legacy": "TASK-001",
      "description": "Reunião de onboarding",
      "owner": {"email": "usuario@example.com"},
      "status": {"description": "Pendente"},
      "type": {"description": "Reunião"},
      "priority": {"description": "Alta"},
      "start_date": "2025-10-03",
      "due_date": "2025-10-10"
    }
  ]
}

Estrutura de Dados

Formato de Request Body (POST/PATCH)

Todos os endpoints que aceitam POST ou PATCH requerem que os dados sejam enviados dentro de um array data:

{
  "data": [
    {
      // objeto 1
    },
    {
      // objeto 2
    }
  ]
}

Paginação

Todos os endpoints de listagem (Get All) suportam paginação:

• Return All: Busca todos os registros automaticamente (percorrendo todas as páginas)
• Limit: Define quantos registros retornar (máximo 1000 por chamada)

Filtros

Os filtros seguem o padrão da API SenseData:

• Filtros simples: id, name, cnpj
• Filtros de relacionamento: customer:id, owner:email, status:description
• Filtros de data: created_at:start, created_at:end, due_date:start, due_date:end
• Filtros vazios: payment_date:empty, updated_at:empty

Formatos de Data

• Date: YYYY-MM-DD (exemplo: 2025-10-02)
• DateTime: YYYY-MM-DDTHH:MM:SS ou YYYY-MM-DDTHH:MM:SSZ (exemplo: 2025-10-02T14:30:00)
• Time: HH:MM:SS (exemplo: 14:30:00)

Recursos Excluídos

Por solicitação do desenvolvedor, os seguintes endpoints NÃO estão incluídos neste pacote:

• Formulários (/v2/forms)
• NPS (/v2/nps)
• Prioridades de Atividade (/v2/tasks_priorities)
• Atividades Deletadas (/v2/deleted_tasks)
• Usuários (/v2/users)
• Jornada da Carteira (/v2/journeys)
• Suporte (/v2/support_tickets)
• Check-in de Atividade (/v2/tasks_checkin)

Tratamento de Erros

Todos os nodes suportam a opção Continue On Fail do n8n. Quando habilitada, erros não interrompem o workflow e são retornados como:

{
  "error": "Mensagem de erro"
}

Documentação da API

Para mais informações sobre a API SenseData, consulte:

• Documentação oficial: https://api.sensedata.io/v2/redoc
• Handbook da API: Incluído no repositório como sensedata_v2_handbook.md

Suporte

• Issues: https://github.com/yourusername/n8n-nodes-sensedata/issues
• Documentação SenseData: https://api.sensedata.io/v2/redoc

Desenvolvimento

Estrutura do Projeto

n8n-nodes-sensedata/
├── credentials/
│   └── SenseDataApi.credentials.ts
├── nodes/
│   └── SenseData/
│       ├── GenericFunctions.ts
│       ├── sensedata.svg
│       ├── SenseDataBilling.node.ts
│       ├── SenseDataContact.node.ts
│       ├── SenseDataContract.node.ts
│       ├── SenseDataCustomData.node.ts
│       ├── SenseDataCustomer.node.ts
│       ├── SenseDataCustomerNote.node.ts
│       ├── SenseDataDefaultUsage.node.ts
│       ├── SenseDataKpi.node.ts
│       ├── SenseDataPlaybook.node.ts
│       ├── SenseDataStatus.node.ts
│       ├── SenseDataTask.node.ts
│       └── SenseDataUsageTime.node.ts
├── package.json
├── tsconfig.json
└── README.md

Build

npm run build

Desenvolvimento

npm run dev

Licença

MIT

Autor

Desenvolvido para integração com n8n.

Nota: Este é um pacote desenvolvido pela comunidade e não é oficialmente mantido pelo SenseData ou n8n.