Etiquetas e seguimento automáticos no Odoo: do picking validado ao e-mail do cliente

Ao validar uma guia com transportadora, o Odoo automatiza quatro coisas: a chamada à API, a etiqueta PDF anexada à guia, o número de seguimento em carrier_tracking_ref e o e-mail ou SMS ao cliente com esse número. Não automatiza a recolha física nem a verdade do peso e dos volumes. Aqui fica o fluxo com o modelo do Odoo de cada passo e o código dos nossos conectores de Correos Express e MRW, que usamos no nosso próprio armazém. Sem Odoo por trás, o mesmo está em integrar a API de uma transportadora num site próprio.

O que é preciso antes

• Contrato e credenciais do ambiente correto. A Correos Express separa teste (www.test.cexpr.es) e produção (www.cexpr.es); a MRW usa o serviço web Sagec com franquia, assinante, departamento, utilizador e palavra-passe. Ambos trazem um botão de teste de ligação (action_cex_test_connection e action_mrw_test_connection) para o verificar antes do primeiro envio real.
• Morada normalizada. Nome, rua, localidade, código postal de cinco dígitos em Espanha e telefone com pelo menos nove dígitos, no remetente e no destinatário: a lista literal de _cex_validate_shipment_inputs.
• Peso e volumes na guia. Os módulos leem os pacotes (package_level_ids / package_ids) ou, se não existirem, um volume com shipping_weight ou weight. Peso zero não sai.
• Tipo de operação com «Imprimir etiqueta». No Odoo 19, a chamada automática ao validar só ocorre com print_label ativado. É a causa mais comum de «validei e não aconteceu nada».

O fluxo passo a passo, com o modelo do Odoo em cada passo

1. Validar (stock.picking._action_done). O Odoo 19 chama _send_confirmation_email, que stock_delivery reescreve: com transportadora rate_and_ship, ainda sem tracking e um tipo de operação que imprime etiqueta, executa send_to_shipper() antes de compor o e-mail.
2. Chamar a API (delivery.carrier.send_shipping). O Odoo encaminha para cex_send_shipping ou mrw_send_shipping: JSON contra apiRestGrabacionEnviok8s/json na Correos Express, SOAP TransmEnvio contra sagec.mrw.es na MRW. Se já existia número de envio, devolve-se o existente.
3. Guardar a etiqueta (ir.attachment). O PDF é anexado à guia como Etiqueta_CEX_<número>.pdf ou Etiqueta_MRW_<número>.pdf e publicado no chatter. Com vários volumes, a Correos Express devolve várias etiquetas com sufixo _01, _02…
4. Escrever o tracking (carrier_tracking_ref). send_to_shipper toma tracking_number da resposta, escreve-o no campo padrão e publica «Paquete enviado al transportista … con número de rastreo …». Os módulos guardam também o seu número próprio.
5. Avisar o cliente (mail.template / sms.template). stock envia «Shipping: Send by Email» se a empresa tiver ativada a confirmação por e-mail, e stock_sms o SMS. Ambos incluem o tracking apenas se carrier_tracking_ref já estiver preenchido.

Validar antes de chamar: o que se verifica e o que devolve a transportadora se não

A transportadora valida, mas tarde e com mensagens para a sua equipa. Os módulos verificam primeiro no Odoo e só chamam se não houver erros; se os houver, um único UserError com todos. Se mesmo assim rejeitar, a resposta é classificada por palavras-chave e traduzida numa frase para o operador; o administrador vê o detalhe técnico.

Novas tentativas: uma falha silenciosa é pior do que uma visível

Um 503 em plena preparação de encomendas não é raro. Deixar a guia a meio é a pior resposta; engolir o erro, a segunda. Os módulos fazem uma terceira: decidir se a falha é transitória e repetir com espera crescente.

• Transitório na Correos Express é HTTP 408, 409, 423, 425, 429, 500, 502, 503 ou 504, ou uma mensagem com «timeout», «vuelva a intentarlo», «service unavailable» ou «error interno»; a MRW usa uma lista mais curta: 408, 429, 500, 502, 503 e 504. O resto é erro de dados: é marcado e mostrado.
• Na guia ficam cex_retry_pending, cex_retry_count, cex_retry_next_attempt, cex_last_error_message e cex_last_attempt_at (na MRW, prefixo mrw_), e no chatter «CEX temporalmente no disponible. Reintento automático #1 programado para …».
• Uma ação agendada a cada 5 minutos recolhe os pendentes sem número de envio com a hora cumprida, de 50 em 50, e passa-os pelo mesmo código da primeira tentativa.
• Espera: 5, 15, 30, 60, 120 e 240 minutos na Correos Express; 5, 15, 30, 60, 180 e 360 na MRW. Seis tentativas por defeito, configurável. Ao esgotá-las, «Se alcanzó el máximo de reintentos automáticos»: aí é preciso uma pessoa.
• Quem se apercebe: o operador, no erro e no chatter. O Odoo 19 acrescenta a sua rede: se num lote já se processou uma guia na transportadora, o erro seguinte não reverte o lote; converte-se numa atividade de aviso.

O fragmento que fixa a espera, no módulo da Correos Express:

# flexigobe_correos_express/models/delivery_carrier.py (v19.0.3.0.19)
CEX_RETRY_BACKOFF_MINUTES = [5, 15, 30, 60, 120, 240]

def _cex_retry_delay_minutes(self, attempt_no):
    self.ensure_one()
    idx = max(int(attempt_no or 1) - 1, 0)
    if idx >= len(CEX_RETRY_BACKOFF_MINUTES):
        idx = len(CEX_RETRY_BACKOFF_MINUTES) - 1
    return CEX_RETRY_BACKOFF_MINUTES[idx]

O e-mail ao cliente: quando se dispara e o que leva

Dispara-se ao validar, não ao criar a guia. O modelo padrão («Shipping: Send by Email», em Inventário → Definições → Confirmação por e-mail) diz «Nos alegra informarle de que su pedido ha sido enviado» e, se existir carrier_tracking_ref, acrescenta a referência com ligação para carrier_tracking_url; o SMS de stock_sms acrescenta o número de encomenda (object.origin) e a referência em texto simples, sem ligação. Como stock_delivery chama send_to_shipper antes de super()._send_confirmation_email(), o tracking já existe ao compor o e-mail. Se o envio ficou em fila de repetição, o e-mail sai sem tracking.

A ligação é construída por cada módulo: https://s.correosexpress.com/SeguimientoSinCP/search?n=<tracking> na Correos Express e https://www.mrw.es/seguimiento_envios/MRW_historico_nacional.asp?enviament=<número> na MRW. Tracking sem ligação significa que ainda não há referência.

Caso: os dois módulos próprios e em que diferem

Partilham arquitetura e são mantidos para o Odoo 19, 18 e 17. As API diferem, e nota-se na etiqueta, na anulação e no que não fazem.

Nenhum gere hoje a cobrança na entrega, e perguntam-nos muito por isso. Mais em Correos Express no Odoo e MRW no Odoo; se ainda está a escolher, que transportadora se adequa a um ecommerce no Odoo.

Como verificar que funciona

Não com o sandbox: com uma guia real validada e estas quatro evidências, as das capturas.

1. Um anexo Etiqueta_CEX_…pdf ou Etiqueta_MRW_…pdf com código de barras legível. O da MRW olha para o cabeçalho do binário (%PDF-, ^XA, <?xml, <html) e, se não for etiqueta imprimível, não a guarda: di-lo no chatter.
2. carrier_tracking_ref preenchido e «Etiqueta OK» com o número de envio.
3. No chatter: «Paquete enviado al transportista…», «Etiqueta … generada correctamente» com o PDF, e o SMS ou e-mail ao cliente se estiverem ativados.
4. Campos de repetição a zero. Se não, o envio não chegou à transportadora embora a guia esteja validada.

Com uma transportadora sem módulo publicado, o mesmo fluxo e outro adaptador: dentro do serviço de logística no Odoo e, para consultoras, como engenharia para consultorias. A regra dos nossos serviços é a mesma: a etiqueta sai da guia, o tracking volta à guia e ninguém copia nada.

Perguntas frequentes

Ligações úteis dentro da FlexigoTech

O que fazemos sobre isto