Módulo ViaDireta para Magento 2 · versão 1.0.2

Magento Open Source / Adobe Commerce 2.4.7 ou superior · PHP 8.2 a 8.5 · 0,4 MB

DESCARREGAR MÓDULO

Visão geral

O módulo liga a sua loja Magento à ViaDireta. Cria as expedições a partir das encomendas (e o envio do Magento com o número de seguimento), imprime etiquetas e guias de transporte, pede recolhas ao armazém e mostra o seguimento de cada envio, sem copiar dados à mão.

  • Envio das encomendas para a ViaDireta, uma a uma, em lote ou automaticamente quando a encomenda muda para um estado escolhido.
  • Etiquetas e guias de transporte em PDF, de uma encomenda ou de várias de uma só vez.
  • Vários locais de recolha, associados às fontes de inventário (MSI); se for preciso, a encomenda é dividida num serviço por local.
  • Pedido de recolha e manifesto de carga para os volumes à espera de serem recolhidos.
  • Recolhas e trocas de artigos devolvidos, pedidas a partir da encomenda e associadas à entrega original.
  • Estados de encomenda ViaDireta (Enviada, Em distribuição, Devolvida…), atualizados pelo seguimento.
  • Transportador ViaDireta no checkout, com preço fixo ou por peso e zona, e seguimento na conta do cliente.
O módulo usa só a API pública do Magento: não altera o código da loja e funciona com ou sem fontes de inventário (MSI).

Download e instalação

Antes de começar precisa do utilizador e password da API ViaDireta. Se ainda não os tem, peça-os ao seu gestor ViaDireta ou através dos contactos. A instalação é feita no servidor da loja, por quem gere o Magento.

  1. Descarregue o ficheiro viadireta-magento-v1.0.2.zip (botão acima) e descompacte-o na raiz da loja (fica a pasta app/code/ViaDireta/Shipping).
  2. Na raiz da loja, corra:
    php bin/magento module:enable ViaDireta_Shipping
    php bin/magento setup:upgrade
    php bin/magento setup:di:compile                           # só em modo produção
    php bin/magento setup:static-content:deploy pt_PT en_US    # só em modo produção
    php bin/magento cache:flush
  3. No admin, abra Sales › ViaDireta › Configuração e siga a configuração.

Atualizar para uma versão nova

Substitua a pasta app/code/ViaDireta/Shipping pela da versão nova e repita os comandos do passo 2. A configuração e as expedições mantêm-se.

Desinstalar

Desative o módulo com php bin/magento module:disable ViaDireta_Shipping (ou module:uninstall, numa instalação feita pelo Composer). O que acontece às expedições é escolhido em Ao desinstalar, no separador API.

Configuração

A configuração está em Sales › ViaDireta › Configuração e tem quatro separadores. Guarde com Guardar configuração. A ajuda de cada campo está no ? ao lado do nome.

1. API: ligação e modo

  1. Preencha o Utilizador API e a Password API e carregue em Associar / testar ligação. O módulo confirma as credenciais, lê as contas a que dão acesso e traz os locais de recolha.
  2. Escolha o Modo: Testes usa a conta de testes da ViaDireta, para experimentar sem criar envios reais; Produção usa a sua conta.
  3. Confirme que o Estado está Ativo e guarde.
Separador API da configuração ViaDireta
Separador API: estado, credenciais, modo de testes / produção e registo de depuração.
Em modo de testes, as expedições ficam marcadas com TESTE e não contam como “já enviadas”: quando passar para produção pode enviar essas encomendas normalmente.

2. Expedição: contas, locais de recolha e valores por omissão

  • Contas ViaDireta: conta usada nas entregas e, se tiver, contas próprias para recolhas e para trocas.
  • Locais de recolha: os armazéns e lojas da sua conta, trazidos com Sincronizar com a ViaDireta. Com várias fontes de inventário (MSI), escolha que fontes saem de cada local (ou da Morada da conta); cada fonte só pode estar num local. Escolha também o local por omissão. Para ter mais locais de recolha, peça ao suporte ViaDireta: dsii@viadirectanet.pt.
  • Encomendas com artigos de vários locais: dividir num serviço por local ou enviar tudo do mesmo local. Numa encomenda dividida, a cobrança vai toda no primeiro serviço.
  • Valores por omissão das expedições: documento a imprimir (etiqueta ou guia de transporte), data do serviço em dias úteis (nunca para o próprio dia, fins de semana ou feriados nacionais) e peso por omissão.
Separador Expedição
Separador Expedição: contas e locais de recolha com as fontes de inventário.

3. Automação: envio automático, estados e avisos

  • Estados prontos para envio e Enviar automaticamente (desligado numa instalação nova): a expedição é criada sozinha quando a encomenda passa para um desses estados. Pode limitar às encomendas com o transportador ViaDireta.
  • Estado da encomenda após envio (por omissão Enviada), Criar a remessa do Magento (o envio com o número de seguimento) e Notificar o cliente por email.
  • Estados mostrados na lista de expedições.
  • Estados de encomenda ViaDireta e o estado da encomenda em cada fase do seguimento; devoluções.
  • Atualizações da ViaDireta (webhook) e seguimento para o cliente.
Separador Automação
Separador Automação: estados prontos para envio, envio automático e remessa do Magento.
Separador Automação: devoluções, webhook e cliente
Separador Automação: devoluções, webhook e seguimento para o cliente.

4. Checkout: o transportador ViaDireta

  • Preço dos portes: preço fixo ou por peso e zona, com escalões “até X kg → preço” para Portugal Continental, Açores e Madeira (pelo código postal) e restantes países, com tabelas país a país se quiser; portes grátis a partir de um valor e peso máximo.
  • Ative o transportador, escolha o nome e os países em Stores › Configuration › Sales › Delivery Methods › ViaDireta.
Separador Checkout
Separador Checkout: tarifas por peso e zona.

Local de recolha do produto

Ao editar um produto, no grupo ViaDireta, o atributo Local de recolha (ViaDireta) escolhe de onde sai: Automático (pela fonte de inventário associada no separador Expedição), a morada da conta ou um dos locais de recolha. Sem escolha, sai do local por omissão.

Atributo Local de recolha (ViaDireta) no produto
Produto: grupo ViaDireta com o Local de recolha.

Expedições ViaDireta

Em Sales › ViaDireta › Expedições ViaDireta tem as encomendas com os produtos (e o local de cada um), o destino, o envio e pagamento, o estado e os envios ViaDireta de cada uma. As vistas Todos / Por enviar / Enviadas / Com erro, a pesquisa e o filtro de estado ajudam a encontrar o que procura. Em modo de testes aparece sempre um aviso no topo.

Lista de expedições ViaDireta
Lista de expedições: encomendas por enviar e enviadas, incluindo encomendas divididas por locais.

Botões do topo

  • Enviar pendentes: envia de uma vez as encomendas nos estados prontos para envio que ainda não têm expedição. Com encomendas selecionadas, envia só essas.
  • Imprimir etiquetas (ou guias, no ▾): junta num único PDF os documentos das encomendas selecionadas.
  • Pedir recolha: ver Pedido de recolha.
  • Atualizar estados: consulta o seguimento de todos os envios ainda não concluídos.

Enviar uma encomenda

O botão Enviar da linha abre o formulário com os dados já preenchidos (nome, morada, contacto, email, data do serviço, volumes, peso, cobrança, local de recolha, descrição e observações). Pode corrigir o que for preciso antes de enviar. A cobrança é preenchida sozinha quando o pagamento é à cobrança.

Formulário de envio para a ViaDireta
Formulário de envio de uma encomenda.

Menu ▾ de cada encomenda

Cada serviço ViaDireta da encomenda tem um submenu com Etiqueta, Guia de transporte, Seguimento e Pedir recolha / troca. Em baixo:

  • Enviar para ViaDireta (de novo): cria uma nova expedição para a mesma encomenda.
  • Anular envio (só na loja): apaga o registo na loja e tira os números de seguimento, para poder enviar outra vez. Não anula o serviço na ViaDireta, e a remessa do Magento fica (o Magento não deixa apagar remessas).
Menu de uma encomenda
Menu ▾ de uma encomenda com a entrega e uma recolha.

Estado e histórico

Cada serviço mostra o nº de seguimento, o local de recolha e a fase. O botão ⟳ atualiza o estado; o botão ☰ (Histórico) mostra os movimentos de todos os serviços da encomenda, lado a lado.

Histórico de seguimento
Histórico de uma encomenda dividida em dois serviços.

Pedido de recolha e manifesto de carga

O botão Pedir recolha pede à ViaDireta que venha buscar os volumes. Mostra os serviços à espera de recolha agrupados por local, com volumes e peso. Escolha a data, a hora a partir da qual pode ser feita a recolha, o contacto e eventuais observações, e carregue em Enviar pedido. É registado um pedido por local na ViaDireta e o armazém recebe o aviso por email.

Pedido de recolha
Pedido de recolha com os serviços de três locais.
Só entram serviços que ainda não chegaram à ViaDireta. Se as suas credenciais não tiverem acesso a uma conta de registo de recolhas, o pedido segue só por email para a ViaDireta, marcado como “não registado” (a janela avisa antes de enviar).

Manifesto de carga

No ▾ ao lado de Pedir recolha: Imprimir manifesto de carga (um PDF por local, com os serviços à espera de recolha das encomendas selecionadas ou de todas, totais e assinaturas) e a escolha do local de recolha das encomendas selecionadas.

Menu do pedido de recolha
Menu do Pedir recolha.
Manifesto de carga
Manifesto de carga (exemplo do modo de testes).

Vendas › Encomendas

Na grelha de encomendas aparece a coluna Expedição ViaDireta com os números de seguimento, a fase e o botão ▾ de cada encomenda (o mesmo menu da lista de expedições, mais o Histórico). A coluna pode ser escondida em Columns.

Grelha de encomendas com a coluna ViaDireta

O botão ViaDireta ▾ ao lado de Create New Order envia as selecionadas ou as pendentes, imprime etiquetas ou guias das selecionadas e abre as Expedições ViaDireta.

Botão ViaDireta da grelha de encomendas
Botão ViaDireta ▾ da grelha de encomendas.
Menu ViaDireta de uma encomenda
Menu ViaDireta de uma encomenda com a entrega e uma recolha.

Ver encomenda

No separador Information da encomenda, a secção ViaDireta mostra o nº e a fase de cada serviço, Enviar (antes do envio) ou o documento configurado, ⟳ e o menu ▾. Com Criar a remessa do Magento, o envio para a ViaDireta cria também a remessa (Shipment) com o número de seguimento; com várias fontes de inventário, há uma remessa por fonte. Com Notificar o cliente, o cliente recebe o email de envio do Magento.

Secção ViaDireta na página da encomenda
Secção ViaDireta de uma encomenda dividida em dois serviços.

Devoluções: recolhas e trocas

O Magento Open Source não tem um módulo de devoluções, por isso a devolução nasce na encomenda: Pedir recolha / troca (no menu ▾ da encomenda e de cada entrega) abre um formulário onde escolhe o serviço — Recolha no cliente (R) ou Troca: entregar novo e recolher (ER) —, os artigos e as quantidades, o motivo, a entrega original e o local de recolha de destino.

Pedido de recolha / troca de uma encomenda
Pedir recolha / troca a partir de uma entrega.
  • O número de serviço é o da entrega original com R (recolha) ou TR (troca) no fim. Se repetir, fica R2, TR2…
  • Os serviços aparecem a azul nas listas e no histórico. Quando concluídos, a fase passa a Recolhido ou Troca efetuada.

Checkout e área de cliente

Com o transportador ativo, o comprador vê a opção Entrega ViaDireta com o preço dos portes calculado pelas tarifas configuradas.

Entrega ViaDireta no checkout
Checkout: métodos de entrega com a opção ViaDireta.

Em A minha conta › As minhas encomendas › Ver, o bloco Seguimento do envio mostra o número de cada volume, o último estado e o botão Seguir envio.

Seguimento na conta do cliente
Conta do cliente: seguimento de uma encomenda com dois volumes.

Estados e webhook

O módulo acrescenta os estados de encomenda Enviada, Em distribuição, Insucesso na entrega, Devolvida, Recolha pedida, Troca pedida, Recolhida e Troca efetuada, visíveis para o cliente. A encomenda entregue passa a Complete. Um estado desligado na configuração é removido, se nenhuma encomenda o usar.

FaseQuando
Em preparaçãoRegistado, atribuído a uma zona, agendado ou no armazém ViaDireta.
Em distribuiçãoSaiu com o estafeta.
Entregue / Recolhido / Troca efetuadaConcluído com sucesso.
InsucessoTentativa sem sucesso; continua a ser seguido.
DevolvidoDevolvido ao remetente.

O estado da encomenda só avança e, numa encomenda dividida, conta o serviço mais atrasado. Os estados atualizam-se pelo botão Atualizar estados, pelo ⟳ de cada encomenda ou, na hora, pelos avisos da ViaDireta (webhook): copie o Endereço e o Segredo do separador Automação e envie-os ao seu gestor ViaDireta.

Detalhes técnicos do webhook

A ViaDireta envia POST {loja}/viadireta/webhook em JSON, com os cabeçalhos X-ViaDireta-Timestamp (segundos Unix, aceite até 5 minutos de diferença) e X-ViaDireta-Signature: sha256=<HMAC-SHA256(segredo, timestamp + "." + corpo)>. A loja só aceita avisos das contas configuradas e ignora serviços que não são seus.

Dúvidas frequentes

O botão “Associar / testar ligação” dá erro.

Confirme o utilizador e a password da API (são diferentes dos da área de cliente) e se o servidor da loja tem acesso à Internet por HTTPS. Se o erro continuar, ative o Registo de depuração no separador API e envie o ficheiro var/log/viadireta.log ao suporte ViaDireta.

O menu ViaDireta não aparece no admin.

Confirme que correu os comandos de instalação (incluindo setup:upgrade e, em modo produção, setup:di:compile e setup:static-content:deploy) e que a função do utilizador tem as permissões ViaDireta (Expedições e Configuração) em System › User Roles.

A opção ViaDireta não aparece no checkout.

Confirme que o transportador está ativo em Stores › Configuration › Sales › Delivery Methods › ViaDireta, que o país do cliente está permitido, que a zona tem preço nas tarifas e que o carrinho não passa do Peso máximo.

Enviei encomendas em modo de testes. Tenho de as anular?

Não. As expedições de testes ficam marcadas TESTE e, em produção, a encomenda pode ser enviada normalmente.

Anulei um envio na loja. Foi anulado na ViaDireta?

Não. “Anular envio (só na loja)” apaga apenas o registo na loja. Para anular o serviço na ViaDireta, contacte o apoio ao cliente.

Precisa de ajuda? Fale connosco.