MelhorEnvio
A integração com o MelhorEnvio conecta a sua conta ao idworks e sincroniza os fluxos correspondentes ao canal — credenciais, regras de sincronização de produtos, importação de pedidos, conciliação financeira e demais ações específicas dele. A configuração reúne 5 parâmetros distribuídos em 1 grupo(s). Nos pedidos de transportadora Melhor Envio, o idworks também cota o frete, paga e gera a etiqueta de envio em ZPL — veja Como o idworks gera a etiqueta do Melhor Envio?.
Antes de configurar, ative a integração em Configurações → Integrações (aba Integrações Disponíveis), preencha o nome interno e (quando o tipo exigir) passe pelo fluxo de autenticação. A partir daí, os parâmetros abaixo ficam disponíveis na Configuração (ícone de engrenagem) da integração.
Categoria no catálogo do idworks: Transportadora.
Índice
Conceito
Cadastro e autenticação
Parâmetros por grupo
Etiqueta de envio
- Como o idworks gera a etiqueta do Melhor Envio?
- Quais mensagens de erro podem aparecer e o que fazer?
Referência rápida
O que é a integração MelhorEnvio?
É a conexão entre o canal MelhorEnvio e o idworks. Ela controla como dados fluem entre os dois sistemas — depende do tipo da integração (a categoria neste caso é Transportadora), mas em geral cobre uma combinação de credenciais, regras de sincronização, gatilhos automáticos e parâmetros de conciliação.
📍 Onde: menu lateral → Configurações → Integrações → aba Integrações Disponíveis → MelhorEnvio.
Como ativar a integração?
- Acesse Configurações → Integrações.
- Na aba Integrações Disponíveis, busque por MelhorEnvio e clique no botão +.
- Preencha:
- Conta (apenas multi-conta) — empresa dona da integração.
- Nome da Integração — texto livre. Útil para distinguir várias instâncias do mesmo tipo.
- Clique em Salvar.
A integração aparece imediatamente em Minhas Integrações. Dependendo do tipo, o status inicial é Ativo (quando só requer credencial fixa) ou Não Autenticado (quando depende de autenticação externa).
Pré-requisito: privilégio Criar parametrizações empresa.
Como autenticar e validar as credenciais?
Preencha o grupo Credenciais de Acesso (ver tabela abaixo). Quando a integração pede uma autorização externa (o canal abre a tela de login dele para você liberar o acesso), clique em Autenticar Integração na linha da integração (ícone de cadeado) — uma nova aba abre o login do canal e, ao confirmar, a conexão fica liberada. Para integrações com credencial fixa (usuário/senha/chave), basta preencher os campos e salvar.
Depois de salvar, use a ação Validar credenciais (quando disponível) para confirmar que o canal responde. O status na listagem reflete o resultado: Ativo = OK, Erro = credencial inválida ou revogada, Não Autenticado = falta concluir o fluxo de autorização.
Pré-requisito: privilégio Editar parametrizações empresa.
Status
5 parâmetro(s).
| Parâmetro | Tipo | Para que serve |
|---|---|---|
| Integração EDI | Sim/Não | Ative se quiser que a idworks envie o EDI para a transportadora na integração. |
| Integração Tracking | Sim/Não | Ative se quiser que a idworks consulte o tracking [código de rastreamento] dos pedidos enviados pela transportadora. |
| Aviso de Recebimento | Sim/Não | Caso ativado, deve resultar em cotações mais caras com Correios e JadLog apenas, visto que são serviços que apenas estas transportadoras oferecem. |
| Mãos Próprias | Sim/Não | Caso ativado, deve resultar em cotações mais caras com Correios apenas, visto que são serviços que apenas esta transportadora oferece. |
| Incluir valor do seguro | Sim/Não | Caso ativado, vai ser informado o valor a ser segurado e tipicamente é correspondente ao valor dos produtos enviados no pacote. |
Aviso de Recebimento, Mãos Próprias e Incluir valor do seguro valem na cotação e na compra da etiqueta de envio. Veja Como o idworks gera a etiqueta do Melhor Envio?.
Como o idworks gera a etiqueta do Melhor Envio?
Quando o pedido é de uma transportadora com Tipo integração = Melhor Envio, o idworks cota o frete, paga e gera a etiqueta no Melhor Envio, sem você entrar no site. Isso acontece na primeira vez que a etiqueta do pedido é pedida, por exemplo ao finalizar o packing ou ao imprimir a etiqueta pelo pedido.
O caminho é este:
- Cotação. O idworks consulta o Melhor Envio com o CEP do cadastro da empresa (origem), o CEP de entrega do pedido e o peso e as medidas de cada volume. Entre as opções que voltam com preço, escolhe a mais barata. Você não escolhe o serviço.
- Carrinho. Coloca a opção escolhida no carrinho do Melhor Envio, com os dados da empresa (remetente), os do destinatário e a chave de acesso da NF-e do pedido.
- Checkout. Paga o frete com o saldo da sua conta no Melhor Envio.
- Etiqueta. Pede a geração da etiqueta, espera 2 segundos e busca o PDF, com até 3 tentativas e 2 segundos entre elas. O idworks converte o PDF em ZPL.
O que vale saber:
- Parâmetros. Aviso de Recebimento e Mãos Próprias pedem esses serviços na cotação e na compra, e tendem a deixar o frete mais caro. Com Incluir valor do seguro ligada, o valor do pedido vai como valor segurado. Desligada, vai o valor 1.
- Telefone do cliente. Não vai para o Melhor Envio quando a parametrização Excluir telefone NF e EDI está ligada.
- Volumes. O peso e as medidas vêm dos volumes do pedido. Volume sem peso vai com 0,01.
- Qual integração é usada. A integração escolhida no campo Integração da aba Config. Transportadora da transportadora do pedido (veja O que eu configuro na aba Config. Transportadora?). Se a transportadora não tem integração vinculada, usa a integração Melhor Envio da empresa do pedido. Sem token, ou com a integração Inativo ou Não Autenticado, a etiqueta não sai (veja a mensagem "Falta credenciais" em Quais mensagens de erro podem aparecer e o que fazer?).
- Reimpressão. Depois que a etiqueta sai, o idworks guarda o ZPL por alguns dias, e a reimpressão nesse prazo usa essa cópia, sem falar com o Melhor Envio. Passado o prazo, o código do envio no Melhor Envio, gravado nos volumes do pedido, é reaproveitado: o idworks só pede a etiqueta de novo, sem cotar nem pagar outra vez. Se o pagamento falha, o código é apagado e a próxima tentativa recomeça da cotação.
- Não repita o pedido da etiqueta. Espere o resultado antes de pedir a etiqueta de novo. Duas solicitações ao mesmo tempo para o mesmo pedido não têm trava e podem comprar o frete duas vezes.
- ZPL e impressora térmica. A etiqueta é entregue em ZPL, como a das outras transportadoras integradas. Na impressão direta em impressora térmica pelo QZ Tray, o ZPL vai puro para a impressora. A exceção é a parametrização Converter ZPL para PDF para imprimir: com ela ligada, o Packing imprime a etiqueta em PDF (veja A etiqueta sai em branco ou a térmica trava). Na visualização em tela, o idworks converte o ZPL em PDF.
- Etiqueta manual. Se a transportadora tem etiqueta manual ativa, o idworks usa o arquivo anexado ao pedido e não consulta o Melhor Envio. Sem arquivo anexado, aparece "Etiqueta manual não localizada". Veja Como subir etiqueta da transportadora manualmente?.
Quais mensagens de erro podem aparecer e o que fazer?
Os erros de cotação, carrinho, checkout e geração da etiqueta aparecem no aviso da tela e ficam na Timeline (Logs) do pedido (veja Aba Timeline (Logs)), no evento de EDI da transportadora (ação Envio EDI transportadora no Log Pedidos). As exceções são "Falta credenciais" (só na tela) e a falha na conversão para ZPL (só na Timeline), indicadas na tabela.
| Mensagem | Quando aparece | O que fazer |
|---|---|---|
| "Falta credenciais" | A integração Melhor Envio usada pelo pedido não tem token de acesso, ou está com status Inativo ou Não Autenticado (o idworks só lê as credenciais de integração Ativo ou Erro). Aparece só no aviso da tela, sem registro na Timeline. | Autentique a integração de novo (veja Como autenticar e validar as credenciais?). Se ela estiver Inativo, ligue o Status em Editar, em Configurações → Integrações. |
| "nenhuma transportadora atende o endereço. CEP Origem: … CEP Destino: …" | O Melhor Envio não devolveu nenhuma opção com preço para essa origem, esse destino e esses volumes. | Confira o CEP da empresa, o CEP de entrega do pedido, e o peso e as medidas dos volumes. |
| Mensagem de saldo insuficiente | O checkout falhou porque a conta no Melhor Envio não tem saldo para pagar o frete. O texto vem do Melhor Envio. | Recarregue o saldo no Melhor Envio e gere a etiqueta de novo. A nova tentativa recomeça da cotação. |
| Outra mensagem do Melhor Envio na cotação, no carrinho ou no checkout | O Melhor Envio recusou o que foi enviado: algum dado do pedido ou a própria credencial (token vencido ou revogado). A mensagem é a que ele devolve. | Corrija o dado apontado e gere a etiqueta de novo. Se a mensagem for de autenticação, autentique a integração de novo (veja Como autenticar e validar as credenciais?). |
| Mensagem do Melhor Envio ao gerar ou buscar o PDF da etiqueta. Na Timeline ela aparece como "Imprimir: …", às vezes precedida de "Gerar etiqueta: …". Na tela aparece só o texto que o Melhor Envio devolveu. | O frete foi pago, mas o Melhor Envio não gerou ou não entregou o PDF da etiqueta nas 3 tentativas. | Gere a etiqueta de novo. O envio já está pago e não é cobrado outra vez. |
| "Não foi possível converter a etiqueta PDF para ZPL" | O Melhor Envio entregou o PDF, mas o idworks não conseguiu convertê-lo em ZPL. Não aparece aviso na tela: a etiqueta sai sem a parte do Melhor Envio (só a DANFE, se o pedido a imprime junto). O texto fica só na Timeline, com status Sucesso. | Gere a etiqueta de novo. O envio já está pago e não é cobrado outra vez. Se repetir, acione o suporte. |
Privilégios da tela
Esta tela tem privilégios próprios que controlam o que cada usuário pode fazer. Configure os perfis de acesso em Configurações → Perfis de Acesso vinculando os privilégios abaixo aos grupos desejados. Quando o usuário não tem o privilégio, a ação correspondente fica desabilitada na tela.
| Privilégio | Libera |
|---|---|
| Visualizar integrações | Acesso à tela de Integrações e a esta página de configuração. |
| Criar parametrizações empresa | Ativar a integração (botão + no catálogo). |
| Editar parametrizações empresa | Abrir a Configuração (engrenagem), editar nome e status e validar credenciais. |
| Deletar parametrizações empresa | Excluir a integração. |