Checkout para Miva

Dentro de 24 horas após a inscrição, um representante de integração dedicado entrará em contato com você para iniciar um processo de integração personalizado.

Importante: As etapas listadas abaixo são apenas para referência e seu representante de integração orientará você através delas.

1. Baixe o módulo na Miva App Store ou solicite o arquivo zonos.mvc diretamente à Zonos.
2. No admin do seu Miva, vá em Domain Settings -> Modules -> Add Module, envie o arquivo zonos.mvc e clique em Add.

3. Vá em Settings -> Modules, encontre a Zonos e clique em Install. Confirme que ela é exibida como Installed.

No Miva, vá em 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

Na próxima tela, habilite Customer Service & Sales para permitir que o token crie e modifique pedidos. Clique em Save.

Navegue até o módulo Checkout no Miva indo em Miva -> Utility Settings -> Zonos e preencha os seguintes campos:

1. ID da loja: copie o número da sua conta Zonos em Dashboard -> Configurações -> Conta -> Integrações.
2. Chave de API Zonos: sua chave de API secreta (nunca compartilhe isso).
3. Chave pública Zonos: sua chave pública.
4. Moeda da loja: a moeda base da sua loja (por exemplo, USD).
5. Ambiente: selecione Live para produção ou Test para teste.
6. Seletor do botão de checkout: seletor CSS do botão de checkout (exemplo: a[href*="checkout.html"]).
7. Seletores ocultos: para ocultar opções de pagamento nacionais e outros detalhes que podem não se aplicar a clientes internacionais.
8. Importar pedidos: marque para importar automaticamente os pedidos Zonos concluídos para o admin do Miva. Isso requer que os webhooks sejam registrados na próxima etapa.

Clique em Atualizar no canto superior direito para salvar antes de continuar.

Os pedidos são importados via webhook no módulo 10.x. Versões anteriores do módulo usavam, em vez disso, uma URL/endpoint de sucesso do pedido.

Depois de salvar suas configurações, clique em Registrar Webhooks. Isso conecta sua loja à Zonos para que os pedidos concluídos sejam importados automaticamente, os cancelamentos sejam sincronizados e as atualizações de envio sejam enviadas de volta ao Miva.

Os webhooks precisam estar registrados para que a importação de pedidos, a sincronização de cancelamentos e as atualizações de envio funcionem. A caixa de seleção Importar pedidos requer que os webhooks estejam registrados.

Role para baixo para preencher os campos restantes:

1. Token de API do Miva: o Access Token do token de API que você criou na etapa Crie um token de API.
2. Assinatura de API do Miva: a Signing Key da mesma entrada de token de API.
3. Tipo de imagem: seleciona qual tamanho de imagem do produto é exibido no checkout da Zonos (Main funciona para a maioria das lojas).
4. Mapeamentos de campos adicionais: opcionalmente, mapeie campos personalizados do Miva para atributos/metadados da Zonos (cor, material, tamanho etc.). Recomendamos mapear o código HS caso você tenha configurado códigos HS específicos do produto nas suas listagens de produtos do Miva. Isso não é necessário para gerar uma cotação de tarifas e impostos, já que podemos usar os códigos HS específicos do produto que você inseriu no Catálogo ou usar seu código HS padrão. No entanto, é recomendado; a precisão dos cálculos do custo final aumenta bastante com produtos classificados corretamente. Para mapear um campo no Miva, crie um campo personalizado para o código HS e depois mapeie-o em Utility Settings -> Zonos.

Clique em Atualizar para salvar todas as configurações.

Agora que você configurou sua conta e seu módulo, está pronto para testar fazendo o seguinte:

• Teste cotações de envio
• Faça um pedido de teste em seu site
• Teste o fluxo de pedidos através de seus sistemas
• Teste seu site

Saiba como executar esses testes. Você precisará definir o campo Environment do módulo como Test durante os testes.

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

1. Vá em dashboard.zonos.com -> Hello -> Configurações do Hello.
2. Ative a opção Comportamento de moeda.
3. Insira o seletor CSS que direciona os elementos de preço do seu produto (por exemplo, .price).

O Zonos Hello converterá e exibirá automaticamente os preços na moeda local do comprador quando isso estiver habilitado.

As dimensões de envio, o país de origem e o código HS definidos no catálogo do Miva são mapeados automaticamente para a Zonos e usados para cotações de custo final / envio quando preenchidos. Não é necessário nenhum mapeamento adicional para configurar.

Se sua loja vende produtos configuráveis em que todas as variações compartilham um único SKU, as Product Shipping Rules padrão do Miva armazenam um único conjunto de dimensões por produto, de modo que toda configuração é tratada como do mesmo tamanho, independentemente do que o cliente selecionou.

Miva e Zonos oferecem suporte a dimensões no nível da variante, mas isso exige configurar cada variante individualmente. Isso pode ser impraticável para lojas com centenas ou milhares de configurações que não correspondem a variantes discretas.

Este recurso resolve isso lendo as dimensões de cada configuração diretamente do carrinho no checkout, usando a lógica personalizada que sua loja já possui para calculá-las -- por exemplo, extraindo dimensões da descrição do produto.

Requisitos

• Sua loja já deve preencher colunas de dimensão personalizadas nos itens do carrinho quando os itens são adicionados (isso é feito do lado do Miva, fora do escopo do módulo Zonos).
• Você precisará saber os nomes exatos das colunas que está usando.

Configuração

Insira esses nomes de coluna nos três campos correspondentes no admin do módulo Zonos. Deixe-os em branco para usar as Product Shipping Rules padrão -- o recurso é totalmente opcional e não afeta lojas que não o utilizam.

Quando uma etiqueta de envio é criada ou um número de rastreamento é inserido no Dashboard da Zonos, o número de rastreamento e o status do envio são enviados automaticamente para o pedido correspondente no admin do Miva. Isso requer que os webhooks estejam registrados (veja a etapa Registre os webhooks acima).

O rastreamento também pode ser inserido diretamente no Miva. Use a caixa de diálogo Enter Tracking Number em qualquer pedido da Zonos -- o número de rastreamento e o status do envio serão sincronizados automaticamente de volta para o Dashboard da Zonos.

O log de depuração é acessível dentro do admin do Miva, nas configurações do módulo Zonos. Ele registra o ciclo de vida completo de cada evento de pedido que o módulo processa -- importações, sincronizações de rastreamento, cancelamentos e solicitações de cancelamento enviadas à Zonos -- incluindo sucessos e falhas.

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

O log retém apenas as 500 linhas mais recentes. Entradas mais antigas não são arquivadas, portanto verifique-o rapidamente após a ocorrência de um problema -- eventos anteriores já podem ter sido sobrescritos.

Log de erros público (sem necessidade de login) 

Um segundo log, voltado ao público, está disponível por meio de uma URL direta -- sem necessidade de login no admin do Miva. Ele registra apenas erros (nenhum sucesso) e não contém PII de clientes ou dados sensíveis. Cada entrada é prefixada com a versão do módulo (por exemplo, [v10.09]) para identificação rápida.

Formato da 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 é retornado no array de metadados da resposta da API para todos os pedidos do dashboard.

Todos os reembolsos de pagamento devem ser processados diretamente pelo dashboard da Zonos. Os botões Refund, Capture e Void no Miva não estão disponíveis para pedidos importados pela Zonos, por design. Quaisquer reembolsos processados na Zonos não atualizarão automaticamente os valores de pagamento no pedido correspondente no Miva -- o pedido no Miva mantém os valores capturados originais e não é mantido em sincronia com a atividade de reembolso na Zonos.

Para cancelamentos de pedidos, o comportamento depende do status atual do pedido:

• Open (ainda não enviado): cancelar no Miva também cancelará na Zonos e anulará a autorização de pagamento. Como a Zonos não captura o pagamento até que o pedido seja enviado, o cliente nunca chega a ser cobrado e nenhum reembolso separado é necessário.
• Shipped ou Completed: cancelar no Miva marcará o pedido no Miva como cancelado, mas a Zonos rejeitará o cancelamento porque o pedido já foi cumprido e não se qualifica mais para cancelamento automático. Nesse caso, uma nota visível somente para a equipe da loja (nunca para o cliente) é adicionada ao pedido no Miva, explicando que o pedido precisa ser tratado na Zonos. Uma notificação por e-mail também é enviada ao endereço de e-mail principal da conta da loja, alertando o lojista para agir no dashboard da Zonos, onde ele pode processar manualmente qualquer reembolso aplicável.

Sintoma: os pedidos são concluídos no Zonos Checkout e aparecem no dashboard da Zonos, mas nada aparece no admin do Miva.

Causa: a Zonos envia um webhook ORDER_CREATED (HTTP POST) para o endpoint /mm5/json.mvc da sua loja. Em sites de dev, a segurança no nível do servidor frequentemente bloqueia essa solicitação antes que ela chegue ao Miva. Causas comuns:

• HTTP Basic Auth -- se o site de dev tiver um prompt de senha (Plesk, cPanel, .htaccess etc.), o webhook será rejeitado com um 401 Unauthorized. Coloque os IPs da Zonos na lista de permissões no seu .htaccess ou na configuração do Plesk para que eles ignorem o prompt de autenticação.
• Cloudflare WAF / IP Access Rules -- se o site estiver por trás do Cloudflare, as regras de segurança dele podem bloquear o POST antes que ele chegue ao seu servidor. Adicione uma regra de WAF para permitir solicitações POST cujo caminho da URL contenha /mm5/json.mvc, ou coloque os IPs da Zonos diretamente na lista de permissões nas IP Access Rules do Cloudflare.
• Lista de permissões de IP no nível do servidor -- se o site de dev restringir o tráfego a IPs específicos (comum em ambientes de staging restritos a IPs do escritório ou da plataforma), as solicitações de webhook da Zonos são descartadas silenciosamente, sem resposta. Adicione todos os IPs de entrega de webhook da Zonos à lista de permissões do seu servidor (Plesk IP Access Restriction Manager, cPanel IP Blocker ou as regras de segurança do seu firewall/painel de hospedagem).

IPs de entrega de webhook 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

Isso normalmente afeta apenas sites de dev/staging -- sites Miva em produção geralmente são públicos e não precisam de whitelisting de IP. Se não tiver certeza de como configurar isso, entre em contato com seu provedor de hospedagem ou com o suporte do Miva.

As informações do produto podem afetar o valor dos direitos e impostos devidos e o custo do envio. Quanto mais informações do produto você fornecer à Zonos, mais precisa será a cotação retornada. Zonos pode gerar uma cotação mesmo quando esta informação não estiver disponível, mas recomenda fornecer os seguintes detalhes principais do produto para melhorar a precisão:

• Peso: O peso afeta o custo de envio, o que pode afetar taxas ou impostos. Os pesos nas listagens de produtos Miva são usados automaticamente pelo Zonos quando presentes.
• Dimensões: As dimensões podem afetar o custo de envio, o que pode afetar taxas ou impostos. O Zonos pode usar as dimensões do produto (comprimento, largura e altura) configuradas em cada produto no Miva, mas você deve mapeá-las para o aplicativo Zonos para integração adequada.
• Códigos HS: Os códigos HS afetam as taxas tarifárias e às vezes podem afetar os impostos. Zonos pode usar os códigos HS configurados em suas listagens de produtos no Miva, mas você deve mapear o campo do código HS no aplicativo Zonos.
• País de origem: O país de origem de um produto afeta as tarifas e pode afetar os impostos. A Miva não pode enviar o país de origem de seus produtos para o Zonos, portanto eles devem ser adicionados através do Catálogo Zonos.

Detalhes do produto enviados para Zonos pela Miva 

Observação: Alternativamente, você pode inserir qualquer uma das informações acima no Catálogo, substituindo as informações armazenadas e enviadas do Miva.

Mais informações sobre informações de produtos por plataforma.