Sincronizar fornecedores com n8n

O que você vai construir

Um workflow n8n que roda todo dia às 6h, lê a planilha de fornecedores que o setor financeiro mantém no Google Sheets e reflete cada linha na Ligga: quem já existe é atualizado, quem não existe é criado.

O desenho do fluxo:

Schedule Trigger (cron 0 6 * * *)
  ↓
Google Sheets (lê a aba "Fornecedores")
  ↓
Split In Batches (1 linha por vez)
  ↓
HTTP Request: GET /v1/suppliers?filter[name][eq]=<nome da linha>
  ↓
If: a listagem devolveu algum registro?
  ├── Sim  → HTTP Request: PATCH /v1/suppliers/<id encontrado>
  └── Não  → HTTP Request: POST /v1/suppliers (com Idempotency-Key)
  ↓
volta ao Split In Batches até a planilha acabar

Pré-requisitos

Uma instância de n8n, na nuvem ou própria, com acesso à internet.
Uma chave de API com o escopo suppliers:write e o módulo fornecedores habilitado no contrato. Confira os dois em GET /v1/me.
Uma credencial do Google com acesso de leitura à planilha.
Uma planilha cujos cabeçalhos usem os nomes de campo do recurso Fornecedores: name, document_number e email.

Passo a passo

Crie a credencial da Ligga. Em Credentials → New → Header Auth, preencha o nome como Ligga API, o cabeçalho como Authorization e o valor como Bearer ligga_live_…. O passo está detalhado no guia de n8n.
Schedule Trigger. Modo Cron, expressão 0 6 * * *. É o único nó que dispara o fluxo.
Google Sheets — ler a planilha. Resource Sheet Within Document, operação Get Row(s), aba Fornecedores, opção Return All ligada. Cada linha vira um item do n8n.
Split In Batches. Batch Size 1. A Ligga é consultada uma vez por fornecedor, e uma linha com erro não derruba as outras.
HTTP Request — procurar o fornecedor. Method GET, URL https://api.ligga.app/functions/v1/api/v1/suppliers, autenticação Ligga API, e dois parâmetros de query: filter[name][eq] com o valor {{ $json.name }} e limit com o valor 1.
If — já existe? Condição sobre {{ $json.data.length }}, verdadeira quando é maior que zero. A resposta de listagem sempre traz data como lista, então o teste funciona mesmo quando não há resultado.
Ramo verdadeiro: atualizar. Method PATCH, URL https://api.ligga.app/functions/v1/api/v1/suppliers/{{ $json.data[0].id }}, autenticação Ligga API, corpo em JSON com os campos que a planilha controla. O PATCH é parcial: o que você não manda fica como está.
Ramo falso: criar. Method POST, URL https://api.ligga.app/functions/v1/api/v1/suppliers, autenticação Ligga API, mais os cabeçalhos Content-Type e Idempotency-Key. A resposta é 201 Created.
Opcional: avise quem acompanha. Um nó de Slack ou de e-mail no fim do laço, com a contagem de criados, atualizados e falhos, transforma o workflow em algo que alguém percebe quando quebra.

Código completo

Os trechos que você cola nos nós de HTTP Request.

Parâmetros de query do nó de busca (passo 5):

filter[name][eq] = {{ $json.name }}
limit            = 1

Corpo do nó de atualização (passo 7):

{
  "document_number": "{{ $node['Google Sheets'].json.document_number }}",
  "email": "{{ $node['Google Sheets'].json.email }}"
}

Cabeçalhos e corpo do nó de criação (passo 8):

Content-Type    = application/json
Idempotency-Key = sync-{{ $node['Google Sheets'].json.name }}

{
  "name": "{{ $node['Google Sheets'].json.name }}",
  "document_number": "{{ $node['Google Sheets'].json.document_number }}",
  "email": "{{ $node['Google Sheets'].json.email }}"
}

Decisões

A busca é por name porque a planilha não conhece os identificadores da Ligga. É o casamento possível quando o lado de fora só tem o nome digitado por uma pessoa. Se a sua planilha tiver o CNPJ, troque o filtro para filter[document_number][eq]: documento é bem mais estável que nome, que muda com abreviação, acento e espaço a mais.

A chave de idempotência vem do nome do fornecedor. Se o workflow reexecutar o mesmo dia, a criação repetida devolve o fornecedor original em vez de gravar um segundo registro igual.

Uma linha por vez, de propósito. Com Batch Size 1, cada fornecedor vira duas requisições, uma de leitura e uma de escrita. É mais lento do que disparar tudo junto e é o que mantém o fluxo dentro das cotas do plano sem precisar de tratamento de 429. Para planilhas grandes, acrescente um nó Wait curto dentro do laço. Os limites do seu plano estão em Limites de requisições.

Os erros da Ligga chegam como texto no n8n. As respostas de erro usam o tipo application/problem+json, que o n8n não converte sozinho. Para ler type, detail ou request_id, faça o parse explícito, como mostra a seção correspondente do guia de n8n.

Quando não usar

A planilha é a fonte de verdade em mão dupla. Este fluxo só empurra dados da planilha para a Ligga. Sincronizar nos dois sentidos exige controle de conflito e um serviço próprio, não um workflow visual.
O volume é alto. Milhares de linhas por execução significam milhares de requisições e, em n8n na nuvem, cobrança por execução. Nesse caso, um script agendado como o da receita de importação de clientes sai mais barato.
Você precisa apagar fornecedores que sumiram da planilha. O DELETE da Ligga desativa o registro em vez de removê-lo, e transformar ausência na planilha em desativação automática costuma dar prejuízo no primeiro erro de digitação.

Veja também

Fornecedores (suppliers) — campos, filtros e a semântica do DELETE
n8n — credencial, paginação e leitura dos erros
Idempotência — como escolher a chave
Limites de requisições — cotas por plano