Integrações e Dados

┌──────────── INTEGRAÇÕES ────────────┐
│                                      │
│  🗄️ Database Connections (por empresa)│
│     PostgreSQL · MySQL · SQL Server  │
│                                      │
│  📊 Data Sources                     │
│     ├─ SQL (sobre DB Conn)           │
│     ├─ API REST                      │
│     ├─ Formulário interno            │
│     └─ Tabela interna                │
│         ▲                            │
│         │ consumido por:             │
│         │                            │
│  ┌──────┴─────────────────────┐      │
│  │ Dashboards · Filtros        │      │
│  │ Agentes IA · Automações     │      │
│  │ Campos select de formulário │      │
│  └─────────────────────────────┘      │
│                                      │
│  🌐 Webhooks                         │
│     ├─ Entrada (POST → Ziinp)        │
│     └─ Saída (Ziinp → URL externa)   │
│                                      │
│  🔄 Integrações por módulo           │
│     ├─ Form: FormIntegrationTab      │
│     ├─ Form: FormDatabaseIntegrTab   │
│     ├─ Schedule: Google/Outlook      │
│     └─ Sign: plataformas externas    │
│                                      │
│  💾 Backup LGPD (por empresa)        │
└──────────────────────────────────────┘

4.1. Database Connections

• URL: /companies/:id/database-connections.
• O que faz: registra uma conexão SQL do cliente com credenciais isoladas por empresa (multi-tenant).
• Provedores suportados: PostgreSQL, MySQL, SQL Server, e outros via driver.
• Segurança: credenciais criptografadas, leitura somente quando autorizado.
• Onde é consumido:
• como fonte de dados;
• por listas de seleção em formulários;
• por agentes IA;
• por automações.

4.2. Data Sources unificados

• URL: /data-sources (lista), /data-sources/new ou /data-sources/create (criar), /data-sources/:id/edit (editar).
• Abstração: "fonte de dados" não importa se é SQL, API ou formulário — qualquer componente do sistema consome o mesmo jeito.
• Componentes-chave:
• DataSourceAdvancedOptions — paginação, filtros, parâmetros dinâmicos.
• DataSourceOrganizationFields — diz qual coluna é chave, label, geolocalização.
• DataSourceCacheContext — cache controlado por TTL.
• DataSourcePicker — picker reutilizável.
• DataSourceFieldConfig — config de uso em formulário.
• DataSourceSelect — componente de select dinâmico.
• Cache: TTL configurável para baixar carga em fontes externas.

4.3. cURL Import

• Componente: CurlImportDialog.
• Como funciona: cole um comando cURL completo, a Ziinp:
• extrai método, URL, headers, body;
• identifica autenticação (Bearer, Basic);
• cria a fonte de dados pronta para uso.
• Por que é wow: o cliente cola o exemplo do Postman/curl que o time de integração já testou. Em 30 segundos a fonte existe.

4.4. Query Generator (SQL por linguagem natural)

• Componente: QueryGeneratorDialog.
• Como funciona:

1. Descreva em português o que você quer ("quantas inspeções por unidade nos últimos 30 dias").
2. A IA conhece o schema da conexão.
3. Gera o SQL.
4. Você revisa, ajusta e salva.

• Para quem: gestor que sabe o que quer ver mas não escreve SQL.

4.5. Integrações por formulário

4.6. Webhooks de entrada

• Componente exemplo: WebhookExampleCard.
• Como configurar: ao criar uma automação com trigger "webhook", a Ziinp gera um endpoint exclusivo. Qualquer sistema externo envia POST com payload arbitrário e dispara o fluxo.
• Casos clássicos:
• ERP avisa que pedido foi pago → abrir ordem de instalação.
• CRM cria novo cliente → criar booking inicial.
• Sistema legado dispara alerta → criar ação corretiva.

4.7. Webhooks de saída

• Em qualquer etapa de fluxo ou automação, executa POST para URL externa com payload mustachezado.
• Use casos:
• notificar ERP de fechamento de OS;
• empurrar dado para BI corporativo;
• integrar com Slack/Teams custom.

4.8. Integrações nativas

4.9. Backup por empresa

• URL: /companies/:id/backup.
• O que faz: exportação completa dos dados da empresa para entrega sob demanda.
• Por que importa: LGPD — direito de portabilidade dos dados.

4.10. Variáveis Mustache em integrações

• Toda URL, header ou body de webhook pode conter variáveis:
• {{response.campos.cliente_cnpj}}
• {{user.email}}
• {{company.razao_social}}
• {{now}}
• Helper: MustacheVariablePicker.

[ ERP fecha um pedido ]
              │
              ▼
[ POST para webhook Ziinp /webhook/automation/123 ]
              │
              ▼
[ Automation dispara ]
              │
              ▼
[ Agente IA roda: "validar dados do pedido + verificar estoque" ]
              │
       ┌──────┴──────┐
       ▼             ▼
[ query_sql        [ call_api
  no ERP ]           no sistema de estoque ]
       │             │
       └──────┬──────┘
              ▼
[ Agente decide: criar OS de instalação ]
              │
              ▼
[ create_workflow_action ]
              │
              ▼
[ Z-Schedule cria booking ]
              │
              ▼
[ Técnico recebe agenda + formulário pré-preenchido ]

Cenário A — Pré-popular cliente em formulário

Cliente cadastrado no CRM. Formulário "Visita" tem campo Cliente vinculado a fonte SQL no CRM. Operador começa digitando o nome — autocomplete via DataSourceSelect. Selecionou → demais campos preenchidos.

Cenário B — Dashboard misto interno + ERP

Dashboard de "Receita por filial" combina:

• vendas do ERP (via SQL externo);
• contagem de visitas do Z-Field (interno);
• score por equipe do Z-Score (interno).

Tudo em um único painel sem ETL.

Cenário C — IA respondendo sobre ERP

Diretor pergunta ao agente: "Quais os 5 clientes com maior inadimplência?". Agente consulta query_sql na base do ERP, retorna ranking com contexto e sugere ações.

Cenário D — Webhook do banco notifica pagamento

Banco envia webhook quando há baixa. Automação valida CPF, cruza com cadastro, dispara confirmação ao cliente por WhatsApp.

7.1. Pitch 5 minutos

7.2. Apresentação 15 minutos

Objetivos

• Conectar 1 banco SQL externo.
• Criar 1 Data Source SQL com parâmetros dinâmicos.
• Importar 1 fonte via cURL.
• Configurar 1 webhook de entrada e 1 de saída.
• Pré-popular um campo de formulário com fonte externa.

Agenda

Exercícios

1. DB Connection: conectar a um banco PostgreSQL de demo. Testar conexão. 2. Data Source SQL: criar fonte "Clientes ativos" com parâmetro :cidade. Configurar cache de 5 min. 3. cURL Import: importar API pública (ex.: ViaCEP) como fonte. 4. Webhooks: criar automation com webhook de entrada que envia notificação via webhook de saída.

Quiz

1. As credenciais ficam visíveis?
2. Como evitar consulta repetida no banco externo?
3. O que QueryGeneratorDialog faz?
4. Onde aparece o cURL Import?
5. Como o agente IA usa a DB Connection?
6. Posso ter mesma fonte usada em 5 dashboards diferentes?

Setup inicial

• [ ] Criar usuário de banco com permissão somente leitura para conexão Ziinp.
• [ ] Listar os 5 dados mais consumidos do ERP.
• [ ] Criar Data Sources para cada um, com cache adequado.
• [ ] Documentar webhooks de entrada (URL, segredos).
• [ ] Validar tempo de resposta — alertar se > 2s.

Revisão trimestral

• [ ] Há fonte sem uso? Aposentar.
• [ ] Cache TTL adequado por fonte?
• [ ] Webhooks falhando? AutomationHealthPanel.
• [ ] Credenciais rotacionadas?
• [ ] Backup LGPD agendado/testado?

Precisa abrir porta no firewall? Para conexão SQL, sim. Recomenda-se VPN ou IP fixo da Ziinp.

Posso ler de banco de leitura escrava? Sim — exatamente o recomendado.

Posso escrever de volta no ERP? Sim, via API/SQL configurado. Recomendado fazer com supervisão técnica.

O cache atrapalha quando o dado mudou? TTL configurável. Para tempo real estrito, desabilitar cache.

Webhook tem autenticação? Sim — segredo compartilhado e/ou assinatura HMAC.

Posso usar GraphQL? Via API REST adaptada. Suporte nativo a GraphQL no roadmap.

Como faço SSO? Autenticação social (/auth/:social/callback) — Google, Microsoft. SAML/OIDC corporativo via parceiros.

Nesta galeria, as integrações aparecem do ponto de vista de quem implanta: conectar banco, estruturar fontes, importar uma API, gerar SQL, consumir dados no formulário e disparar eventos para sistemas externos. O percurso termina em agenda e backup, mostrando continuidade e governança.

As evidências foram capturadas no sandbox em 24/05/2026. Um mesmo quadro pode ser utilizado em mais de um contexto quando ele comprova uma integração compartilhada por diferentes módulos.

Print 01 - Conexões da empresa

Ampliar

Leitura do print: A página existe no sandbox e apresenta o ponto de criação de conexões, ainda sem conexão configurada.

Evidência capturada; desktop / 1440 x 980; origem: `/companies/:id/database-connections`.

Print 02 - Nova conexão

Ampliar

Leitura do print: O modal centraliza a criação de uma conexão, exibindo tipos de banco suportados, porta, dados de acesso e opção de SSL antes de qualquer vínculo ser salvo.

Evidência capturada; desktop / 1440 x 980; origem: `Modal de nova conexão`.

Print 03 - Catálogo de fontes

Ampliar

Leitura do print: O catálogo real exibe fontes disponiveis e filtros administrativos.

Evidência capturada; desktop / 1440 x 980; origem: `/data-sources`.

Print 04 - Editor de fonte

Ampliar

Leitura do print: A tela de nova fonte demonstra parâmetros usados para conectar dados.

Evidência capturada; desktop / 1440 x 980; origem: `/data-sources/new`.

Print 05 - Importar cURL

Ampliar

Leitura do print: O diálogo transforma um comando cURL de demonstração em configuração de API, incluindo URL, headers e corpo; o token mostrado é apenas um valor fictício do exemplo.

Evidência capturada; desktop / 1440 x 980; origem: `CurlImportDialog`.

Print 06 - SQL gerado por IA

Ampliar

Leitura do print: O assistente recebe uma pergunta em linguagem natural, apresenta a resposta no contexto da fonte conectada e mantém a consulta SQL visível para revisão técnica.

Evidência capturada; desktop / 1440 x 980; origem: `QueryGeneratorDialog` / Assistente de Consulta SQL.

Print 07 - Campo dinâmico

Ampliar

Leitura do print: O campo utiliza a fonte Funcionários Usuários e templates Mustache para separar valor persistido e rótulo exibido, com pesquisa habilitada para a experiência de preenchimento.

Evidência capturada; desktop / 1440 x 980; origem: `DataSourceSelect`.

Print 08 - Aba Integrações

Ampliar

Leitura do print: A aba Integração configura envio automático via API, com endpoint de exemplo, método HTTP e composição visual do corpo JSON a partir dos campos do formulário.

Evidência capturada; desktop / 1440 x 980; origem: `/forms/:id - Integrações`.

Print 09 - Aba Banco de dados

Ampliar

Leitura do print: A integração com banco externo associa uma conexão selecionada a uma query de inserção, composta visualmente com campos do formulário e variáveis do sistema.

Evidência capturada; desktop / 1440 x 980; origem: `/forms/:id - Banco de dados`.

Print 10 - Exemplo de payload

Ampliar

Leitura do print: O construtor visual permite selecionar campos do formulário e variáveis do sistema para compor um payload JSON rastreável antes do envio à integração.

Evidência capturada; desktop / 1440 x 980; origem: `WebhookExampleCard` / Corpo da Requisição.

Print 11 - Webhook de saída

Ampliar

Leitura do print: A etapa de ação configura uma chamada HTTP POST de saída com endpoint, autenticação e áreas de headers, parâmetros e corpo, usando endereço fictício para demonstração.

Evidência capturada; desktop / 1440 x 980; origem: `/automation/:id/edit` - Chamada de API.

Print 12 - Integrações de agenda

Ampliar

Leitura do print: O módulo de agenda comprova um dos pontos de integração externa.

Evidência reutilizada; desktop / 1440 x 980; origem: `/scheduling-management/integrations`.

Print 13 - Backup e importacao

Ampliar

Leitura do print: A interface LGPD permite selecionar dominios para exportação do tenant.

Evidência capturada; desktop / 1440 x 980; origem: `/companies/:id/backup`.

🏭 Indústria — Integração com ERP de manutenção

Z-Schedule consome lista de equipamentos do ERP via SQL. Formulário "Manutenção" pré-popula código + última revisão. Ao concluir, webhook empurra evento "MANUTENCAO_REALIZADA" pra fila do ERP. Resultado: Ziinp opera junto, ERP segue como sistema de registro.

⚡ Telecom — CRM + Sistema de provisionamento

Cliente cadastrado no CRM (Salesforce/HubSpot). Z-Field consome lista por API REST. Após instalação, webhook empurra "INSTALAÇÃO_OK" pro sistema de provisionamento. Resultado: sem digitação dupla, sem inconsistência.

🏥 Saúde — Integração HL7 / FHIR via webhook

Sistema clínico envia webhook para Ziinp ao criar paciente. Cria automation que registra ficha base. Atendimento ao final empurra dados estruturados via webhook de saída pro EMR.

💰 Backoffice — ERP financeiro

Reembolsos: SQL externo lê centro de custo, projeto, alçada. Z-Flow aprova com regra de valor. Webhook gera lançamento contábil no ERP.

🛒 Varejo — Sistema de loja (PDV)

Vendas do PDV sincronizadas via SQL (réplica leitura). Dashboard misto: vendas + visitas + auditoria. Webhook do PDV dispara alerta se quebra de meta.

🏗️ Construção — Folha de pagamento

RH consome relatório de horas/produtividade do Z-Field via API. Webhook ao fechar mês empurra dados pra folha.

🌾 Agro — Estações meteorológicas

API de estações meteorológicas como Data Source. Dashboard cruza clima com inspeções e produtividade.

🎓 Educação — LMS corporativo

Treinamentos do Ziinp publicados também no LMS via webhook. Status de conclusão sincronizado.

Receita 1 — Pré-popular cliente em formulário

1. Em /companies/:id/database-connections
   Criar conexão "ERP_PROD" (PostgreSQL réplica leitura).

2. Em /data-sources
   Nova fonte "Clientes Ativos":
     query: SELECT id, razao_social, cnpj, cidade FROM clientes WHERE ativo = true
     cache TTL: 5 min
     campo chave: id
     campo label: razao_social

3. No formulário, adicionar campo "Cliente"
   tipo: select dinâmico
   fonte: Clientes Ativos
   busca: razao_social

4. Operador começa digitando, autocomplete cai do ERP em real time.

Receita 2 — Webhook do ERP cria ação na Ziinp

1. Em /automation, criar automation
   trigger: webhook
   URL gerada: https://api.ziinp.app/webhook/automation/abc123
   segredo: HMAC com chave compartilhada

2. Configurar no ERP para chamar essa URL ao evento X
   POST body: { pedido_id, cliente_id, urgencia }

3. Automation:
   action 1: chamar agente IA "Triador de Pedido"
   action 2: create_workflow_action conforme retorno do agente

Receita 3 — Webhook de saída para Slack

Em qualquer etapa de Z-Flow:
  ação ao concluir: webhook
  método: POST
  URL: https://hooks.slack.com/services/T0/B0/XXX
  body: {
    "text": "✅ Ação {{step.nome}} concluída por {{user.nome}} no formulário {{form.titulo}}",
    "channel": "#operacoes"
  }

Receita 4 — Agente IA respondendo sobre ERP

Agente "Consultor ERP":
  Tools: query_sql (sobre conexão ERP_PROD)
  Schema: [colar schema relevante]

  Persona: Você responde sobre vendas, estoque, financeiro.
  Sempre devolve resposta em português + tabela.

Usuário pergunta no /agentes:
  "Top 5 clientes em atraso há mais de 30 dias com saldo > R$ 50k"

Agente:
  1. Escreve SELECT cliente, saldo, dias_atraso FROM ...
  2. Executa
  3. Devolve tabela formatada

Receita 5 — Importar fonte via cURL

Cole no CurlImportDialog:

curl -X GET 'https://api.fornecedor.com/produtos' \
  -H 'Authorization: Bearer XXX' \
  -H 'Content-Type: application/json'

Ziinp detecta:
  método GET
  URL parametrizada
  autenticação Bearer
  resposta JSON

Cria fonte "Produtos Fornecedor" pronta.

• Conectar todos os ERPs do cliente num primeiro POC.
• Substituir 1 planilha por uma fonte SQL viva no Z-Field.
• Demonstrar agente IA respondendo sobre ERP — virou diferencial competitivo.
• Configurar backup mensal automatizado por empresa.