Sincronização automática com o armador e pendências de conversão
Quando o armador manda os eventos por arquivo EDI ou por API, o booking e o embarque entram sozinhos no Hap. Mas cada mensagem só entra se o sistema souber traduzir o cliente e os portos que vieram nela. Este guia explica como a sincronização funciona, por que uma mensagem vira falha e como usar a tela Pendências de Conversão para resolver o que está travado e recuperar o histórico.
Quando usar
Use quando bookings pararem de aparecer, quando a lista de embarques estiver cheia de linhas com situação Falha, ou periodicamente — vale abrir a tela de pendências uma vez por semana para não deixar acumular.
Antes de começar
- Integração de EDI ou API configurada com o armador.
- Cadastro de portos com a sigla (código UN/LOCODE) preenchida.
- Acesso ao menu Frete Marítimo > Pendências de Conversão.
Como a sincronização funciona
Existem dois caminhos automáticos, e eles convivem. Nos dois, o dado passa pela mesma validação de conversão antes de virar registro.
- 1
EDI por arquivo — o armador deposita arquivos numa pasta de FTP. Um serviço do Hap lê essa pasta a cada dois minutos, traduz cada arquivo em mensagens e envia ao sistema.
- 2
API do armador — um serviço consulta o armador periodicamente e traz rastreio de contêiner, conhecimento de embarque, sobrestadia e faturas.
O que cada mensagem traz
Uma mensagem de EDI é um evento de um contêiner: número do booking, contêiner, navio, viagem, portos, número do conhecimento de embarque e um código de status. É esse código que vira o texto que você lê na tela.
O status mais importante é o de partida do porto de embarque: é ele que faz o booking virar embarque. A mensagem também informa a versão do booking — original, substituição ou cancelado —, e a substituição cancela a versão anterior e cria a nova.
Por que uma mensagem vira falha
A mensagem chega com o vocabulário do armador. Para virar registro, ela precisa ser traduzida: o nome do cliente tem que encontrar um cadastro, e o porto de origem e o de destino também. Quando alguma dessas traduções não acontece, a mensagem é gravada com situação Falha e o motivo fica no log da linha.
Usando a tela Pendências de Conversão
A tela mostra os valores que o armador enviou e o Hap não soube traduzir, agrupados e ranqueados por quantas mensagens cada um já custou.
- 1
Abra Frete Marítimo > Pendências de Conversão e escolha o período (o padrão é 90 dias).
- 2
Leia a coluna Mensagens perdidas: ela diz o tamanho do problema. Comece de cima.
- 3
O valor aparece em fonte monoespaçada, exatamente como o armador enviou. É esse texto literal que precisa ser cadastrado.
- 4
Clique em Cadastrar de-para. O valor já vem preenchido e travado; você só escolhe o cliente ou o porto correspondente.
- 5
Repita para os valores mais frequentes. Não precisa resolver todos de uma vez.
- 6
Ao terminar, clique em Reprocessar falhas.
O reprocessamento
Reprocessar falhas pega as mensagens em falha do período e valida cada uma de novo, com os cadastros que existem agora. As que passam a ser traduzidas voltam para a situação Importado e entram normalmente na operação; as que continuam com problema permanecem em falha, com o log atualizado.
É uma ação segura de repetir: ela não cria registros novos, apenas revalida os que já existem.
Problemas comuns
- Pararam de chegar bookings novos: confira primeiro se o armador continua depositando arquivos. Se a data da última mensagem estiver parada há dias, o problema é na entrega, não no Hap.
- O mesmo porto aparece duas vezes na lista de pendências, uma com o nome e outra com um código de quatro ou cinco letras: são a mesma coisa. Cadastre a sigla no cadastro de Porto e o Hap passa a reconhecer as duas formas sozinho.
- O nome do cliente aparece com um trecho estranho colado no fim: é sujeira do arquivo do armador. O Hap já corta isso antes de traduzir; se ainda aparecer assim na lista, cadastre o valor exatamente como está mostrado.
- Cadastrei o de-para e as linhas continuam em Falha: o cadastro vale para as mensagens novas. Para as antigas, use o botão Reprocessar falhas.
- Reprocessei e algumas continuam em falha: elas têm mais de um problema. Abra a linha na tela de Embarques e leia o log, que lista todos os motivos.
- Aparece um número de pedido ou uma referência no lugar do nome do cliente: o armador mandou o campo trocado naquela mensagem. Cadastre esse valor apontando para o cliente certo, ou peça a correção ao armador.