Checkout para Miva

Nas 24 horas seguintes ao registo, um representante de integração dedicado entrará em contacto consigo para dar início a um processo de integração personalizado.

Importante: Os passos indicados abaixo servem apenas de referência; o seu representante de integração irá orientá-lo ao longo de cada um deles.

1. Transfira o módulo a partir da Miva App Store ou peça o ficheiro zonos.mvc diretamente à Zonos.
2. Na administração do Miva, aceda a Domain Settings -> Modules -> Add Module, carregue o ficheiro zonos.mvc e clique em Add.

3. Aceda a Settings -> Modules, encontre a Zonos e clique em Install. Confirme que o módulo aparece como Installed.

No Miva, aceda a Users -> API Tokens e clique em Add API Token. Configure-o da seguinte forma:

• Name: Zonos Checkout
• Allowed IP Addresses: 0.0.0.0/0, ::/0
• Signature: Require Signature with Key -- clique em Generate para criar uma chave de assinatura
• Timestamp: Require Timestamp Within 30 seconds

No ecrã seguinte, ative Customer Service & Sales para permitir que o token crie e modifique encomendas. Clique em Save.

Aceda ao módulo Checkout no Miva através de Miva -> Utility Settings -> Zonos e preencha os seguintes campos:

1. Store ID: copie o número da sua conta Zonos a partir de Dashboard -> Definições -> Conta -> Integrações.
2. Zonos API Key: a sua chave de API secreta (nunca a partilhe).
3. Zonos Public Key: a sua chave pública.
4. Store Currency: a moeda base da sua loja (por exemplo, USD).
5. Environment: selecione Live para produção ou Test para testes.
6. Checkout Button Selector: seletor CSS do botão de checkout (exemplo: a[href*="checkout.html"]).
7. Hidden Selectors: para ocultar opções de pagamento nacionais e outros detalhes que possam não se aplicar a clientes internacionais.
8. Import Orders: assinale para importar automaticamente as encomendas Zonos concluídas para a administração do Miva. Requer que os webhooks sejam registados no passo seguinte.

Clique em Update no canto superior direito para guardar antes de continuar.

No módulo 10.x, as encomendas são importadas através de webhook. As versões anteriores do módulo utilizavam, em alternativa, um URL/endpoint de sucesso da encomenda.

Depois de guardar as definições, clique em Register Webhooks. Isto liga a sua loja à Zonos para que as encomendas concluídas sejam importadas automaticamente, os cancelamentos sejam sincronizados e as atualizações de envio sejam enviadas de volta para o Miva.

Os webhooks têm de estar registados para que a importação de encomendas, a sincronização de cancelamentos e as atualizações de envio funcionem. A caixa de verificação Import Orders requer que os webhooks estejam registados.

Desloque-se para baixo para preencher os restantes campos:

1. Miva API Token: o Access Token do token de API que criou no passo Criar um token de API.
2. Miva API Signature: a Signing Key da mesma entrada de token de API.
3. Image Type: define o tamanho da imagem do produto apresentada no checkout da Zonos (Main funciona para a maioria das lojas).
4. Additional Field Mappings: opcionalmente, mapeie campos personalizados do Miva para atributos/metadados da Zonos (cor, material, tamanho, etc.). Recomendamos que mapeie o código SH se tiver definido códigos SH específicos dos produtos nas fichas de produto do Miva. Isto não é obrigatório para obter uma cotação de direitos aduaneiros e impostos, uma vez que podemos utilizar os códigos SH específicos dos produtos que introduziu no Catalog ou o seu código SH predefinido. No entanto, é recomendável: a precisão dos cálculos de landed cost aumenta significativamente quando os produtos estão corretamente classificados. Para mapear um campo no Miva, crie um campo personalizado para o código SH e, em seguida, mapeie-o em Utility Settings -> Zonos.

Clique em Update para guardar todas as definições.

Agora que configurou a sua conta e o módulo, está pronto para efetuar os seguintes testes:

• Testar cotações de envio
• Fazer uma encomenda de teste no seu site
• Testar o fluxo de encomendas nos seus sistemas
• Testar o seu website

Saiba como executar estes testes. Durante os testes, terá de definir o campo Environment do módulo como Test.

Depois de concluir os testes, está pronto para entrar em produção! Defina Environment como Live, confirme que as suas credenciais Zonos estão corretas e certifique-se de que os webhooks estão registados na sua loja em produção.

1. Aceda a dashboard.zonos.com -> Hello -> Hello Settings.
2. Ative Currency behavior.
3. Introduza o seletor CSS que identifica os elementos de preço dos seus produtos (por exemplo, .price).

Com esta opção ativada, o Zonos Hello converte e apresenta automaticamente os preços na moeda local do comprador.

As dimensões de envio, o país de origem e o código SH definidos no catálogo do Miva são mapeados automaticamente para a Zonos e, quando preenchidos, são utilizados nas cotações de landed cost / envio. Não é necessário qualquer mapeamento adicional.

Se a sua loja vende produtos configuráveis em que todas as variações partilham um único SKU, as Product Shipping Rules padrão do Miva guardam apenas um conjunto de dimensões por produto, pelo que todas as configurações são tratadas como tendo o mesmo tamanho, independentemente da escolha do cliente.

O Miva e a Zonos suportam dimensões ao nível da variante, mas isso exige configurar cada variante individualmente. Esta abordagem pode ser pouco prática para lojas com centenas ou milhares de configurações que não correspondem a variantes distintas.

Esta funcionalidade resolve o problema ao ler as dimensões de cada configuração diretamente do cesto no checkout, utilizando a lógica personalizada que a sua loja já tem implementada para as calcular -- por exemplo, extraindo as dimensões da descrição do produto.

Requisitos

• A sua loja já tem de preencher colunas de dimensões personalizadas nos artigos do cesto quando estes são adicionados ao carrinho (tratado do lado do Miva, fora do âmbito do módulo Zonos).
• Precisa de saber os nomes exatos das colunas que utiliza.

Configuração

Introduza esses nomes de colunas nos três campos correspondentes da administração do módulo Zonos. Deixe-os em branco para recorrer às Product Shipping Rules padrão -- a funcionalidade é totalmente opcional e não afeta as lojas que não a utilizam.

Quando é criada uma etiqueta de envio ou introduzido um número de seguimento no Zonos Dashboard, o número de seguimento e o estado do envio são enviados automaticamente para a encomenda correspondente na administração do Miva. Requer que os webhooks estejam registados (consulte o passo Registar os webhooks acima).

O seguimento também pode ser introduzido diretamente no Miva. Utilize a caixa de diálogo Enter Tracking Number em qualquer encomenda Zonos -- o número de seguimento e o estado do envio são sincronizados automaticamente com o Zonos Dashboard.

O registo de depuração está disponível na administração do Miva, nas definições do módulo Zonos. Regista o ciclo de vida completo de cada evento de encomenda processado pelo módulo -- importações, sincronizações de seguimento, cancelamentos e pedidos de cancelamento enviados à Zonos -- incluindo, lado a lado, os sucessos e as falhas.

Cada entrada inclui o ID da encomenda na Zonos, o ID da encomenda no Miva e, quando relevante, detalhes ao nível do cliente, como a resposta de erro da API do Miva ou da Zonos. É, por isso, a fonte de informação mais completa para diagnosticar problemas.

O registo guarda apenas as 500 linhas mais recentes. As entradas mais antigas não são arquivadas, por isso consulte-o assim que ocorrer um problema -- os eventos anteriores podem já ter sido substituídos.

Registo público de erros (sem necessidade de início de sessão) 

Está disponível um segundo registo, de acesso público, através de um URL direto -- sem necessidade de iniciar sessão na administração do Miva. Regista apenas erros (não sucessos) e não contém dados pessoais de clientes nem dados sensíveis. Cada entrada tem como prefixo a versão do módulo (por exemplo, [v10.09]) para uma identificação rápida.

Formato do URL:

https://[store-domain]/mm5/json.mvc?Store_Code=[miva_store_code]&Function=Module&Module_Code=igs&Session_Type=runtime&Module_Function=JSON_WebHook&publiclog=1

Exemplo:

https://dts4509.mivamerchantdev.com/mm5/json.mvc?Store_Code=Test&Function=Module&Module_Code=igs&Session_Type=runtime&Module_Function=JSON_WebHook&publiclog=1

Código da loja: o miva_store_code é devolvido no array de metadados da resposta da API para todas as encomendas do Dashboard.

Todos os reembolsos de pagamentos têm de ser processados diretamente no Zonos Dashboard. Por conceção, os botões Refund, Capture e Void do Miva não estão disponíveis para encomendas importadas pela Zonos. Os reembolsos processados na Zonos não atualizam automaticamente os montantes de pagamento na encomenda correspondente do Miva -- a encomenda no Miva mantém os montantes capturados originais e não é sincronizada com a atividade de reembolso na Zonos.

No caso de cancelamentos de encomendas, o comportamento depende do estado atual da encomenda:

• Open (ainda não enviada): cancelá-la no Miva também a cancela na Zonos e anula a autorização de pagamento. Como a Zonos só captura o pagamento quando a encomenda é enviada, o cliente nunca chega a ser cobrado e não é necessário qualquer reembolso separado.
• Shipped ou Completed: cancelar no Miva marca a encomenda do Miva como cancelada, mas a Zonos rejeita o cancelamento porque a encomenda já foi processada e deixou de ser elegível para cancelamento automático. Neste caso, é adicionada à encomenda do Miva uma nota apenas para administradores -- visível só para a equipa da loja e nunca para o cliente -- a explicar que a encomenda tem de ser tratada na Zonos. É também enviada uma notificação por e-mail para o endereço de e-mail principal da conta da loja, a alertar o comerciante para agir no Zonos Dashboard, onde pode processar manualmente qualquer reembolso aplicável.

Sintoma: as encomendas são concluídas no Zonos Checkout e aparecem no Zonos Dashboard, mas nada surge na administração do Miva.

Causa: a Zonos envia um webhook ORDER_CREATED (HTTP POST) para o endpoint /mm5/json.mvc da sua loja. Em sites de desenvolvimento, a segurança ao nível do servidor bloqueia frequentemente este pedido antes de chegar ao Miva. Causas habituais:

• HTTP Basic Auth -- se o site de desenvolvimento pedir uma palavra-passe (Plesk, cPanel, .htaccess, etc.), o webhook é rejeitado com um erro 401 Unauthorized. Adicione os IPs da Zonos à lista de permissões no seu .htaccess ou na configuração do Plesk para que contornem o pedido de autenticação.
• Cloudflare WAF / IP Access Rules -- se o site passar pelo proxy da Cloudflare, as respetivas regras de segurança podem bloquear o POST antes de chegar ao seu servidor. Adicione uma regra WAF que permita pedidos POST cujo caminho do URL contenha /mm5/json.mvc, ou adicione os IPs da Zonos diretamente à lista de permissões nas IP Access Rules da Cloudflare.
• Lista de permissões de IP ao nível do servidor -- se o site de desenvolvimento restringir o tráfego apenas a IPs específicos (comum em ambientes de staging limitados aos IPs do escritório ou da plataforma), os pedidos de webhook da Zonos são descartados silenciosamente, sem resposta. Adicione todos os IPs de entrega de webhooks da Zonos à lista de permissões do seu servidor (Plesk IP Access Restriction Manager, cPanel IP Blocker ou as regras de segurança da sua firewall/painel de alojamento).

IPs de entrega de webhooks da Zonos

195.85.106.100/32
67.207.37.24/29
18.118.243.230/32
18.191.115.116/32
18.216.243.49/32
18.218.198.53/32
18.221.118.18/32
18.223.39.35/32
3.128.123.176/32
3.132.179.92/32
3.138.165.252/32
3.19.11.176/32
3.22.153.63/32
52.15.215.38/32

Normalmente, isto afeta apenas sites de desenvolvimento/staging -- os sites Miva em produção costumam ser públicos e não precisam de listas de permissões de IP. Se não tiver a certeza de como configurar isto, contacte o seu fornecedor de alojamento ou o suporte do Miva.

As informações do produto influenciam os direitos aduaneiros, os impostos e os custos de envio, pelo que, quanto mais informações a Zonos receber, mais precisa será a cotação. A Zonos consegue gerar uma cotação mesmo quando faltam algumas destas informações.

• Peso, dimensões, país de origem e código SH: os valores definidos nas regras de envio do catálogo do Miva são transmitidos automaticamente à Zonos. Não é necessário qualquer mapeamento.
• Códigos SH num campo personalizado: se, em alternativa, guardar os códigos SH num campo personalizado do Miva, mapeie esse campo em Additional Field Mappings, em Utility Settings -> Zonos.
• Valores em falta: a Zonos recorre aos dados do produto no Catalog ou ao seu código SH predefinido.

Nota: Qualquer valor que introduza no Catalog substitui o valor transmitido pelo Miva.

Saiba mais sobre as informações de produto por plataforma.

O módulo 10.x importa as encomendas Zonos concluídas para a administração do Miva através de webhook. Assinale Import Orders nas definições da Zonos e, em seguida, clique em Register Webhooks. Os webhooks também sincronizam os cancelamentos e enviam as atualizações de envio de volta para o Miva. As versões anteriores do módulo utilizavam, em alternativa, um URL de sucesso da encomenda.

Normalmente, a segurança ao nível do servidor do site de desenvolvimento está a bloquear o webhook ORDER_CREATED que a Zonos envia para /mm5/json.mvc -- HTTP Basic Auth, Cloudflare WAF ou IP Access Rules, ou uma lista de permissões de IP no servidor. Permita os IPs de entrega de webhooks da Zonos indicados acima, em Resolução de problemas: as encomendas não aparecem no Miva em sites de desenvolvimento/staging. Os sites em produção costumam ser públicos e não são afetados.

Processe todos os reembolsos no Zonos Dashboard. Os botões Refund, Capture e Void do Miva não estão disponíveis para encomendas importadas pela Zonos, e os reembolsos efetuados na Zonos não atualizam os montantes de pagamento na encomenda do Miva.

Depende do estado da encomenda:

• Open (ainda não enviada): a encomenda também é cancelada na Zonos e a autorização de pagamento é anulada. O cliente nunca chega a ser cobrado, pelo que não é necessário qualquer reembolso.
• Shipped ou Completed: a Zonos rejeita o cancelamento. É adicionada à encomenda do Miva uma nota apenas para administradores e é enviado um e-mail para o endereço de e-mail principal da conta da loja, para que possa processar qualquer reembolso no Zonos Dashboard.

Utilize o registo de depuração nas definições do módulo Zonos, na administração do Miva. Este regista todas as importações de encomendas, sincronizações de seguimento e cancelamentos, com sucessos e falhas, e guarda as 500 linhas mais recentes. Para consultar apenas os erros, sem iniciar sessão na administração do Miva, utilize o URL do registo público de erros descrito acima, em Registo de depuração.