PrestaShop integration
Complete manual for the ViaDireta module for PrestaShop stores (in Portuguese).
Módulo ViaDireta para PrestaShop · versão 1.0.1
PrestaShop 8.1 a 9.2 · PHP 7.2 a 8.5 · 0,4 MB
Visão geral
O módulo liga a sua loja PrestaShop à ViaDireta. Cria as expedições a partir das encomendas, 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 localizações em armazém dos produtos; 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 a partir das Mercadorias Devolvidas do PrestaShop, associadas à entrega original.
- Estados de encomenda atualizados pelo seguimento ViaDireta (em distribuição, entregue, insucesso, devolvida…).
- Transportadora 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.
- Descarregue o ficheiro
viadireta-prestashop-v1.0.1.zip(botão acima). - No back office, abra Módulos › Gestor de módulos, carregue em Carregar um módulo e escolha o ficheiro.
- No fim da instalação, carregue em Configurar e siga a configuração.
Atualizar para uma versão nova
Carregue o ficheiro da versão nova em Carregar um módulo, por cima do anterior. A configuração e as expedições mantêm-se.
Desinstalar
Em Módulos › Gestor de módulos, desinstale o módulo ViaDireta. A configuração é sempre apagada e a transportadora fica marcada como apagada; as expedições e os pedidos de recolha só são apagados se em Ao desinstalar (separador API) escolher “Apagar também”.
Configuração
A configuração está em Módulos › Gestor de módulos › ViaDireta › Configurar e tem quatro separadores. Na mesma linha tem atalhos para a Transportadora e para as Expedições ViaDireta.
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á ligado e carregue em Guardar.
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. A cada local, incluindo a Morada da conta (predefinida), associe as localizações em armazém dos produtos e escolha 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 a transportadora ViaDireta.
- Estado da encomenda após envio (por omissão Enviado, com os emails desse estado) e Notificar o cliente por email com o número e o link de seguimento.
- Estados mostrados na lista de expedições.
- Estados de encomenda ViaDireta: ligue ou desligue cada estado criado pelo módulo e escolha o estado da encomenda em cada fase do seguimento.
- Devoluções: estado da devolução e da encomenda ao registar uma recolha ou troca e quando é concluída.
- Atualizações da ViaDireta (webhook) e seguimento para o cliente.
4. Checkout: a transportadora ViaDireta
- Mostrar no checkout, Nome no checkout (por idioma), Classe de imposto e Peso máximo.
- 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.
- As zonas, os grupos de clientes e o logótipo da transportadora configuram-se em Envio › Transportadoras.
Local de recolha do produto
Ao editar um produto, no separador Envio, a lista Local de recolha (ViaDireta) escolhe de onde sai: Automático (pela localização em armazém associada no separador Expedição), a Morada da conta (predefinida) ou um dos locais sincronizados. A escolha no produto tem prioridade.
Expedições ViaDireta
Em Encomendas › ViaDireta (com o número de encomendas por enviar no menu) 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, com filtros por encomenda, cliente, estado e situação ViaDireta. 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 para ViaDireta da linha abre o formulário com os dados já preenchidos (nome, morada, contacto, email, data do serviço, cobrança, local de recolha ou divisão por local com o peso e os volumes de cada serviço, observações). Pode corrigir o que for preciso antes de enviar. A cobrança é preenchida sozinha quando o pagamento é contra-reembolso.
Menu ▾ de cada encomenda
Cada serviço ViaDireta da encomenda tem um submenu com Etiqueta, Guia de transporte, Seguimento e Criar devolução. 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 repõe o estado anterior da encomenda (e o stock), para poder enviar outra vez. Não anula o serviço na ViaDireta.
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.
Encomendas
Em Encomendas › Encomendas aparece a coluna Expedição ViaDireta com os números de seguimento: entregas a verde, recolhas e trocas a azul, encomendas por enviar a cinzento. Em cada linha, o botão ViaDireta ▾ tem o mesmo menu da lista de expedições, mais o Histórico.
O botão ViaDireta ▾ do topo envia as selecionadas ou as pendentes, imprime etiquetas, guias e o manifesto das selecionadas e abre as Expedições ViaDireta.
Ver encomenda
Na página da encomenda, o bloco ViaDireta mostra o nº, o local e a fase de cada serviço, o botão Enviar para ViaDireta (antes do envio) ou o do documento configurado, Atualizar estado e o menu ▾. Depois do envio, a encomenda fica com uma mensagem privada com o número e o link de seguimento, e o número vai para a transportadora da encomenda.
Devoluções: recolhas e trocas
O módulo usa as Mercadorias Devolvidas do PrestaShop (ative-as em Apoio ao Cliente › Mercadorias Devolvidas).
1. Criar a devolução a partir da entrega
No menu ▾ de uma entrega, Criar devolução cria a devolução com os artigos dessa entrega (escolha as quantidades e o motivo) e pergunta logo se quer pedir a recolha ou a troca à ViaDireta. Também pode criar a devolução pelo PrestaShop e pedir o serviço depois.
2. Pedir a recolha ou a troca
Em Apoio ao Cliente › Mercadorias Devolvidas, a coluna ViaDireta mostra o nº do serviço e o menu ▾ com Pedir recolha ao cliente, Troca (entregar novo e recolher), os documentos, o seguimento e a anulação. O formulário vem preenchido com a morada do cliente, o material 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… - Quando concluídos, a fase passa a Recolhido ou Troca efetuada.
Checkout e área de cliente
Com Mostrar no checkout ativo, o comprador vê a transportadora ViaDireta com o preço dos portes calculado pelas tarifas configuradas.
Em A minha conta › Histórico de encomendas › Detalhes, o cliente vê o número de seguimento, o último estado e o botão Seguir envio.
Estados e webhook
Enviado (após o envio) e Entregue são os estados do PrestaShop. O módulo cria também, se quiser, Em distribuição, Insucesso na entrega, Devolvida ao remetente, Recolha pedida, Troca pedida, Recolhida e Troca efetuada, que ficam em Parâmetros da Loja › Definições da Encomenda › Estados.
| 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}/module/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/logs/viadireta.log ao suporte ViaDireta.
A transportadora ViaDireta não aparece no checkout.
Confirme que Mostrar no checkout está ativo, que a transportadora está associada à zona e ao grupo do cliente em Envio › Transportadoras, que a zona / país tem preço nas tarifas e que o carrinho não passa do Peso máximo.
Os produtos saem de armazéns diferentes. Como faço?
Sincronize os locais de recolha (separador Expedição) e associe a cada local as localizações em armazém dos produtos, ou escolha o local em cada produto (Envio › Local de recolha (ViaDireta)). A encomenda é dividida num serviço por local, com uma etiqueta para cada um.
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.