VibeFox Correios for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e superior (testado na 4.1.0.3).

PHP: 8.0 ou superior.

Contrato dos Correios (somente para preços em tempo real): os preços em tempo real usam a API de preços dos Correios Web Services (CWS) e precisam das credenciais de um contrato dos Correios com cartão de postagem. Você precisa de três dados: seu usuário do Meu Correios (normalmente o CNPJ ou o CPF do contrato), o código de acesso da API e o número do cartão de postagem. Gere o código de acesso no portal dos Correios Web Services (cws.correios.com.br; para homologação, cwshom.correios.com.br). Você também precisa do CEP de onde envia. Sem credenciais, a extensão funciona apenas com preços fixos.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.

Instalação

O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém README.txt, o pacote do OpenCart 3 vfd_correios-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_correios.ocmod.zip. Instale somente o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_correios-oc3-(version).ocmod.zip. A extensão não adiciona modificações OCMOD, então você não precisa atualizar Extensions > Modifications. Em vez do Installer, você também pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Acesse Extensions > Extensions, escolha o tipo de extensão Shipping. Localize VibeFox Correios e clique em Install (o botão verde +).

3. Clique em Edit (o botão de lápis) para abrir a página de configurações.

4. Informe a sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Edit e clique em Activate (veja Chave de licença).

5. Informe o usuário da API dos Correios, o código de acesso, o número do cartão de postagem, o CEP de origem e o serviço. Se a moeda padrão da sua loja não for BRL, informe a taxa para BRL. Preencha os preços fixos para os outros países e como alternativa (veja Configuração), ative Enable Correios e clique em Save.

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_correios.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir do nome do arquivo, e um pacote renomeado não funciona.

2. O pacote aparece na lista de extensões instaladas na mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Acesse Extensions > Extensions, escolha o tipo de extensão Shipping. Localize VibeFox Correios, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).

4. Informe a chave de licença e as configurações como nos passos 4 e 5 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões.

Após a instalação, o método fica desativado até você ativar Enable Correios e salvar. Se você instalar a extensão novamente após uma desinstalação, as configurações dos Correios que você manteve voltam a ser usadas.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Shipping > VibeFox Correios > Edit. As seções são listadas à esquerda. Um único botão Save na parte inferior salva a página inteira sem recarregá-la. Cada salvamento também limpa os preços dos Correios e os tokens da API em cache. Os números podem ser digitados com ponto ou vírgula. Somente administradores com permissão de modificação para esta extensão podem salvar as configurações.

A página mostra avisos quando os preços em tempo real ou o método não podem funcionar: apenas parte das três credenciais está preenchida, o CEP de origem está ausente, a taxa para BRL está ausente em uma loja com outra moeda, ou não há credenciais nem preços fixos. Cada aviso informa se os preços fixos são usados enquanto isso ou se o método fica oculto. Um aviso também aparece se a loja não tiver uma classe de peso com a unidade kg ou uma classe de comprimento com a unidade cm; as unidades dos produtos são então convertidas pelo nome da unidade de sua classe (unidades desconhecidas são lidas como kg ou cm). Verifique System > Localisation > Weight Classes e Length Classes.

O salvamento é recusado com uma mensagem se o título do método estiver vazio ou for inválido (no máximo 64 caracteres, sem < > ; = # { }), se um campo numérico ou um preço em Country prices não for um número igual ou maior que 0, se a taxa para BRL for 0, se Min cart weight for maior que Max cart weight, se o CEP de origem não tiver 8 dígitos, se o código do outro serviço tiver mais de 5 dígitos, ou se Sort order não for um número inteiro. Nada é salvo até você corrigir o valor.

Geral

As configurações se aplicam a todas as zonas geográficas. Você pode limitar o método a uma zona geográfica em Conditions, ou a uma lista de países com Ignore shipping zones.

Enable Correios: mostra ou oculta os Correios na finalização da compra. Padrão: desativado.

Method title: o nome do método de envio exibido ao cliente no carrinho e na finalização da compra. Padrão: Correios. Obrigatório.

Sort order: a posição dos Correios entre os métodos de envio na finalização da compra. Um número inteiro.

API dos Correios (preços em tempo real no Brasil)

Para endereços no Brasil, o preço vem da API de preços dos Correios. Se a API não retornar preço (API fora do ar, CEP não atendido, encomenda grande demais), é usado o preço fixo de Country prices, ou o método fica oculto quando não há um. Os detalhes dos erros vão para o log, nunca para o cliente.

API user: seu login no portal Meu Correios, normalmente o CNPJ ou o CPF do contrato. Limpar esse campo também limpa o código de acesso salvo.

Access code: o código de acesso da API (código de acesso) gerado no portal dos Correios Web Services. Não é a senha do portal. Após salvar, o campo fica vazio e exibe Saved — leave empty to keep it (empty the API user as well to remove it). Informe um novo valor somente para alterá-lo. Para remover o código salvo, esvazie API user e salve.

Posting card: o número do cartão de postagem (cartão de postagem) do seu contrato: 10 dígitos, geralmente começando com dois zeros, por exemplo 0012345678. Números mais curtos são completados com zeros à esquerda. Você pode conferir o número na página Correios Fácil do site dos Correios.

Homologation: usa o ambiente de homologação (teste) dos Correios: as requisições vão para apihom.correios.com.br com um código de acesso de homologação. Desative em uma loja em produção.

Origin CEP: o CEP (8 dígitos) de onde as encomendas são enviadas, por exemplo 01001-000.

Service: o serviço dos Correios precificado na finalização da compra. Códigos de varejo: PAC (04510, padrão), SEDEX (04014), SEDEX 12 (04782), SEDEX 10 (04790), SEDEX Hoje (04804). Códigos de contrato: PAC (03298), SEDEX (03220), SEDEX 12 (03140), SEDEX 10 (03158), SEDEX Hoje (03204), Correios Mini Envios (04227). Os códigos de contrato exigem um cartão de postagem de um contrato que inclua o serviço.

Other service code: opcional, um código de serviço de 5 dígitos do seu contrato que não esteja na lista, por exemplo 03085. Um código mais curto é completado com zeros à esquerda. Quando preenchido, é usado no lugar de Service.

Package format: o tipo de objeto enviado aos Correios.

Default product weight (kg): enviado aos Correios para cada produto que não tenha peso. Padrão: 0.3. Os pesos e as dimensões dos produtos são convertidos a partir das suas classes de peso e de comprimento, e o carrinho é precificado como uma única encomenda.

BRL → store currency rate: o nome do campo mostra a moeda padrão da sua loja, por exemplo BRL → EUR rate. Os preços dos Correios são em BRL. Se a sua moeda padrão não for BRL, informe quantas unidades da sua moeda equivalem a um BRL, por exemplo 0.17. Sem esse valor, os preços em tempo real não são usados. A taxa deve ser maior que 0. Se a sua moeda padrão for BRL, deixe o campo vazio.

Preços fixos (usados para países fora do Brasil, sem credenciais da API e como alternativa quando a API não retorna preço)

Country prices: uma tabela de países com um preço Base e preços conforme o peso do carrinho, na moeda padrão da sua loja, sem impostos: XS até 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL acima de 5 kg. Um preço de tamanho vazio ou zero usa o preço Base. Clique em Add country para adicionar uma linha e no botão × para remover uma. A linha * All other countries define os preços de todos os países sem linha própria. Um país sem linha (e sem *) não recebe preço fixo. Uma linha precisa de pelo menos um preço. Um preço base de 0 significa frete grátis para esse país.

Fixed price per: Order (padrão) cobra o preço uma única vez. Item (price × quantity) o multiplica pelo número de itens no carrinho. Isso se aplica somente aos preços fixos. Os preços em tempo real são sempre calculados para a encomenda inteira.

Condições

Min cart weight (kg): oculta o método quando o carrinho pesa menos que isto. 0 significa sem limite. Não pode ser maior que Max cart weight.

Max cart weight (kg): oculta o método quando o carrinho pesa mais que isto. Padrão: 30. 0 significa sem limite; um campo vazio significa 30 kg. Encomendas PAC e SEDEX dos Correios podem pesar até 30 kg.

Minimum order amount: mostra o método somente quando o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) atinge este valor. Deixe vazio para sempre mostrar.

Free shipping: ativa a entrega grátis a partir do valor indicado abaixo.

Free shipping from: o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) a partir do qual a entrega é grátis. Nesse caso nenhuma requisição é feita à API.

Tax class: a classe de imposto acrescentada ao custo do envio, ou No tax (padrão).

Geo zone: oferece os Correios somente para endereços nesta zona geográfica. All zones (padrão) significa sem limite. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones. Não é usado com Ignore shipping zones.

Disponibilidade sem zonas de envio

Normalmente o método é oferecido na zona geográfica selecionada em Conditions (em todas as zonas, se nenhuma for selecionada).

Ignore shipping zones: oferece o método para os países abaixo, independentemente da zona geográfica correspondente. A Geo zone em Conditions então não é verificada.

Countries: os países de destino para esse modo. Deixe vazio para usar todos os países habilitados na loja. Este campo só é usado quando Ignore shipping zones está ativado.

Avançado

Debug log: grava os cálculos de preço em storage/logs/vfd_crr_debug.log.php (no OpenCart 4, system/storage/logs/vfd_crr_debug.log.php). O arquivo não pode ser lido pela web. Erros da API são sempre registrados, mesmo com esta opção desativada. Usuário da API, código de acesso, cartão de postagem, token e CEPs dos clientes não são registrados. Quando o arquivo chega a 5 MB, ele é movido para vfd_crr_debug.old.log.php e um novo log é iniciado.

Log: mostra o tamanho e as últimas entradas do log de depuração. Clique em Clear log para esvaziá-lo.

Remove data on uninstall: quando ativado, desinstalar a extensão exclui as configurações dos Correios e o log. Quando desativado (padrão), eles são mantidos para uma nova instalação. Os serviços dos Correios salvos com os pedidos são sempre mantidos.

Importação / Exportação

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. O código de acesso não é exportado.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações, por exemplo em outra loja. Os valores são verificados como em um salvamento normal. O código de acesso salvo é mantido.

Como funciona na finalização da compra

Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço dos Correios. Se uma Geo zone estiver definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, os Correios não são oferecidos. Somente produtos com Requires Shipping definido como Yes contam: os demais produtos não somam peso e não entram no valor do pedido. Em seguida a extensão verifica as condições: países permitidos (com Ignore shipping zones), peso do carrinho e valor mínimo do pedido. O valor do pedido é o preço dos produtos que precisam de envio, após o desconto do cupom e antes dos impostos. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada aos Correios.

Para um endereço no Brasil com credenciais definidas, a extensão primeiro obtém um token da API para o seu cartão de postagem. O token também fornece os números do contrato e da agência regional, por isso o preço é o do seu contrato. Depois solicita o preço do serviço escolhido pelo CEP de origem e de destino, pelo peso da encomenda em gramas e pelo tamanho da encomenda em cm. Um preço só é solicitado quando o CEP de destino tem 8 dígitos. Quando todos os produtos têm dimensões, o tamanho da encomenda é estimado a partir delas; caso contrário, é enviado o tamanho mínimo dos Correios. Encomendas acima de 30 kg não são enviadas à API. O preço em BRL é convertido com a sua taxa. O preço é calculado na moeda padrão da loja, arredondado conforme as casas decimais dela, e exibido ao cliente na moeda dele com o imposto da Tax class selecionada.

Cada preço fica em cache por 1 hora. Uma requisição com falha fica em cache por 10 minutos, para que uma queda da API não deixe lenta cada atualização da finalização da compra. O token fica em cache até pouco antes de expirar (no máximo pelo tempo de vida do cache do OpenCart, 1 hora por padrão) e é renovado automaticamente; se os Correios o recusarem, um novo token é solicitado e a requisição de preço é repetida uma vez. O tempo limite da API é de 12 segundos.

Se a API não retornar preço, é usado o preço fixo, ou o método fica oculto quando não há preço fixo. O cliente nunca vê os detalhes dos erros da API; eles vão para o log de depuração.

A extensão calcula somente as tarifas. Ela não obtém os preços internacionais dos Correios (Exporta Fácil, Packet), estimativas de prazo de entrega, etiquetas, pré-postagens, declarações ou rastreamento. Os clientes não podem escolher uma agência ou um armário dos Correios. Serviços adicionais (valor declarado, mão própria, aviso de recebimento) não são adicionados. Ela mostra um único serviço dos Correios por loja, e as taxas de câmbio não são atualizadas automaticamente.

No OpenCart 4, o cliente clica em Choose no bloco do método de envio na página de finalização da compra e escolhe os Correios na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.

Pedidos

Quando um pedido é feito com os Correios, a extensão salva como o preço do envio foi calculado. A página do pedido em Sales > Orders então mostra um bloco Correios com Correios service (por exemplo PAC — contract (03298)) e Price: Live price (Correios API), Fixed price ou Free shipping. O bloco é exibido somente no painel administrativo, não nos e-mails aos clientes, e continua visível quando a extensão está desativada.

No OpenCart 4, a finalização da compra mantém um único pedido e o atualiza quando o cliente confirma novamente. Os dados dos Correios do pedido são atualizados junto com ele e, se o cliente mudar para outro método de envio, o bloco dos Correios deixa de ser exibido para esse pedido.

Chave de licença

A extensão funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Correios é o primeiro bloco da página Extensions > Extensions > Shipping > VibeFox Correios > Edit, acima das configurações. Cole a chave em License key e clique em Activate. Depois disso, o bloco mostra a chave mascarada, o status (por exemplo, a data até a qual a licença está ativa e o seu domínio) e os botões Check now para verificar o status novamente, Change key para informar outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: opencart-shipping-correios e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do painel administrativo (inglês e russo estão incluídos).

Se a chave não for aceita, o bloco informa o motivo, por exemplo Key not found, This key belongs to another product, Domain limit reached ou License expired on seguido de uma data. Depois que o endereço da loja mudar, ou depois que você liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um único domínio: o endereço da loja na configuração do OpenCart. Remover a chave da loja não libera a sua vaga de domínio. Libere-a na sua conta em vibefox.net.

Sem uma chave ativa, os Correios não são exibidos aos clientes na finalização da compra e nenhum preço é calculado. Um usuário administrador conectado ao painel administrativo no mesmo navegador ainda vê o método na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 essa prévia não está disponível: a loja não enxerga o login do painel administrativo, então sem uma chave ativa o método fica oculto para todos. Depois de abrir a página Edit uma vez, um lembrete aparece no Dashboard do painel administrativo. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática quando você abre o Dashboard do painel administrativo ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser informada e, depois, uma vez por semana. Não é necessário um cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

Os Correios não aparecem na finalização da compra: verifique se a licença está ativa e se Enable Correios está ativado. Verifique a Geo zone (ou Ignore shipping zones e Countries), os limites de peso e o Minimum order amount. Sem preço em tempo real, deve existir um preço fixo para o país ou para *. Verifique se os produtos têm Requires Shipping definido como Yes.

O método mostra um preço fixo em vez do preço dos Correios: veja o campo Log na página da extensão. Os erros dos Correios são registrados ali: código de acesso incorreto, serviço fora do seu contrato, CEP não atendido, encomenda acima de 30 kg ou acima dos limites de tamanho. Verifique também se o CEP de origem está preenchido, se o CEP do cliente tem 8 dígitos e, se a moeda padrão não for BRL, a taxa para BRL. Ative Debug log para ver cada cálculo.

A requisição do token falha: verifique o usuário da API, o código de acesso, o cartão de postagem e o ambiente. Um código de acesso de homologação funciona somente com Homologation ativado, e um código de produção somente com ele desativado.

As tarifas parecem desatualizadas após uma mudança: clique em Save na página da extensão. Isso limpa os preços em cache e o token da API.

A página diz "Warning: You do not have permission to modify VibeFox Correios!": o seu grupo de usuários administradores pode apenas visualizar as configurações. Conceda ao grupo a permissão de modificação para extension/shipping/vfd_correios (OpenCart 3) ou extension/vfd_correios/shipping/vfd_correios (OpenCart 4) em System > Users > User Groups.

Para desenvolvedores: o host da API dos Correios pode ser substituído pela configuração vfd_crr_api_url (para testes); ela não tem campo na página de configurações.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Correios. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable Correios, Sort order, Tax class e Geo zone. Os preços e tokens em cache são sempre removidos. Se Remove data on uninstall estiver ativado, as configurações dos Correios e o log de depuração também são excluídos. Se estiver desativado, as demais configurações são mantidas e voltam a ser usadas quando você instalar a extensão novamente. Os serviços dos Correios salvos com os pedidos são sempre mantidos, e os pedidos existentes mantêm o método e o custo de envio.

No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer após a desinstalação, clique em Uninstall (o botão laranja −) ao lado de VibeFox Correios na lista de extensões instaladas e depois em Delete (o botão vermelho de lixeira) para remover o pacote enviado.

Correios é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pelos Correios.