Enviar com a MRW a partir do Drupal Commerce: adeus copy-paste para o portal da transportadora

Várias das lojas de e-commerce que construímos e gerimos enviam com a MRW, uma das principais transportadoras de Portugal e Espanha. Até há pouco tempo, expedir uma encomenda significava sair da loja: abrir o portal de clientes da MRW, voltar a escrever a morada do cliente, imprimir a etiqueta e copiar o número do envio de volta para o Drupal, para o cliente ter um link de seguimento. Multiplique-se por todas as encomendas, todos os dias, e somem-se as devoluções, que obrigavam à mesma dança com as moradas trocadas.

Substituímos isso por um módulo Drupal. Hoje gere a expedição diária da primeira delas, e estamos a disponibilizá-lo à comunidade: o Commerce MRW está no drupal.org, com a release 1.1.0.

O que faz

O Commerce MRW integra o Drupal Commerce com a MRW através do SAGEC, o webservice SOAP da transportadora para criar e gerir envios. Todo o ciclo de expedição acontece nas páginas de administração de shipments que a equipa já usa:

• Transmitir envios (TransmEnvio): um clique cria o envio do lado da MRW e guarda o número devolvido como tracking code do shipment, que alimenta o link de seguimento do cliente.
• Etiquetas on-demand (GetEtiquetaEnvio): o PDF da guia de transporte é transmitido diretamente do SAGEC sempre que alguém o pede. As etiquetas nunca são guardadas localmente: a MRW é a única fonte de verdade e não há problema de ficheiros desatualizados.
• Cancelar (CancelarEnvio) envios transmitidos antes de o estafeta os recolher.
• Recolhas de devolução: o pedido pode levar uma morada de recolha (DatosRecogida), e a MRW recolhe a encomenda à porta do cliente e entrega-a de volta na loja. As devoluções deixam de ser trabalho manual no portal da transportadora.
• Seguimento: um cliente para o webservice TrackingServices da MRW consulta o estado atual, ou o histórico completo, de qualquer envio: pelo número MRW, pela referência da encomenda, individualmente ou em lote.
• "Transmit as": shipments cujo método de envio não é MRW (por exemplo, um "Envio grátis" de tarifa fixa) podem mesmo assim ser expedidos pela MRW. O operador escolhe o método executante na altura de transmitir e a escolha fica registada no shipment.

Os códigos de serviço cobrem o catálogo SAGEC (Ecommerce, Urgente 19 Expedición, Urgente 13 e restantes), e os ambientes PRE (testes) e PRO (produção) têm credenciais separadas e um modo de teste, para validar a integração com a franquia antes de mover um único embrulho real.

Módulo pequeno, arestas afiadas

O manual do SAGEC é curto; a realidade não é. Algumas das arestas que o módulo lima por si:

• Os códigos postais são folclore por país. Espanha quer 5 dígitos com zeros à esquerda, Portugal só os primeiros 4 dos seus códigos de 7 dígitos, as letras de Andorra tornam-se zeros e Gibraltar é sempre 00010. O módulo normaliza tudo antes de o SAGEC ver uma morada.
• O serviço de tracking esconde-se atrás de uma manha do WCF: só aceita pedidos SOAP no endereço relativo do endpoint, e responde 404 no endereço para onde a documentação aponta. Descobrimos para não ter de descobrir.
• Sem extensão SOAP do PHP. Ambos os clientes constroem os envelopes à mão sobre o HTTP client do Drupal, o que também torna cada pedido totalmente testável com respostas simuladas; o módulo traz uma suite de kernel tests que verifica o XML exato que vai para a rede.

As regras da sua loja continuam suas

As integrações com transportadoras morrem por terem o workflow de outra pessoa gravado no código, por isso o Commerce MRW deliberadamente não tem nenhum. Os dados específicos do site viajam num evento: subscreva o evento do pedido TransmEnvio e preencha o que a sua loja souber, o telefone do destinatário, um NIF, observações de entrega para o estafeta, ou uma morada de recolha completa para transformar uma transmissão numa recolha de devolução. Numa das nossas lojas, três subscribers pequenos fazem exatamente isso: um copia o telefone do cliente, outro envia o campo de "notas para a transportadora" do backoffice como instruções de entrega, e outro troca as moradas quando o shipment está marcado como devolução.

O seguimento segue a mesma filosofia. O módulo dá o cliente e uma receita de integração documentada, mas não traz polling nem muda estados de shipments: se o "entregue no destino" deve fazer avançar o seu workflow, ou apenas informar uma pessoa, a decisão é sua. Essa loja corre um cron horário que espelha o último estado MRW no painel de expedição, ao lado de cada tracking code; marcar um envio como entregue continua a ser uma decisão humana, agora informada.

Testado em batalha, depois publicado

Como os nossos outros módulos contrib, este só chegou ao drupal.org depois de gerir a expedição diária de uma loja real: transmissões reais, etiquetas reais entregues ao estafeta, e um cliente de tracking validado contra o webservice de produção antes de a release ser criada. A suite de testes (42 kernel tests à data deste texto) cobre os envelopes SOAP, as regras de códigos postais, os formulários de backoffice e o parsing do tracking.

Como obter

composer require drupal/commerce_mrw:^1.1

Requer Drupal 10.3+ ou 11 e Commerce Shipping 3.x, além de credenciais SAGEC da sua franquia MRW (peça à sua franquia; a nossa ativou o webservice de envios e o serviço de tracking mediante pedido).

Se tem uma loja Drupal Commerce a enviar para Portugal ou Espanha, isto é para si. A issue queue está aberta, e os envios internacionais, etiquetas ZPL e pontos de entrega MRW estão no roadmap.