AutoflowGuia do implantador
0 / 60
Buscar

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

Integrações e conectores

Quase todo cliente tem um ERP, um sistema de protocolo ou um parceiro externo. O Autoflow conversa com eles em quatro níveis — de "o ERP abre um processo" até "o processo chama o parceiro e espera a resposta". Entenda cada nível, como configurar e como desenhar o fluxo para tratar o que pode dar errado.

Esta lição é o mapa; as duas seguintes são a prática

Aqui você vê os níveis e as telas de configuração. Em Padrões de integração na prática estão os cinco padrões com os JSONs reais, o conceito de conector intermediário, um laboratório de template e um simulador de erros. Em Exemplos estão processos completos: jurídico (busca em tribunais, intimações), órgão público (alvará, dívida ativa, diário oficial) e empresas (ERP, crédito, assinatura eletrônica).

Os níveis de integração

Nível O que faz Estado
N1 Genérico Sistema externo inicia processos pela API e recebe eventos por webhook pronto
N2 Participação Sistema externo envia mensagens a processos em andamento; usuários do ERP fazem tarefas do Autoflow por SSO, dentro do ERP (embed) pronto
N3 Ação O processo chama o sistema externo (blocos Enviar / Aguardar retorno) pronto (HTTP genérico)
N4 Provider específico Conectores prontos (Slack, CRM…) com OAuth futuro
Parceiro gerenciado Integração configurada pela plataforma; o cliente só Habilita (ex.: despachante) pronto, segmento Concessionária
Por que integrar?

Toda redigitação entre sistemas é custo, atraso e risco de erro. Uma venda faturada no ERP que precisa ser digitada de novo para abrir o emplacamento é exatamente o tipo de desperdício que o cliente quer eliminar. Integração também dá rastreabilidade ponta a ponta: a mesma referência (número do pedido) liga o ERP, o processo e o parceiro.

Configurar uma integração

Administração › Configurações › Integrações — exige cargo de escopo Grupo com integration.read (ver) e integration.manage (criar/editar).

Nova integração é um assistente de 6 passos:

  1. Tipo.
  2. Identificação (nome, descrição).
  3. Processos e unidade: quais fluxos este sistema pode iniciar, a unidade padrão e as filiais permitidas.
  4. Chave de acesso: a API key (pf_…) aparece uma única vez. Copie para um cofre de senhas do cliente.
  5. Webhook: URL (HTTPS obrigatório, IP privado bloqueado) e o secret whsec_…. Aviso da tela: ele recebe “todos os eventos, incluindo as variáveis”.
  6. Testar e ativar: envia um ping assinado e mostra exemplo em curl.

O detalhe da integração tem abas: Visão geral (inclui “Acesso de usuários (SSO)”), Chaves (rotação; o secret anterior vale 24h), Processos e unidade, Webhook (“URL base das ações”), Entregas (Pendente, Entregue, Falhou, Morta, com reenvio), Requisições, Trocas (Enviando, Aguardando retorno, Retorno recebido, Concluída, Falhou) e Auditoria. Status: Rascunho, Ativa, Desativada, Com erro, Excluída.

Na mesma área, Integrações prontas mostra os parceiros gerenciados (com “Instalação”, Habilitar/Desabilitar e “Código de vínculo”) e Domínios de imagem lista os hosts permitidos para a imagem da instância (até 20, com curinga *.).

N1 — API pública e webhooks

API pública (/public/v1), autenticada pela API key:

  • POST process-instances — inicia um processo (com variáveis, unidade por branchId ou branchCnpj, e opcionalmente participantes externos);
  • GET process-instances e GET process-instances/:ref — consulta; :ref/timeline — linha do tempo;
  • POST process-instances/:ref/messages — envia mensagem a um processo (N2).

Limites: 60 requisições/min (pico 120), corpo de 1 MB, cabeçalho Idempotency-Key guardado por 24h (o mesmo pedido enviado duas vezes não abre dois processos).

Webhooks enviados pelo Autoflow:

  • eventos process_instance.*, task.*, incident.*, document_request.*, exchange.cancelled, exchange.return_rejected;
  • assinatura X-ProcessFlow-Signature: t=…,v1=HMAC-SHA256 — o sistema do cliente deve validar e rejeitar mensagens com mais de 5 minutos;
  • até 8 tentativas com espera crescente; erro 4xx (exceto 408/429) não é retentado; esgotou → “morta”. Mais de 20 mortas em 1h → integração vai para Com erro, pausa e notifica;
  • variáveis sensíveis (prefixo _ ou marcadas sensíveis) não vão no payload; arquivos só como metadados; teto de 256 KB.
Atenção

pendente A assinatura de webhook recebe todos os eventos (os filtros existem no banco mas não na tela). Oriente o sistema do cliente a ignorar o que não interessa. Também não há documentação pública com sandbox (Swagger) nem upload de arquivo no início do processo.

N3 — O processo chama o parceiro

O exemplo clássico: depois que os documentos são aprovados, o Autoflow envia o pedido ao despachante, espera o CRLV e valida o documento recebido.

SequênciaERP → Autoflow → despachante → de volta
ERPAutoflowDespachanteUsuário1. POST /public/v1/process-instances2. Webhook process_instance.started3. Solicitação de documentos4. Enviar a sistema externo5. HTTP 202 aceito6. Aguardar retorno externo7. Retorno: completed + CRLV8. Validar CRLV9. Webhook process_instance.completed
Clique em Reproduzir ou em qualquer mensagem do diagrama.

Bloco “Enviar a sistema externo” — campos

Campo Para que serve
Integração Qual integração cadastrada usar
Caminho Caminho relativo na URL base das ações (ex.: /processos)
Mensagem de retorno Nome da mensagem que o bloco de espera aguarda
Validar retorno com o requisito / Documentos do retorno Como tratar documentos que voltam (um ou outro)
Documentos (links) Quais documentos enviar por link temporário
Variável de resultado Guarda {status, body} da resposta
Código de erro para 4xx Transforma recusa em erro BPMN tratável
Template do payload JSON com {{ vars.x }}, {{ process.number }}, {{ documents.TIPO.url }}

Desfechos do retorno

Habilite no bloco os desfechos que o parceiro pode devolver: “Aceitar recusa”, “Aceitar cancelamento”, “Aceitar pendência”, “Aceitar andamento”, retorno parcial; e os avisos ao parceiro (“Avisar encerramento do processo”, “Avisar reprovação do retorno”). O retorno grava integrationOutcome (COMPLETED, REJECTED, CANCELLED, NEEDS_CORRECTION), integrationOutcomeReason e integrationOutcomeItems.

Quem decide o caminho é o BPMN

O bloco só registra o que o parceiro disse. Um gateway logo depois da espera decide o que fazer com cada desfecho. Se você habilita “Aceitar recusa” e não testa integrationOutcome em nenhum gateway, o validador avisa (integration.outcomeNotRouted) — porque a recusa seguiria pelo caminho feliz.

Veja o fluxo de demonstração do despachante (versão mais simples, anterior aos desfechos genéricos):

N2 — SSO com o ERP e tarefas dentro do ERP

Para o usuário fazer tarefas do Autoflow sem sair do ERP:

  1. No Keycloak (realm do produto), crie um client por sistema: confidencial, Standard flow, PKCE S256, sem Direct access grants e sem Service accounts, redirect exato, com o scope padrão que traz o público da API e o tenant.
  2. No Autoflow, na integração, aba Visão geral › Acesso de usuários (SSO): informe o “Client OIDC” e as “Origens autorizadas para embed”.
  3. Usuários do ERP são os mesmos do Autoflow: precisam ter vínculo na unidade, e a unidade precisa estar nas filiais permitidas da integração.
  4. Erros comuns: 401 invalid_token (falta audience), 401 delegated_access_not_enabled, 403 unit_not_allowed, 403 embed_origin_not_allowed.
Para treinar sem cliente

O repositório tem dois sistemas de exemplo: um “ERP” que inicia a venda pela API, recebe webhooks e mostra “Minhas tarefas” com SSO, e um “despachante” que recebe o pedido e devolve o CRLV (com modos aceitar, recusar e falhar). Peça à equipe técnica para subir os dois em homologação e faça o ciclo completo — é o melhor treino de integração.

Como conduzir a integração com o cliente

  1. Mapeie os pontos de contato no TO-BE: onde o processo começa por outro sistema? Onde precisa avisar alguém? Onde espera resposta?
  2. Escolha o nível: só abrir processo e ser avisado (N1)? Mandar eventos no meio (N2)? O processo chamar o parceiro (N3)?
  3. Feche o contrato de dados com o time de TI do cliente/parceiro: campos, formatos, referência externa, desfechos possíveis, prazos de resposta.
  4. Modele os caminhos de erro antes do caminho feliz: recusa, pendência, cancelamento, silêncio (timer).
  5. Teste em homologação com o sistema real do parceiro, incluindo falhas.

Resumo

  • N1: API para iniciar e webhooks assinados para avisar; N2: mensagens e SSO/embed; N3: blocos Enviar/Aguardar; N4: futuro.
  • A API key aparece uma vez; webhooks exigem HTTPS e são retentados até 8 vezes.
  • O retorno do parceiro vira integrationOutcome; um gateway decide o caminho.
  • Modele recusa, pendência, cancelamento e silêncio antes de ir para produção.
QuizVerifique seu entendimento0/4 respondidas · 0 certas
1.O ERP precisa abrir um processo quando a venda é faturada. Qual nível?
2.O despachante pode responder "falta comprovante". O que precisa existir no fluxo?
3.O ERP enviou duas vezes a mesma venda por falha de rede. Como evitar dois processos?
4.Sem "Código de erro para 4xx", o que acontece quando o parceiro recusa os dados?
AnteriorPortal do participante externo