Integrar a API de uma transportadora num site próprio: as quatro chamadas que importam e os erros que se repetem

Publicámos conectores de MRW, SEUR, Correos Express, DHL, GLS, UPS e CTT para Odoo e integrámos transportadoras em sites sem Odoo por trás, como eclipseando.com. As API mudam de nome e de formato, mas o trabalho é sempre o mesmo: quatro chamadas, três ou quatro erros que se repetem e uma decisão de arquitetura que convém tomar antes de escrever a primeira linha. Este artigo é a versão para um site próprio; se a sua loja usa Odoo, a maior parte já está resolvida nos conectores de transportadora.

Antes de programar: a adesão e o ambiente de testes

Nenhuma transportadora lhe dá acesso à sua API por preencher um formulário no site. É preciso um contrato de transporte com um comercial, e daí saem as credenciais: um código de cliente ou assinante, um utilizador e uma palavra-passe ou chave, e por vezes um código de franquia ou de agência. Peça-as desde o primeiro dia e peça também o ambiente de testes, que nem todas têm e nem todas se comportam como a produção. Algumas API continuam a ser SOAP com XML (é o caso histórico de várias transportadoras espanholas); outras são REST com JSON. Não muda o que há a fazer, muda o tempo que custa ler a documentação.

As quatro chamadas

Criar o envio: metade do trabalho é limpar a morada

A chamada de criação é onde se concentram as rejeições. Cada transportadora tem a sua ideia do que é uma morada válida: comprimento máximo da rua, código postal com exatamente cinco dígitos, província como código e não como texto, telefone obrigatório e sem indicativo, e em várias nada fora de ASCII no nome. O que funciona é normalizar antes de chamar: separar rua e número, cortar os campos ao máximo que cada API admite, substituir os acentos quando a API não os aceita e validar que o código postal existe para esse país. E guardar sempre o pedido e a resposta completos, em XML ou JSON, junto da encomenda. Quando um pacote se perde três semanas depois, esse registo é a única prova do que foi enviado.

Seguimento: sondagem com cabeça, ou webhook se existir

Poucas transportadoras avisam por webhook; a maioria tem de ser consultada. A forma correta é uma ação agendada que consulta apenas as expedições abertas, com um intervalo razoável (de hora a hora costuma bastar, mais vezes no dia da entrega), que para quando o estado é final e que respeita os limites da API. Os códigos de evento traduzem-se para um conjunto pequeno de estados próprios: aceite, em trânsito, em distribuição, entregue, incidência, devolvido. Cinco ou seis, não quarenta. E cada mudança de estado dispara o aviso ao cliente, que é para o que se faz tudo isto.

Quando não tem a API porque quem envia é o seu fornecedor

É mais frequente do que parece: vende você, mas o pacote é preparado e enviado por um fornecedor com o seu próprio contrato de transporte. Não tem credenciais, não pode criar o envio nem consultar a expedição. O que quase sempre tem são os e-mails que a transportadora envia para o endereço de contacto a cada movimento. Em eclipseando.com resolvemo-lo assim com a GLS: uma tarefa lê a caixa de correio a cada dez minutos, reconhece os quatro tipos de e-mail (a caminho, em distribuição, em ponto de recolha com data limite, destinatário ausente), extrai o número de expedição e a encomenda a que pertence, e converte cada um num estado e num aviso ao comprador. Os dois últimos são os urgentes: um pacote num ponto de recolha volta ao remetente se ninguém o for buscar, e um cliente que não sabe que está lá não vai.

Os erros que vemos em produção

• Testar apenas contra a sandbox. Várias transportadoras têm um ambiente de testes que aceita o que a produção rejeita. O teste que vale é um envio real para o seu próprio escritório.
• Criar o envio ao confirmar a encomenda no site. Cria-se ao preparar o pacote. Se se criar antes, cada cancelamento é uma expedição fantasma que por vezes é faturada.
• Não guardar o pedido e a resposta. Sem o XML ou JSON completos junto da encomenda, uma reclamação é a sua palavra contra a da transportadora.
• Um único número de seguimento por encomenda. Funciona até à primeira encomenda com dois volumes ou dois fornecedores. O seguimento modela-se por envio.
• Certificados e cifragem antigos. Algumas API continuam em TLS com cifras que as bibliotecas modernas rejeitam por defeito. Deteta-se no primeiro dia, não no da entrada em produção.

Com Odoo por trás, quase nada disto se programa

Se a loja usa Odoo, as quatro chamadas já estão escritas nos conectores que publicamos na App Store de Odoo, testados em Odoo 19, 18 e 17 sobre Odoo.sh real: a etiqueta sai ao validar a guia de remessa, o seguimento é consultado por ação agendada e escrito na guia, o manifesto fecha-se a partir do próprio Odoo e o aviso ao cliente sai por e-mail ou SMS com o modelo que quiser. O site só tem de ler o estado da guia. Por isso, quando alguém nos pede para integrar uma transportadora num site e já tem Odoo, a resposta costuma ser ligar o site ao ERP, não voltar a escrever a integração.

Perguntas frequentes

Ligações úteis dentro da FlexigoTech

O que fazemos sobre isto