TOTVS iPaaS - Como mitigar e prevenir erros de Read Timeout em integrações

Dúvida

Ambiente

Causa

Sugestões

1. Liberação de IPs no Firewall (Premissa Primordial de Infraestrutura)
   Antes de qualquer ajuste no diagrama, assegure a comunicação de rede entre a plataforma e o destino. Se a API de destino, firewalls, gateways ou WAFs bloquearem ou descartarem silenciosamente (drop) os pacotes originados pelo TOTVS iPaaS, a conexão permanecerá pendente até o limite de tempo (Read Timeout). Certifique-se de liberar os intervalos da Lista de IPs Oficiais do TOTVS iPaaS.

   
    

2. Fragmentação de Carga de Dados (Redução de Latência por Lote)
   Utilize o componente Splitter no fluxo para fatiar requisições volumosas em mensagens menores ou itens individuais antes de disparar as chamadas HTTP/REST. Cada item é processado de forma rápida e independente, reduzindo o tempo de resposta do servidor de destino e prevenindo o estouro do limite de conexão.

   
    

3. Paginação Dinâmica e Controle de Cursors
   Em rotinas de extração contínua (como busca de pedidos ou estoque), evite buscar todo o volume de dados em uma única requisição. Estruture um fluxo de paginação utilizando o componente Data Storage para armazenar e controlar o estado do cursor (page, pageSize, date), o gatilho Timer para agendamento e chamadas síncronas/subfluxos via Webhook Síncrono ou Diagram Caller. Isso reduz a carga no sistema de origem, obtendo blocos limitados a cada execução.

   
    

4. Inversão do Modelo de Comunicação (Assincronismo/Event-Driven)
   Substitua o modelo de polling síncrono por uma arquitetura orientada a eventos utilizando o Webhook Assíncrono como gatilho de entrada. A aplicação de origem faz a requisição, o TOTVS iPaaS retorna a confirmação de recebimento imediatamente e encerra a conexão HTTP. A regra de negócio é processada em segundo plano sem manter sockets TCP abertos ou pendentes.

   
    

5. Amortecimento de Picos via Mensageria (Buffer de Fila)
   Posicione o componente Message Broker entre o ponto de entrada da integração e as chamadas externas aos sistemas ERP ou Cloud. O componente atua como um intermediário de mensagens assíncronas que retém as requisições em buffer caso o sistema de destino enfrente lentidão ou degradação temporária, evitando devolver timeout para a aplicação cliente.

   
    

6. Subfluxo Isolado de Fallback e Tratamento Centralizado de Exceções
   Para evitar que erros de tempo limite causem efeito dominó ou retenham o pipeline, adicione o componente Global Error ao diagrama. Ao capturar a exceção (message, code, stackTrace), o fluxo é desviado para uma rotina isolada onde o componente Generator formata os dados para registro de log ou aciona rotas alternativas sem derrubar a execução principal.

   
    

7. Modularização de Diagramas em Micro-Etapas
   Evite diagramas monolíticos que encadeiam transformações pesadas e múltiplas chamadas de APIs em sequência. Subdivida a integração em micro-diagramas acionados pelo componente Diagram Caller. Isso desacopla o ciclo de vida das etapas: caso um serviço específico sofra timeout, apenas aquele subfluxo granular falhará, simplificando a identificação do gargalo.

   
    

8. Filtragem e Limpeza Prévia de Payload (Payload Minimization)
   O tamanho do corpo da requisição afeta diretamente o tempo de tráfego na rede e o parsing do servidor de destino. Utilize os componentes JavaScript ou Jolt para remover atributos desnecessários, arrays nulos ou metadados redundantes antes da requisição externa. Um payload enxuto reduz o tempo de resposta da API de destino.

   
    

Informação / Atenção:

• Global Error: O componente suporta no máximo 1 instância por diagrama, não pode ser inserido dentro de subfluxos (como o Splitter) nem em fluxos iniciados por Webhook Síncrono.

  
   

• Data Storage: O limite máximo por tenant é de 200 chaves únicas e o tamanho limite do valor por chave é de 1 MB.

  
   

• Reprocessamento: Apenas integrações que utilizam o Webhook Assíncrono como nó inicial de entrada suportam reprocessamento manual ou em lote pelo Monitor.