Integración OpenCart
Manual completo de la extensión ViaDireta para tiendas OpenCart 3 (en portugués).
Extensão ViaDireta para OpenCart 3 · versão 1.1.2
OpenCart 3.0.2.0 a 3.0.5.0 · PHP 7.0 a 8.6 · 0,3 MB
Visão geral
A extensão liga a sua loja OpenCart à 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: cada artigo sai do armazém ou da loja certa e, 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 devoluções do OpenCart, associadas à entrega original.
- Estados atualizados pelo seguimento ViaDireta (em distribuição, entregue, insucesso, devolvido), com mudança automática do estado da encomenda.
- Opção 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-opencart3-v1.1.2.ocmod.zip(botão acima). - No admin da loja, abra Extensões › Instalador e envie o ficheiro.
- Abra Extensões › Extensões, escolha o tipo Envios e carregue em Instalar na linha ViaDireta; depois em Editar.
- Siga a configuração e guarde com o Estado em Ativado.
Atualizar para uma versão nova
Envie o ficheiro da versão nova no Instalador, por cima do anterior. A configuração e o histórico das expedições mantêm-se, e a extensão atualiza-se sozinha ao abrir a configuração ou a lista de expedições.
Desinstalar
Em Extensões › Extensões › Envios, carregue em Desinstalar. A opção Ao desinstalar (separador API) define se as expedições ficam guardadas na base de dados ou se são apagadas.
Configuração
A configuração está em Extensões › Extensões › Envios › ViaDireta › Editar e tem quatro separadores.
1. API: ligação e modo
- Preencha o Utilizador API e a Password API e carregue em Associar / testar ligação. A extensão 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.
- Mude o Estado para Ativado 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: carregue em Sincronizar com a ViaDireta para trazer os locais da sua conta (armazéns, lojas). A cada local, incluindo a linha Morada da conta (predefinida), pode associar valores do campo Localização dos produtos e/ou uma loja, e escolher o local por omissão. Assim cada encomenda sai do local certo. Sem locais criados, as recolhas são feitas na morada da conta. 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 (cada um com os seus artigos e peso) ou enviar tudo do mesmo local. Numa encomenda dividida, a cobrança vai toda no primeiro serviço.
- Documento a imprimir: etiqueta ou guia de transporte (o outro fica sempre disponível no menu).
- Data do serviço: dias úteis após o envio (1 = próximo dia útil). Nunca é para o próprio dia, nem para sábados, domingos ou feriados nacionais.
- Peso por omissão: usado quando os produtos não têm peso.
3. Automação: envio automático, estados e avisos
- Enviar automaticamente (desligado numa instalação nova): a expedição é criada sozinha quando a encomenda passa para um dos Estados prontos para envio (por exemplo, quando o pagamento é confirmado). Pode limitar às encomendas com o método de envio ViaDireta.
- Estado da encomenda após envio e Notificar o cliente por email com o número de seguimento.
- Estados mostrados na lista de expedições: os estados das encomendas que aparecem na lista.
- Seguimento e estados: escolha o estado da encomenda quando o envio está Em distribuição, Entregue ou Devolvido. O estado só avança, nunca recua.
- Devoluções: estado da devolução quando a recolha / troca é pedida e quando o artigo chega à loja.
- Atualizações da ViaDireta (webhook): endereço e segredo para a ViaDireta avisar a loja quando o estado de um envio muda (ver Estados e webhook).
4. Checkout: a opção ViaDireta para o comprador
- Mostrar no checkout e Nome no checkout (por idioma).
- Preço dos portes: preço fixo (só para Portugal Continental, para Portugal ou para todos os países) ou por peso e zona, com escalões “até X kg → preço” para Portugal Continental, Açores e Madeira e Internacional (com tabelas país a país, se quiser).
- Portes grátis a partir de um valor, Peso máximo e Classe de imposto.
Local de recolha do produto
Em Catálogo › Produtos › Editar › Dados, logo a seguir à Localização do OpenCart, o campo Local de recolha (ViaDireta) escolhe de onde sai o produto: um dos locais sincronizados ou a Morada da conta (predefinida). Tem prioridade sobre a associação pela Localização; sem escolha, valem as regras do separador Expedição.
Expedições ViaDireta
Em ViaDireta › Expedições ViaDireta (menu lateral) tem as encomendas com os produtos (e o local de cada um), o destino, o estado e os envios ViaDireta de cada uma. 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, pronto a imprimir.
- 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, volumes, peso, cobrança, local de recolha, descrição, data do serviço). Pode corrigir o que for preciso antes de enviar; no fim, a encomenda fica com o número de seguimento e o cliente pode receber o email com o link de seguimento. O local de recolha também pode ser mudado na própria lista, por encomenda ou para as selecionadas.
Menu ▾ de cada encomenda
Cada serviço ViaDireta da encomenda (entregas e recolhas / trocas de devoluções) aparece numa linha com ▸; ao passar o rato abre as opções desse serviço: Etiqueta, Guia de transporte, Seguimento e Criar devolução (nas recolhas / trocas, Abrir 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, que fica disponível para enviar outra vez. Não anula o serviço na ViaDireta.
Estado e histórico
Cada serviço mostra a fase com cor e a data do último movimento. O botão ⟳ atualiza o estado; o botão Histórico mostra os movimentos de todos os serviços da encomenda, lado a lado, como no seguimento do site ViaDireta.
Pedido de recolha e manifesto de carga
O botão Pedir recolha pede à ViaDireta que venha buscar os volumes ao seu armazém ou loja. Mostra os serviços à espera de recolha, agrupados por local, com o total de 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, a opção Imprimir manifesto de carga gera o anexo da guia de transporte com os serviços à espera de recolha: das encomendas selecionadas ou, sem seleção, de todas. Sai um PDF por local de recolha, com o número do manifesto, os volumes, o peso, a cobrança, os totais e os espaços para as assinaturas do cliente e do estafeta. No mesmo menu pode mudar o local de recolha das encomendas selecionadas.
Vendas › Encomendas
Na lista de encomendas do OpenCart aparece a coluna Expedição ViaDireta com os números de seguimento: entregas a verde VD…, recolhas e trocas de devoluções a azul VD…R, encomendas por enviar a cinzento Por enviar.
O botão ViaDireta ▾ do topo envia as selecionadas, envia as pendentes e imprime etiquetas ou guias das selecionadas. Em cada linha, o botão ViaDireta ▾ tem o mesmo menu da lista de expedições, mais o Histórico.
Detalhe da encomenda
No detalhe de uma encomenda, antes de enviar, aparece o botão Enviar para ViaDireta. Depois do envio, o botão imprime o documento configurado e o ▾ dá acesso ao outro documento, ao seguimento, à criação de uma devolução e à lista de expedições. O número de seguimento e o link ficam também no histórico da encomenda.
Devoluções: recolhas e trocas
Quando um cliente quer devolver ou trocar um artigo, a ViaDireta vai buscá-lo (recolha) ou entrega o novo e recolhe o antigo na mesma visita (troca).
1. Criar a devolução
Em Vendas › Devoluções › Adicionar, o campo Entrega ViaDireta aceita o número de seguimento ou o número da encomenda. Carregue em Preencher e a devolução fica preenchida com a encomenda, o cliente e o produto; escolha a entrega original e o produto devolvido. O mesmo acontece com Criar devolução nos menus das expedições e das encomendas.
2. Pedir a recolha ou a troca
Na lista de devoluções, o botão ViaDireta ▾ de cada devolução tem Pedir recolha ao cliente e Troca (entregar novo e recolher), e os documentos e o seguimento dos serviços já pedidos. O formulário vem preenchido com a morada do cliente, o material a recolher / entregar 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 na lista de devoluções, nas expedições e nas encomendas. 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 opção ViaDireta com o preço dos portes calculado pelas tarifas configuradas.
Na conta do cliente, o detalhe da encomenda mostra o número de seguimento, o último estado e o botão Seguir envio (opção Mostrar seguimento ao cliente, no separador Automação).
Estados e webhook
A extensão reconhece a fase de cada serviço pelo seguimento ViaDireta:
| 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 (entrega, recolha ou troca). |
| Insucesso | Tentativa sem sucesso; continua a ser seguido. |
| Devolvido | Devolvido ao remetente. |
Os estados atualizam-se de três formas: pelo botão Atualizar estados da lista de expedições, pelo ⟳ / Histórico de cada encomenda ou, na hora, pelos avisos da ViaDireta (webhook). Para ativar os avisos, 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}/index.php?route=extension/shipping/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 system/storage/logs/viadireta.log ao suporte ViaDireta.
A opção ViaDireta não aparece no checkout.
Verifique se Mostrar no checkout está ativo, se o país / zona do cliente tem preço definido (uma zona sem escalões, ou um peso acima do último escalão, não mostra a opção) e se 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.
Os produtos saem de armazéns diferentes. Como faço?
Sincronize os locais de recolha (separador Expedição) e associe a cada local os valores do campo Localização dos produtos, ou escolha o local em cada produto (Local de recolha (ViaDireta)). A encomenda é dividida num serviço por local, com uma etiqueta para cada um.
Um serviço não aparece no pedido de recolha.
O pedido de recolha só inclui serviços dos últimos 30 dias que ainda não chegaram à ViaDireta. Se o material já deu entrada no armazém, ou já saiu para distribuição, deixa de aparecer.
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.