Como configurar file polling SFTP/FTP

Use file polling quando o parceiro deposita arquivos num servidor (SFTP, FTP, FTPS) e você precisa que o Lefia busque e processe automaticamente.

Configuração obrigatória

Na criação da integração, defina:

• Gatilho: vem da conexão de origem SFTP/FTP — a tela mostra Leitura de arquivos (file_polling), não pergunta
• Source connection: SFTP/FTP/FTPS com credenciais (host, porta, user, senha). O host precisa ser público: se ele (ou o que o DNS devolve para ele) for rede interna, loopback ou endereço de metadata da nuvem, a conexão é recusada por segurança, como nas conexões HTTP
• Poll directory: caminho absoluto do diretório no servidor remoto (ex: /inbound, /edi/orders)
• Poll file pattern: padrão glob dos arquivos a buscar:

- *.xml — qualquer arquivo XML
- INV_*.csv — começa com INV_ e termina em .csv - pedido_???.dat — ? casa exatamente 1 caractere
- ou .* ou vazio — todos os arquivos

• Post-processing: o que fazer com o arquivo depois de processar

- delete — apaga
- archive — move pra subpasta archive/ (criada se não existir)
- none — deixa em paz (cuidado: vai re-listar mesmo arquivo no próximo poll, mas não reprocessa graças à dedup)

Como funciona a dedup

Cada arquivo gera uma idempotency_key no formato file:<filename>:<size>. A constraint unique uq_messages_idempotency_key em (tenant_id, integration_id, idempotency_key) garante que o mesmo arquivo nunca é processado duas vezes — mesmo se duas execuções do cron rodarem em paralelo.

Se o arquivo for substituído por um com mesmo nome mas tamanho diferente, é tratado como novo. Se você precisar dedup por conteúdo, abra um incidente pra adicionar hash SHA-256 no key.

Teste manual

Use dryRun: true pra ver o que casaria sem baixar nem processar:

curl -X POST $BASE_URL/api/mapeamentos/execute-file-poll \
  -H "authorization: Bearer $CRON_SECRET" \
  -H "content-type: application/json" \
  -d '{"integrationId":"<uuid>","dryRun":true}'

A resposta lista cada arquivo encontrado com status: dry_run.

Limites conhecidos

• Arquivos baixam pra memória antes de inserir no banco (Buffer). Ok pra payload EDI/CSV típico (<10MB). Pra arquivos enormes, abrir um incidente pedindo streaming.
• Não suporta polling recursivo em subdiretórios (só o diretório configurado).
• Glob suporta apenas * e ?. Sem **, sem [abc], sem brace expansion.

Arquivo EDI do parceiro (EDIFACT, X12, IDoc)

Quando a integração tem mapeamento e a mensagem de origem é EDIFACT, X12 ou IDoc, o Lefia lê o arquivo na estrutura da mensagem antes de aplicar o mapeamento: segmentos, grupos (por exemplo, cada LIN com os seus QTY e MOA), repetições e posições vêm do catálogo da mensagem, e os separadores vêm do próprio arquivo (UNA/ISA). O envelope (UNB, UNH, ISA, GS, ST…) fica à parte, em _envelope. Um arquivo com várias mensagens vira uma mensagem por documento, cada uma com o trecho exato do arquivo nos dados originais. A 1ª é processada na hora; as outras entram na fila de processamento, que passa a cada 5 minutos e leva até 50 mensagens por vez — um arquivo com 500 documentos termina em cerca de 50 minutos. Arquivo fora da forma da spec fica em erro com a linha e o segmento. Sem mapeamento, o arquivo segue como chegou.