Trilha 08 · Integrações e implantação

Padrões de integração na prática

Como um processo do Autoflow conversa com outros sistemas: buscar dados em APIs, registrar em ERPs, esperar respostas, receber pedidos e avisar por webhook. Cinco padrões, o papel do conector intermediário e o que acontece quando algo dá errado.

Por que processos precisam falar com outros sistemas

Quase nenhum processo real vive sozinho. No meio do fluxo aparecem momentos em que a informação está em outro lugar ou precisa ir para outro lugar:

• um escritório de advocacia precisa buscar processos em que o cliente é parte nos tribunais antes de aceitar o caso;
• uma prefeitura precisa consultar a situação cadastral de um CNPJ antes de emitir um alvará;
• uma concessionária precisa avisar o ERP quando a venda for concluída;
• um sistema de captura de publicações precisa abrir um processo de prazo sempre que sai uma intimação.

Sem integração, alguém faz isso à mão: abre outro sistema, copia, cola, anexa um print. É lento, gera erro de digitação e não deixa rastro.

As quatro direções

Toda integração responde a uma pergunta: quem começa a conversa e quem espera quem?

Explore cada padrão abaixo: a sequência mostra quem chama quem, e os blocos de código mostram exatamente o que trafega.

{
  "pedido": "01JB7Q3M2X5V8Y1Z4C6E9G0H2K",
  "callbackUrl": "https://autoflow.cliente.com.br/api/public/v1/process-instances/7da66f1a-…/messages",
  "processo": 1042,
  "parte": { "nome": "Construtora Alfa Ltda", "documento": "12.345.678/0001-90" },
  "tribunais": ["TJSP", "TRT2", "TRF3"]
}

curl -X POST "$CALLBACK_URL" \
  -H "Authorization: Bearer pf_ab12cd34_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: retorno-01JB7Q3M2X5V8Y1Z4C6E9G0H2K" \
  -d '{
    "exchangeId": "01JB7Q3M2X5V8Y1Z4C6E9G0H2K",
    "variables": {
      "processosEncontrados": 3,
      "processosContraCliente": 1,
      "resumoBusca": "1 execução fiscal no TRF3; 2 ações como autora no TJSP"
    }
  }'

curl -X POST "$CALLBACK_URL" \
  -H "Authorization: Bearer pf_ab12cd34_…" \
  -F exchangeId=01JB7Q3M2X5V8Y1Z4C6E9G0H2K \
  -F 'variables={"processosContraCliente":1}' \
  -F "RELATORIO_BUSCA=@relatorio.pdf;type=application/pdf"
# o nome do campo de arquivo é o TIPO DE DOCUMENTO declarado no bloco

O ponto que mais confunde: o conector intermediário

Este é o conceito mais importante da lição. Leia com calma.

O bloco Enviar a sistema externo do Autoflow sempre faz a chamada do mesmo jeito:

• método POST, corpo JSON;
• para o endereço URL base da integração + caminho configurado no bloco;
• assinado pelo Autoflow (cabeçalho X-ProcessFlow-Signature, HMAC-SHA256 com o segredo do webhook da integração);
• sem campo para colocar o token, a chave ou o certificado de outro sistema.

Já as APIs do mundo real são todas diferentes. A API de um tribunal pede uma chave própria num cabeçalho e usa uma consulta específica. Um provedor de dados cadastrais pede OAuth. Um sistema legado do órgão só fala SOAP ou exige certificado digital. Um ERP quer o cliente num formato próprio.

Por isso, na maioria dos casos, existe uma peça no meio: o conector intermediário (também chamado de adaptador ou middleware). É um serviço pequeno, mantido pela sua equipe ou pela TI do cliente, que:

1. Recebe o pedido do Autoflow e confere a assinatura (garante que veio mesmo do Autoflow).
2. Traduz para o formato da API de destino e usa as credenciais dela (que ficam guardadas no conector, não no Autoflow).
3. Chama uma ou várias APIs, pagina resultados, junta fontes, trata indisponibilidade.
4. Devolve ao Autoflow um resultado simples: na hora (resposta 2xx) ou depois, pelo callbackUrl, com variáveis e arquivos.

Quando NÃO precisa de conector

Quando o sistema de destino é construído para conversar com o Autoflow: ele aceita o POST, confere a assinatura e, se for o caso, chama o callbackUrl. É o caso de sistemas internos que a TI do cliente pode adaptar, ou de parceiros que implementam o contrato do Autoflow. O despachante do pacote Concessionária (parceiro gerenciado) é um exemplo: o Autoflow já sabe falar com ele.

Exemplo de conector (Node.js)

Um conector mínimo, para você mostrar à TI do cliente. Ele recebe o pedido, confere a assinatura, responde 202, faz a busca e devolve pelo callback.

// conector-juridico.js — exemplo didático (Node 22+, Express)
import express from 'express';
import crypto from 'node:crypto';

const app = express();
app.use(express.raw({ type: 'application/json' })); // precisa do corpo BRUTO para conferir a assinatura

const WEBHOOK_SECRET = process.env.AUTOFLOW_WEBHOOK_SECRET; // whsec_… da integração no Autoflow
const AUTOFLOW_API_KEY = process.env.AUTOFLOW_API_KEY;      // pf_… da mesma integração (para o callback)

function assinaturaValida(req) {
  const header = req.get('X-ProcessFlow-Signature') || '';            // "t=1761220800,v1=abc…[,v1=…]"
  const parts = Object.groupBy(header.split(','), (p) => p.split('=')[0]);
  const t = Number(parts.t?.[0]?.split('=')[1]);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;       // mais de 5 min: recusa
  const esperado = crypto.createHmac('sha256', WEBHOOK_SECRET).update(`${t}.${req.body}`).digest('hex');
  return (parts.v1 || []).some((p) => {
    const v = Buffer.from(p.split('=')[1] ?? '', 'hex');
    return v.length === 32 && crypto.timingSafeEqual(v, Buffer.from(esperado, 'hex'));
  });
}

app.post('/consultas/processos-por-parte', async (req, res) => {
  if (!assinaturaValida(req)) return res.status(401).end();
  const pedido = JSON.parse(req.body);
  if (!pedido.parte?.documento) return res.status(422).json({ erro: 'documento obrigatório' }); // 4xx = recusa

  res.status(202).json({ recebido: pedido.pedido }); // responde já; o trabalho vem depois

  const processos = await buscarNosTribunais(pedido.parte.documento, pedido.tribunais); // usa as credenciais DO TRIBUNAL
  const contra = processos.filter((p) => p.poloPassivo.includes(pedido.parte.documento));

  await fetch(pedido.callbackUrl, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${AUTOFLOW_API_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': `retorno-${pedido.pedido}`,
    },
    body: JSON.stringify({
      exchangeId: pedido.pedido,
      variables: {
        processosEncontrados: processos.length,
        processosContraCliente: contra.length,
        resumoBusca: contra.map((p) => `${p.numero} (${p.tribunal})`).join('; ') || 'Nada contra o cliente',
      },
    }),
  });
});

app.listen(8080);

Montando o corpo do pedido: o template

Por padrão, o Autoflow envia um corpo com tudo (id da troca, dados do processo, todas as variáveis públicas, links dos documentos). Quando o sistema de destino espera um formato específico, você escreve um template no campo Template do payload do bloco, usando {{ caminho }}. Experimente:

Síncrono ou assíncrono? Como escolher

A decisão mais comum na modelagem é entre o padrão 1 (enviar e seguir) e o padrão 2 (enviar e aguardar). Use esta regra:

Quando dá errado

Integração falha. O outro sistema cai, recusa dados ou demora. O Autoflow tem um comportamento definido para cada caso. Clique nos cenários:

Configurando no Autoflow, passo a passo

1. Crie a integração. Administração › Configurações › Integrações › Nova integração (cargo de escopo Grupo com integration.manage). No assistente: tipo, nome, processos liberados e unidade padrão, chave de acesso (pf_…, aparece uma única vez: entregue ao conector com segurança) e webhook (URL + segredo whsec_…, que também assina as ações).
2. Informe a “URL base das ações”. Na aba Webhook da integração. É o endereço do conector (HTTPS, acessível pela internet). O bloco Enviar soma o caminho a essa base.
3. Teste e ative. O último passo do assistente faz um ping assinado e mostra um exemplo em curl.
4. No fluxo, coloque o bloco “Enviar a sistema externo”. Escolha a integração, o caminho (ex.: /consultas/processos-por-parte), o template do payload e a variável de resultado.
5. Se for esperar resposta: preencha Mensagem de retorno (ex.: resultado-tribunais), coloque o bloco Aguardar retorno externo com a mesma mensagem e um timer de cobrança. Habilite os desfechos que o conector pode mandar.
6. Trate a recusa: preencha Código de erro para 4xx e coloque um evento de borda de erro com esse código.
7. Publique e acompanhe. Cada chamada aparece em Integração › Trocas (pedido, resposta, status) e na linha do tempo do processo. Webhooks enviados aparecem em Entregas, com reenvio.

Levantamento de uma integração com o cliente

Antes de prometer prazo, levante estes pontos. A maioria dos atrasos em integração vem de uma pergunta que não foi feita no começo.

Resumo

• Cinco padrões: enviar e seguir, enviar e aguardar retorno, sistema inicia processo, webhook de eventos e tarefa dentro de outro sistema (SSO).
• O bloco Enviar sempre faz POST JSON assinado para a URL da integração. APIs de terceiros com autenticação e formato próprios precisam de um conector intermediário.
• Resultado para gateway decidir, consulta lenta ou retorno com arquivos: use enviar e aguardar. As variáveis do callback viram variáveis do processo.
• Use template de payload para mandar só o necessário (formato certo e LGPD).
• Sempre: prazo de cobrança em toda espera e código de erro para 4xx com caminho de correção.