Integração Magento
Manual completo do módulo ViaDireta para lojas Magento 2.
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
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.
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.
- Descarregue o ficheiro
viadireta-magento-v1.0.2.zip(botão acima) e descompacte-o na raiz da loja (fica a pastaapp/code/ViaDireta/Shipping). - 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
- 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
- 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.
- Escolha o Modo: Testes usa a conta de testes da ViaDireta, para experimentar sem criar envios reais; Produção usa a sua conta.
- Confirme que o Estado está Ativo e guarde.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
- O número de serviço é o da entrega original com
R(recolha) ouTR(troca) no fim. Se repetir, ficaR2,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.
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.
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.
| Fase | Quando |
|---|---|
| Em preparação | Registado, atribuído a uma zona, agendado ou no armazém ViaDireta. |
| Em distribuição | Saiu com o estafeta. |
| Entregue / Recolhido / Troca efetuada | Concluído com sucesso. |
| Insucesso | Tentativa sem sucesso; continua a ser seguido. |
| Devolvido | Devolvido 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.