Guia de Integração — Plugin ZHF Melhor Envio

Passo a passo para conectar o ZHF Ecommerce ao Melhor Envio, configurar o webhook e ativar o fluxo de cotação e compra de etiqueta.

Quem é este guia para: lojistas e operadores que vão integrar a loja do zero. Siga as etapas na ordem — cada uma depende da anterior.

1. Pré-requisitos

Antes de começar, confirme que você tem:

ZHF Ecommerce instalado e ativo na loja.
Plugin ZHF Melhor Envio instalado e ativo.
Conta no Melhor Envio com acesso ao painel de integrações (Área Dev).
Loja com URL pública em HTTPS — obrigatório para o webhook funcionar (ambientes em localhost não recebem webhook).
HPOS (armazenamento de pedidos de alta performance) ativo, se você quiser usar o box de Melhor Envio dentro do pedido para cotar e comprar etiqueta.
- Ative em: Ecommerce → Configurações → Avançado → Recursos → High-performance order storage.
Decisão de ambiente: começar em sandbox (testes) ou já em produção. Os dois usam apps e tokens diferentes.

2. Acessar o painel e abrir as configurações

Faça login no painel administrativo em /zhf-admin.
- Após o login, o painel administrativo continua acessível em /wp-admin/.
No menu lateral, acesse Ecommerce → Configurações → Entregas.
Abra a seção Melhor Envio.
- Atalho direto: admin.php?page=wc-settings&tab=shipping&section=zhf_melhor_envio

3. Copiar os dados de configuração do plugin

Na seção Melhor Envio, abra o bloco Configurações do aplicativo → Dados de configuração. O plugin exibe, com botões de Copiar, exatamente o que você precisa cadastrar no Melhor Envio:

Campo no Melhor Envio	Valor exibido pelo plugin	Observação
Nome da plataforma	`ZHF-ECOMMERCE`	Fixo
Site da plataforma	URL da sua loja	Dinâmico por site
URL do ambiente de testes	URL da sua loja	Dinâmico
URL de redirecionamento após autorização	`{site}/wp-admin/admin-post.php?action=zhf_me_oauth_callback`	Callback OAuth
Descrição do aplicativo	`Cotação e compra de etiqueta`	Fixo
URL Webhook	`{site}/wp-json/zhf-me/v1/webhook`	Alternativa: `index.php?rest_route=/zhf-me/v1/webhook`

Atenção: copie a URL de redirecionamento exatamente como o plugin exibe. Uma diferença de um caractere faz o OAuth falhar.

4. Criar o aplicativo no Melhor Envio

No Melhor Envio, acesse Integrações → Área Dev (https://app.melhorenvio.com.br/integracoes/area-dev).
Crie um novo aplicativo.
Cole cada campo copiado do plugin no formulário correspondente.
Salve o aplicativo.
Copie o Client ID e o Client Secret gerados.

O Client Secret também é usado para validar a assinatura do webhook. Guarde-o com cuidado e nunca o exponha publicamente.

5. Conectar via OAuth

Volte às configurações do plugin (Ecommerce → Configurações → Entregas → Melhor Envio).
Selecione o Ambiente correto: Produção ou Sandbox.
Cole o Client ID e o Client Secret.
Clique em Salvar alterações.
Clique em Conectar com Melhor Envio e autorize no site do Melhor Envio.
Aguarde o retorno automático ao painel.

Resultado esperado: o status de conexão muda para Conectado.

O plugin renova o token automaticamente (refresh quando faltam ≤ 5 minutos para expirar, além de uma renovação diária preventiva). Se a renovação diária falhar, o plugin envia um e-mail ao admin.

6. Selecionar as modalidades disponíveis

Esta etapa define quais serviços (PAC, SEDEX, Jadlog etc.) ficam disponíveis para uso na loja.

Ainda na seção Melhor Envio, localize Modalidades Disponíveis.
Clique em Verificar modalidades para carregar a lista atualizada da sua conta.
Selecione as modalidades que a loja vai oferecer.
Salve alterações.

Se você deixar a lista vazia, o plugin considera todas as modalidades retornadas pela API. Selecionar explicitamente evita oferecer serviços que você não usa e reduz inconsistências no checkout.

7. Configurar o CEP de origem

A cotação e a compra de etiqueta precisam partir do mesmo CEP de origem. O plugin usa, nesta ordem:

CEP de origem configurado no plugin (se preenchido); senão
O CEP da loja em Ecommerce → Configurações → Geral.

Recomendação: defina o CEP de origem explicitamente para garantir que cotação e etiqueta sempre coincidam. Divergência aqui é a causa mais comum de erro 422 na compra de etiqueta.

8. Adicionar as modalidades no checkout (zonas de entrega)

Esta é a etapa que faz o frete aparecer para o cliente. Conectar o OAuth e selecionar modalidades não exibe frete sozinho — é preciso adicionar cada modalidade como um método dentro de uma zona de entrega.

Conceito: cada modalidade = uma instância do método de envio dentro de uma zona. PAC e SEDEX, por exemplo, são duas instâncias separadas.

Acesse Ecommerce → Configurações → Entregas → Áreas de entrega.
Edite a zona desejada (ex.: Brasil) → Adicionar método de entrega.
Escolha Melhor Envio → Adicionar.
Clique em Editar na instância recém-criada e configure:
- Título — o texto que o cliente vê no checkout (ex.: “PAC — Correios”).
- Modalidade — selecione o serviço Melhor Envio desta instância.
- Custo Adicional — valor somado ao preço retornado pela API (opcional).
- Dias Adicionais — dias somados ao prazo da API (opcional).
- Remover se tiver classe de entrega / Exibir apenas com classe de entrega — regras opcionais por classe de produto.
Salve.
Repita os passos 2–5 para cada modalidade que a loja vai oferecer.

Teste o checkout com um CEP de destino válido (8 dígitos) e um produto físico com peso e dimensões preenchidos.

9. Configurar a automação de status dos pedidos

O plugin pode trocar o status do pedido automaticamente em três momentos. Em todos eles, a primeira opção é “Não trocar status” — o padrão seguro, que evita mudanças acidentais após instalação ou atualização.

Opção	Quando dispara
Status para comprar etiquetas e receber rastreio	Define quais status do ZHF Ecommerce permitem comprar etiqueta e receber rastreio via webhook
Status após receber rastreio	Quando chega o código de rastreio
Status após entrega	Quando o Melhor Envio sinaliza entrega
Status após a compra da etiqueta	Quando a etiqueta é paga (evento `order.released`)

Ajuste Status para comprar etiquetas e receber rastreio com os status do ZHF Ecommerce permitidos no seu processo (ex.: Processando, Concluído).
Configure as três trocas automáticas conforme sua operação — ou deixe em “Não trocar status” se preferir controlar manualmente.
Salve alterações.

10. Dados fiscais do remetente (CNPJ)

Para emitir etiquetas, o Melhor Envio exige o CNPJ do remetente cadastrado nos dados fiscais do aplicativo.

Acesse os dados fiscais do app no painel do Melhor Envio e preencha o CNPJ.
Erro comum: se o CNPJ do destinatário for igual ao CNPJ do remetente cadastrado, a API rejeita (422). Para testes, use um destinatário pessoa física (CPF) ou um CNPJ diferente.
Algumas transportadoras exigem CNAE — você pode preencher um CNAE global no plugin ou informá-lo no momento da compra da etiqueta.

11. Emitir etiqueta de um pedido (box do pedido)

O box Melhor Envio dentro do pedido só aparece com HPOS ativo (ver pré-requisitos).

Abra o pedido em Ecommerce → Pedidos e localize o box lateral Melhor Envio.
Se você usa NFe, informe a chave de 44 dígitos.
Ajuste os volumes, se necessário (ao reduzir a quantidade de volumes, edite as dimensões dos volumes finais — caso contrário o backend retorna erro).
Marque Assegurar pedido, se aplicável.
Clique em Cotar pedido e selecione um serviço.
Preencha CNAE, se a transportadora exigir.
Clique em Comprar etiqueta — o frete vai para o carrinho do Melhor Envio.
Pague no carrinho do Melhor Envio (link “Ver carrinho”).
Após o pagamento, o webhook marca a etiqueta como paga e aplica o status configurado.

12. Teste completo recomendado

Crie um pedido de teste no ZHF Ecommerce com endereço, CPF/CNPJ e produto físico.
Abra o pedido e use o box do plugin para cotar e comprar a etiqueta.
Confirme que o frete chegou ao carrinho do Melhor Envio.
Confirme o recebimento dos webhooks (rastreio, entrega, etiqueta paga).
Valide as notas do pedido e, se configurada, a troca automática de status.

13. Solução de problemas

Conexão / OAuth

“Não conectado” após autorizar: confira Client ID/Secret salvos e a URL de redirecionamento idêntica à do plugin. Verifique se o site responde por HTTPS. Se persistir, recrie o app copiando os campos novamente.
Frete parou de aparecer / token expirado: reconecte em Melhor Envio → Conectar. Confirme que a renovação diária de token está ativa.

Frete não aparece no checkout

Causa	Solução
Plugin não conectado	Refazer OAuth (etapa 5)
Modalidade não selecionada na instância	Editar o método na zona e escolher a modalidade (etapa 8)
Modalidade não adicionada à zona	Adicionar o método Melhor Envio na zona de entrega (etapa 8)
CEP de origem vazio	Configurar CEP da loja ou do plugin (etapa 7)
CEP de destino inválido	Deve ter 8 dígitos
Produto virtual / sem envio	Comportamento normal — não gera frete
Modalidade fora das “Modalidades Disponíveis”	Incluir o serviço na seleção global (etapa 6)
Regra de classe de entrega ocultou o método	Revisar as regras de remover/exibir por classe

Preço ou prazo errado

Confira Custo Adicional e Dias Adicionais na instância.
Cache antigo: reduza a duração do cache de cotação nas configurações.

Compra de etiqueta — erros 422 comuns

Mensagem / causa	Ação
CEP de origem divergente	Garantir o mesmo CEP de origem na cotação e na compra (etapa 7)
CNPJ remetente = destinatário	Testar com destinatário PF ou outro CNPJ (etapa 10)
CPF/CNPJ do destinatário ausente	Garantir que o checkout grava CPF/CNPJ do cliente
CNAE exigido pela transportadora	Preencher CNAE global ou no pedido
Chave NFe inválida (modo NFe)	Informar chave de 44 dígitos

Webhook não chega

Confirme a URL do webhook cadastrada no app.
Site precisa ser público em HTTPS.
Client Secret no plugin deve ser idêntico ao do app (validação de assinatura x-me-signature).
Ative os logs de webhook e confira em Ecommerce → Status → Logs.
O pedido precisa ter o código de envio (_zhf_me_shipment_code) correspondente ao protocolo do webhook.

Status não muda

Causa mais comum: a opção está em “Não trocar status”. Defina o status desejado (etapa 9).

Box do pedido não aparece

HPOS desabilitado. Ative em Ecommerce → Configurações → Avançado → Recursos (ver pré-requisitos).

Onde olhar os logs

Fonte (Ecommerce → Status → Logs)	Conteúdo
`zhf-melhor-envio`	Cotações e debug geral
`zhf-melhor-envio-requests`	Cada chamada à API (diagnóstico de rate limit)
Logs de webhook	Rastreio/status que não atualizam

14. Checklist final

[ ] Aplicativo criado no Melhor Envio com os dados corretos
[ ] Client ID e Client Secret salvos no plugin
[ ] Ambiente (sandbox/produção) selecionado corretamente
[ ] Conexão OAuth concluída — status Conectado
[ ] Modalidades disponíveis selecionadas e salvas
[ ] CEP de origem configurado
[ ] Modalidades adicionadas às zonas de entrega (frete aparece no checkout)
[ ] CNPJ do remetente preenchido nos dados fiscais do Melhor Envio
[ ] Webhook cadastrado e respondendo
[ ] Trocas de status ajustadas conforme a operação
[ ] Teste de ponta a ponta realizado (cotação → etiqueta → webhook)