API e integrações

O LinkedFlow fala com o resto das tuas ferramentas por três caminhos: uma API REST com token, um webhook que dispara workflows a partir de fora e nós que chamam os teus próprios serviços de dentro de um percurso. Esta página é o contrato exato, com exemplos prontos para n8n, Make ou um simples curl.

Os três caminhos

Autenticação

Toda a API vive em https://app.linkedflow.pro/api/v1 e autentica-se com um token no cabeçalho Authorization. Há duas formas de o obter, e só a primeira serve para integrações.

Token de API (o que queres para o n8n)

Na aplicação: Definições → Tokens de API → Novo token. Dás-lhe um nome («n8n · sinais diários»), escolhes a expiração — 30 dias, 90 dias, 1 ano ou sem expiração — e copia-lo: só é mostrado uma vez.

Sugestão: cria um utilizador à parte para a máquina («automacao@aminhaempresa.com») com o papel mínimo necessário e emite o token a partir dessa conta. Assim a atividade do workspace distingue o que fez um humano do que fez o n8n, e podes cortar-lhe o acesso sem mexer no teu.

Token de sessão (para um script descartável)

O login da aplicação também devolve um token, mas expira ao fim de 30 dias e segue o workspace ativo do teu utilizador. Serve para um curl de teste; não para uma automação que tem de aguentar meses:

curl -X POST https://app.linkedflow.pro/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"email":"tu@email.com","password":"a-tua-palavra-passe"}'

{
  "user": { "id": "…", "name": "Valen", "current_workspace": { "id": "…", "role": "OWNER" } },
  "token": "198|eMdBPK8g…"
}

A partir daí, cada chamada leva dois cabeçalhos:

Authorization: Bearer 198|eMdBPK8g…
Accept: application/json

Workspace e papéis

Não é preciso enviar o workspace: o token trabalha sempre sobre o workspace atual do utilizador. Se pertences a vários, POST /auth/switch-workspace/{workspace} troca. Cada endpoint exige o mesmo papel que o ecrã equivalente na aplicação (VIEWER < MEMBER < MANAGER < ADMIN < OWNER); se faltar, a resposta é 403. Os papéis estão explicados em Definições.

Sugestão para integrações: cria um utilizador à parte para a máquina («automacao@aminhaempresa.com») com o papel mínimo necessário. Podes cortar-lhe o acesso sem mexer no teu, e na atividade do workspace distingue-se o que fez um humano do que fez o n8n.

Convenções

• Sem Accept: application/json não há JSON: a aplicação responderia com um redirecionamento ou HTML. É o erro número um de quem começa.
• Erros: 401 token em falta ou expirado, 403 papel insuficiente ou subscrição inativa, 404 fora do teu workspace, 422 validação ({"message":"…","errors":{"campo":["…"]}}), 429 demasiadas chamadas.
• Coleções: os prospetos vêm paginados (data, current_page, last_page, total); outros recursos devolvem a coleção direta ou dentro de items. Olha sempre para a primeira resposta antes de mapear campos.
• Idioma: as mensagens de erro saem no idioma do teu utilizador. Podes forçá-lo com Accept-Language: pt.
• Ritmo: não há limite global, mas os endpoints caros têm o seu (o webhook de workflow, 30 chamadas por minuto; o compositor de IA, 20).

Endpoints principais

A lista completa é a da aplicação; isto é o que realmente se usa a partir de fora.

Prospetos e listas

Workflows e execuções

A receita que resolve 80 %: criar e disparar

Um prospeto novo entra no CRM e, se o deixares cair numa lista, o workflow que escuta essa lista arranca sozinho. São duas chamadas, ou até uma:

curl -X POST https://app.linkedflow.pro/api/v1/prospects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{
    "linkedin_url": "https://www.linkedin.com/in/alguem",
    "first_name": "Ana",
    "company": "Consultora Norte",
    "tags": ["n8n", "sinal:a-contratar"],
    "source": "n8n",
    "list_id": "01a05d4e-23b2-725c-9aa4-e1ed9e8fd6da"
  }'

Três coisas a saber sobre esta chamada:

• Basta linkedin_url ou public_identifier. Se o URL não for de um perfil, responde 422.
• O duplicado responde 409 e não é uma falha: devolve o prospeto que já existia e adiciona-o à lista à mesma. No n8n, configura o nó para não abortar com 409 — é o caminho normal quando reprocessas uma fonte.
• Ao entrar na lista dispara o trigger «Ao adicionar a uma lista» de qualquer workflow ativo que a escute, quer o prospeto seja novo, quer já existisse e não estivesse nela. É esse o engate: o n8n não precisa de saber nada de workflows, só de encher uma lista.

Um list_id com forma de UUID mas que não existe (ou que é de outro workspace) não dá erro: o prospeto é criado e não entra em lista nenhuma. É isolamento entre inquilinos — a resposta não pode revelar que listas outro tem — por isso confere o campo lists da resposta se queres ter a certeza.

Se preferires lançar explicitamente, usa POST /workflows/{id}/run com {"list_id":"…"} ou {"prospect_ids":["…"]}. Exige papel MANAGER e uma versão guardada do workflow.

Webhook de entrada: disparar um workflow a partir de fora

Um workflow que começa pelo nó Webhook expõe um URL com token próprio (visível no builder, papel MANAGER ou superior):

POST https://app.linkedflow.pro/api/v1/webhooks/workflows/{token}
Content-Type: application/json

{ "linkedin_url": "https://www.linkedin.com/in/alguem" }

Identificadores válidos, pelo menos um: public_identifier, linkedin_url ou email. O que enviares a mais fica disponível dentro do percurso como {{trigger.*}}, por isso podes passar o motivo do sinal e usá-lo no texto da mensagem.

O 202 também não garante que o percurso comece: um prospeto suprimido, marcado «não contactar» ou que já respondeu fica de fora pelas proteções do costume. O que aconteceu de facto vê-se em Execuções.

Saídas: quando o LinkedFlow chama a tua ferramenta

Webhook de saída

O nó Webhook de saída faz um POST para o URL que indicares. Sem corpo personalizado, envia isto:

{
  "prospect": {
    "id": "01a0…",
    "full_name": "Ana García",
    "linkedin_url": "https://www.linkedin.com/in/…",
    "company": "Consultora Norte",
    "status": "REPLIED"
  },
  "execution_id": "01a0…",
  "node_id": "webhook_1"
}

https://o-teu-n8n/webhook/respostas?s=UM-SEGREDO-LONGO&cat={{previous.classification}}

Detalhes operacionais: 15 segundos de tempo máximo; um 5xx é considerado passageiro e é repetido até três vezes com espera crescente; um 4xx é marcado como falha de configuração e espera decisão tua na caixa de erros. Responde depressa e com 200: se a tua automação for lenta, aceita primeiro e processa depois.

Pedido HTTP: pedir um dado e seguir

O nó Pedido HTTP é igual, mas pensado para usar a resposta. O que devolveres fica disponível no nó seguinte:

{{previous.status}}              → 200
{{previous.response.tier}}       → "A"   (o teu JSON, dentro de "response")
{{previous.response.angulo}}     → "está a contratar"

Com isso, um nó Se bifurca pelo teu próprio scoring: {{previous.response.tier}} == "A". Devolve sempre um JSON plano e responde em menos de 15 segundos; se o teu serviço puder demorar, devolve um valor por omissão em vez de fazer o percurso esperar.

Cinco fluxos de n8n que funcionam

1 · Sinal externo → contacto (captar)

Schedule às 07:30 → HTTP Request à tua fonte de sinais (publicações, mudanças de cargo, ofertas de emprego) → Code que normaliza para linkedin_url → Remove Duplicates → HTTP Request para POST /prospects com o list_id de «Sinais de hoje» e o sinal em tags.

No LinkedFlow: um workflow ativo com disparador Ao adicionar a uma lista → Ler perfil → Pontuar com IA → Se {{previous.score}} >= 70 → Reagir à última publicação → Esperar 1 dia → Enviar convite com nota. Configura o nó do n8n para tratar o 409 como sucesso.

2 · Resposta classificada → CRM e agenda (atender)

No LinkedFlow: disparador Mensagem recebida → nó Classificar resposta → todas as saídas para o mesmo Webhook de saída, com a categoria no URL: ?cat={{previous.classification}}.

No n8n: Webhook → um Se que compara {{ $json.query.s }} com o teu segredo → Switch por {{ $json.query.cat }}: INTERESTED cria o negócio no teu CRM, avisa no Slack e envia o link de agendamento; QUESTION redige um rascunho com IA e deixa-o no Slack para aprovação; NOT_NOW escreve a data de recontacto numa folha e um cron reinjeta-a aos 90 dias; DO_NOT_CONTACT chama POST /suppression e fecha.

3 · «Comenta GUIA e eu envio»

No LinkedFlow: disparador Comentário numa publicação com palavra-chave → Reagir ao comentário → Responder ao comentário → Enviar mensagem com o link → Webhook de saída.

No n8n: inscrição na tua ferramenta de email, linha numa folha com comentou → entregue → abriu, e ao fim de três dias, se não houve resposta, um POST para o webhook de entrada de um workflow de seguimento. Lembra-te de que os comentários são sondados a cada 5 minutos e que responder a um comentário não gasta quota de mensagens.

4 · Enriquecimento e scoring próprios a meio do percurso

Aqui é o LinkedFlow que chama o n8n. No percurso: Ler perfil → Pedido HTTP ao teu webhook do n8n (responder com o último nó) → Se {{previous.response.tier}} == "A" → convite com nota à medida; se não, para uma lista de nurturing.

No n8n: Webhook → scraping do site da empresa → um modelo de IA que devolve JSON estrito (tier, angulo, dor) → Respond to Webhook. Põe um fallback (tier: "B") para que uma falha tua nunca entupa o percurso.

5 · O relatório de segunda-feira (vigiar)

Schedule segunda às 07:00 → GET /dashboard/funnel e GET /executions → GET /errors/unmanaged → um modelo de IA com o prompt «três decisões, não três gráficos» → email. Zero painéis novos: os números saem da mesma API que desenha o dashboard da aplicação.

Descarrega-os já montados

Quatro workflows de n8n prontos a importar a partir de ficheiro. Antes de os ativar: cria uma credencial Header Auth com o nome Authorization e o valor Bearer <o-teu-token>, e substitui o id de lista de exemplo pelo teu.

• 1 · Sinal externo → prospeto numa lista — o que resolve 80 %.
• 2 · Resposta classificada → CRM e agenda — inclui a verificação do cabeçalho secreto.
• 3 · Enriquecimento e scoring — o que responde ao nó Pedido HTTP.
• 4 · O relatório de segunda-feira — funil, execuções e erros pela API.

Boas práticas

• Deduplica antes de chamar, por linkedin_url e dia. Dois POST iguais não duplicam o prospeto, mas podem metê-lo duas vezes no fluxo se o tirares da lista e o voltares a pôr.
• Não lutes contra as quotas. Por muito depressa que empurres, as ações saem ao ritmo da conta (25 visitas, 20 convites e 30 mensagens por dia por omissão). Pôr 500 prospetos na fila não acelera nada, só enche a fila.
• Regista o execution_id que chega nos webhooks de saída: é a chave para voltar a ver esse percurso na aplicação.
• Um utilizador por integração, com o papel mínimo, e roda o seu token quando mudar de mãos.