Como gerenciar um pedido com entrega via Melhor Envio

Este tutorial mostra, do início ao fim, o que fazer quando você recebe um pedido cujo método de entrega é o Melhor Envio: cotar, comprar a etiqueta, informar a NFe (quando houver), pagar no site do Melhor Envio e acompanhar o rastreio automaticamente.

Visão geral do fluxo

Pedido recebido (entrega Melhor Envio)
        │
        ├─ (Se tiver NFe) Informar a chave da NFe
        │
        ├─ Cotar o pedido → escolher a modalidade
        │     (em frete grátis, pode escolher a mais barata)
        │
        ├─ Comprar a etiqueta → vai para o carrinho do Melhor Envio
        │
        ├─ Pagar a etiqueta no site do Melhor Envio
        │
        ├─ Webhook avisa: "Etiqueta paga"  → status do pedido atualiza
        │
        └─ Webhook avisa: código de rastreio → vira nota no pedido

Na prática, gerenciar o pedido é basicamente comprar a etiqueta (que entra no carrinho do Melhor Envio) e depois pagar por ela no site do Melhor Envio. O resto (confirmação da etiqueta e rastreio) chega automaticamente pelo webhook.

Pré-requisitos

Antes de começar, confirme que:

O plugin ZHF Ecommerce está com o Melhor Envio Conectado (status verde nas configurações).
O recurso HPOS (armazenamento de pedidos de alta performance) está ativo. O quadro lateral “Melhor Envio” no pedido só aparece com o HPOS ligado.
O pedido tem endereço completo, CPF ou CNPJ do destinatário e ao menos um produto físico (com envio).

Se o quadro “Melhor Envio” não aparecer no pedido, ative o HPOS em Ecommerce → Configurações → Avançado → Recursos → High-performance order storage.

Passo 1 — Abrir o pedido

Faça login no painel administrativo em seusite.com.br/zhf-admin.
Já dentro do painel, vá em Ecommerce → Pedidos.
Abra o pedido que você quer processar.
Na lateral direita, localize o quadro Melhor Envio.

Enquanto o pedido ainda não tem etiqueta, esse quadro mostra: editor de volumes, opção de seguro, campo de NFe (quando aplicável), botão Cotar pedido e o botão Comprar etiqueta (que fica bloqueado até você escolher uma cotação).

Passo 2 — Informar a chave da NFe (somente se o pedido tiver nota fiscal)

Esse passo só aparece/é exigido quando a loja opera em modo NFe (emissão com nota fiscal eletrônica).

No quadro Melhor Envio, localize o campo Chave da NFe.
Cole a chave de 44 dígitos da nota fiscal.
Clique em Aplicar para salvar.

Pontos importantes:

A chave precisa ter exatamente 44 dígitos, senão a compra da etiqueta é recusada.
No modo NFe, o seguro do envio é obrigatório (o sistema já força isso).
Se a loja não usa NFe (modo declaração de conteúdo), esse campo não aparece e você pode pular este passo.

Passo 3 — Conferir volumes e seguro

Antes de cotar, revise como o pedido será embalado.

Volumes (opcional):

O sistema calcula os volumes automaticamente a partir dos produtos.
Se quiser, você pode reduzir a quantidade de volumes e editar as dimensões/peso de cada um.
⚠️ Se você reduzir a quantidade de volumes, edite as dimensões dos volumes finais — caso contrário a compra dá erro.
Mínimos por volume: peso ≥ 0,1 kg, altura ≥ 2 cm, largura ≥ 11 cm, comprimento ≥ 16 cm.

Seguro:

Marque ou desmarque Assegurar pedido conforme a necessidade.
Em modo NFe, o seguro já vem obrigatório.

Passo 4 — Cotar o pedido e escolher a modalidade

Clique em Cotar pedido.
O sistema consulta o Melhor Envio e exibe as modalidades disponíveis (ex.: PAC, SEDEX, Jadlog) com preço e prazo.
Selecione a modalidade desejada (opção de rádio).

Frete grátis? Quando o pedido foi vendido com frete grátis, o custo da etiqueta é da loja — então você pode simplesmente escolher a modalidade mais barata entre as cotadas. Isso é opcional, mas costuma ser a escolha mais econômica.

Se aparecer pedido de CNAE: algumas transportadoras (ex.: Latam) exigem o CNAE. Se o sistema mostrar o campo de CNAE ao selecionar o serviço, preencha-o antes de continuar (pode ser informado no pedido ou já estar configurado globalmente).

Passo 5 — Comprar a etiqueta

Com a modalidade selecionada (e NFe/CNAE preenchidos quando exigidos), clique em Comprar etiqueta.
O sistema monta o envio e o insere no carrinho do Melhor Envio.
O quadro do pedido se atualiza e passa a mostrar:
- Código de envio (protocolo)
- Método, valor da etiqueta e transportadora
- Botão Cancelar etiqueta
- Link Ver carrinho (Melhor Envio)

Neste momento a etiqueta ainda não está paga — ela está apenas reservada no carrinho do Melhor Envio.

Precisou desistir? Enquanto a etiqueta não estiver paga, clique em Cancelar etiqueta. Isso remove o item do carrinho do Melhor Envio e libera o pedido para uma nova cotação.

Passo 6 — Pagar a etiqueta no site do Melhor Envio

A compra da etiqueta dentro do painel apenas coloca o frete no carrinho. O pagamento é feito no site do Melhor Envio.

No quadro do pedido, clique em Ver carrinho.
Você será levado ao carrinho do Melhor Envio.
Finalize o pagamento da etiqueta por lá.

Depois de pago, você gera/imprime a etiqueta normalmente pelo painel do Melhor Envio e posta o pacote.

Passo 7 — Acompanhamento automático (webhook)

A partir daqui, o trabalho é automático. O Melhor Envio avisa a loja por webhook:

Etiqueta paga: assim que o pagamento é confirmado, o pedido é marcado como Etiqueta paga, ganha uma nota interna e — se você tiver configurado — muda de status automaticamente. O quadro passa a exibir o indicador “Etiqueta paga” e o link Conferir envios.
Código de rastreio: quando a postagem é registrada, o código de rastreio chega e é salvo no pedido como nota.
Entrega: na entrega, uma nova nota é registrada e o status pode mudar (se configurado).

Sobre mudança de status: por padrão, todas as opções de status automático vêm como “Não trocar status” (segurança). O status só muda sozinho se você tiver configurado isso em Ecommerce → Configurações → Entregas → Melhor Envio. Se quiser que o pedido vá para “Em transporte”, “Concluído” etc. automaticamente, configure lá antes.

Resumo rápido (passo a passo)

seusite.com.br/zhf-admin → login → Ecommerce → Pedidos → abrir pedido.
Quadro Melhor Envio na lateral (precisa de HPOS).
Tem NFe? Informar chave de 44 dígitos → Aplicar.
Conferir volumes e Assegurar pedido se for o caso.
Cotar pedido → escolher modalidade (frete grátis → escolher a mais barata).
Preencher CNAE se for solicitado.
Comprar etiqueta (vai pro carrinho do Melhor Envio).
Ver carrinho → pagar no site do Melhor Envio.
Pronto: webhook confirma a etiqueta paga e, depois, traz o código de rastreio.

Resolução de problemas

O quadro “Melhor Envio” não aparece no pedido → HPOS desativado. Ative em Ecommerce → Configurações → Avançado → Recursos.

Erro ao comprar: CPF/CNPJ do destinatário ausente → O pedido precisa ter o CPF (pessoa física) ou CNPJ (pessoa jurídica) do cliente preenchido.

Erro ao comprar: CNPJ do remetente igual ao do destinatário → O Melhor Envio não permite enviar para o mesmo CNPJ cadastrado no app. Use um destinatário diferente (PF ou outro CNPJ).

Erro ao comprar: CEP de origem → Confirme que o CEP de origem da loja está configurado corretamente. O CEP da cotação e o da compra precisam ser o mesmo.

Erro: transportadora exige CNAE → Preencha o CNAE no quadro do pedido (ou globalmente) antes de comprar a etiqueta.

Chave NFe inválida → No modo NFe, a chave precisa ter exatamente 44 dígitos.

“Ao reduzir a quantidade de volumes, edite os volumes finais…” → Você diminuiu o número de volumes mas não ajustou as dimensões. Edite peso/altura/largura/comprimento dos volumes restantes e tente de novo.

Status do pedido não muda sozinho após pagar/rastrear/entregar → Comportamento esperado se as opções estão em “Não trocar status”. Configure os status desejados em Ecommerce → Configurações → Entregas → Melhor Envio.

Rastreio não chega ao pedido → Verifique se o site é público em HTTPS, se a URL de webhook está cadastrada no app do Melhor Envio e se o pedido possui o código de envio (protocolo) gerado na compra da etiqueta.