FlowField

Integrar com n8n e ERP: API e webhooks

Atualizado em · Para o gestor

Vídeo de 11 s, sem som, gravado do app. O passo a passo em texto está logo abaixo.

O FlowField conversa com o n8n, o seu ERP ou o seu BI de dois jeitos: o token de API deixa o seu sistema buscar e gravar vistorias; o webhook avisa o seu sistema na hora em que algo acontece, como um laudo aprovado.

Tudo fica em Mais › Integrações, que só o titular da conta e quem tem o papel Gestor veem. A documentação completa da API está em https://goflowfield.com/v1/openapi.yaml.

Criar um token de API

  1. Em Integrações, toque em Novo token.
  2. Dê um Nome que diga onde ele vai ser usado, por exemplo "n8n produção".
  3. Toque em Criar token e copie o valor, que começa com ff_.
  4. No seu sistema, envie o token em todo pedido, no cabeçalho Authorization: Bearer ff_….

A lista mostra o começo de cada token, quando foi criado e quando foi usado pela última vez. O token também deixa de valer quando a pessoa que o criou sai da equipe ou exclui a conta.

O que o token pode fazer

O token não aprova, não devolve e não reabre laudo, não cria nem edita formulário e não cria outro token: essas ações ficam com as pessoas da equipe.

Criar um webhook

  1. Em Integrações, toque em Novo webhook.
  2. Em URL de destino, cole o endereço que vai receber os avisos. Precisa ser https e acessível pela internet, na porta padrão do https (443) ou na 8443, e sem usuário e senha no endereço. Um n8n em outra porta (como a 5678) precisa ficar atrás de um endereço https normal; senão o app recusa com "Use a porta padrão do https (443) ou 8443."
  3. Em Eventos, marque o que deve ser avisado: Vistoria criada, Vistoria alterada, Vistoria removida, Laudo aprovado, Vistoria devolvida, Lote sincronizado, Laudo emitido (com o link do PDF), Não conformidade criada ou Prazo de não conformidade (3 dias e vencida). Os três últimos estão em Alertas por e-mail e eventos de webhook.
  4. Toque em Criar webhook e guarde o Segredo (começa com whsec_). Ele também aparece uma vez só.
  5. Toque em Enviar teste para conferir se o destino recebe. O resultado aparece na hora, num aviso: "Entregue (HTTP 200)." ou "Falhou:" e o motivo. O teste chega como o evento changeset.applied (Lote sincronizado), com data.test igual a true. O teste não muda o código que a lista mostra: ele reflete só a última entrega de um evento de verdade (por exemplo, HTTP 200, ou falhou), e um webhook novo mostra sem entregas até o primeiro evento.

Cada organização tem até 10 webhooks, um por endereço. Para mudar os eventos de um webhook, remova e crie de novo.

O que chega no destino

Cada aviso é um POST com corpo JSON { event, occurredAt, data }. Nos eventos de vistoria, data traz a vistoria, com id, situação e respostas. Os cabeçalhos:

No destino, recalcule a assinatura com o segredo e recuse o aviso se ela não bater ou se o carimbo tiver mais de 5 minutos.

Quando o destino falha

O FlowField tenta de novo sozinho, até 10 vezes ao longo de cerca de 72 horas. Resposta 4xx (menos 408 e 429) encerra as tentativas, porque repetir não resolve. Depois de corrigir o destino, toque em Reenviar no webhook (o botão diz quantas falhas há): as entregas que falharam voltam para a fila, com o mesmo id e o mesmo corpo.

Exemplo com o n8n: laudo aprovado vai ao cliente

  1. No n8n, crie um fluxo que começa com um nó Webhook, método POST, e copie a URL de produção dele.
  2. No FlowField, crie o webhook com essa URL e marque só Laudo aprovado.
  3. No n8n, com o data.id do aviso, baixe o PDF em https://goflowfield.com/v1/records/{id}/laudo.pdf com o token no cabeçalho Authorization.
  4. Siga com o que a sua empresa já usa: e-mail ao cliente, pasta compartilhada ou lançamento no ERP.

Artigos relacionados

Voltar à ajuda