Para garantir uma ampla gama de integrações e um maior número de transportadoras disponíveis para uso em nossa base, a UoouSolutions criou uma solução em que qualquer Transportadora e Hub/Gateway de Frete que já tenha desenvolvido uma integração com a DLoja Virtual/HostGator também possui autonomia para integrar com a nossa plataforma.

De forma simplificada, nossa plataforma será responsável por chamar uma URL da transportadora/Hub, enviando informações essenciais para a cotação, como o CEP de origem, CEP de destino e produtos do carrinho (com seus respectivos pesos, dimensões e quantidades). Por outro lado, a Transportadora/Hub será responsável por retornar os custos e prazos disponíveis (podendo retornar um ou mais serviços de transporte).


Dessa forma, qualquer Transportadora/Hub/Gateway de Frete que integre com a plataforma DLoja Virtual/HostGator também poderá integrar conosco (ressaltando que todo o desenvolvimento fica por conta da própria empresa).


Além disso, se sua empresa possui um sistema interno de cotação de frete (para cenários de Atacado/B2B) e você deseja disponibilizar essas cotações no seu e-commerce, é possível fazer isso através desta documentação.


Posto isso, caso necessite de qualquer ajuda, disponibilizamos um ambiente de homologação para a realização de testes e validação da cotação. Para isso, basta enviar um e-mail para suporte@uoou.com.br.

Antes de entender exatamente qual o formato da requisição a ser realizada, é crucial compreender alguns conceitos básicos. Acompanhe-os abaixo.



O que é o gateway de frete? 


Com o objetivo de viabilizar a conexão com diversas transportadoras e Hubs de frete compatíveis com a DLoja Virtual/HostGator, a UoouSolutions concebeu uma ferramenta denominada Gateway de Fretes - Integração via API. No entanto, é imperativo respeitar a padronização de requisição e de resposta esperada.


E o que é uma requisição?


Pode ser descrita como a troca de informações entre dois ou mais servidores. No contexto da pesquisa de custos de frete, ocorre um pedido transmitido ao servidor da transportadora/Hub, contendo os detalhes indispensáveis para o cálculo. Subsequentemente, uma resposta é remetida a nós, contendo dados como custo, tempo estimado e outros.


Contudo, tenha sempre em mente que a tarefa de desenvolver essa conexão é da transportadora ou Hub selecionado para realizar as estimativas de frete em sua loja.



Padronização da requisição

Ao solicitar uma estimativa de custo de frete por meio da plataforma, é imprescindível seguir uma padronização específica, utilizando variáveis formatadas em JSON, através do método POST. As variáveis a serem incluídas são as seguintes:


Essas informações serão enviadas pela UoouSolutions para uma URL fornecida pela Transportadora/Hub/Gateway de Frete.


token: Um token de autenticação provido pela transportadora, que será previamente configurado dentro do Tipo de Frete.

cep_origem: O CEP da loja, de onde as mercadorias serão despachadas, que é previamente configurado no Tipo de Frete.

cep_destino: O CEP fornecido pelo cliente durante a solicitação da estimativa.


Em seguida, é necessário enviar um conjunto de informações abrangendo todos os produtos presentes no pedido, incluindo:


quantidade: O total de unidades do mesmo produto.

preco: O valor de venda do produto na loja.

peso: O peso em quilogramas configurado para o produto.

largura: A largura em centímetros configurada para o produto.

altura: A altura em centímetros configurada para o produto.

comprimento: O comprimento em centímetros configurado para o produto.

sku: O SKU do produto na loja.


Aqui está um exemplo ilustrativo em que há apenas um produto na estimativa. Caso o carrinho do cliente contenha produtos diferentes, o objeto dentro da seção "produtos" será replicado:


Exemplo:

{
    "produtos": [
        {
            "quantidade": 1,
            "preco": 249.90,
            "peso": 0.100,
            "largura": 8,
            "altura": 4,
            "comprimento": 11,
            "sku": "JBVL00011"
        }
    ],
    "token": "JMF2217PNRDL55uo0U",
    "cep_origem": "89030000",
    "cep_destino": "89010904"
}


Caso o cliente solicite uma estimativa de preço para várias unidades do mesmo item, a variável "quantidade" será ajustada conforme a escolha do cliente. Entretanto, os outros campos permanecerão inalterados, uma vez que correspondem à medida ou ao valor individual do produto.


Posteriormente, a transportadora aplicará suas regulamentações de frete e cálculos de custo, enviando-nos uma resposta conforme descrito no tópico subsequente.



Padronização da resposta

No retorno da estimativa de preços realizada, a plataforma aguardará os dados seguindo as variáveis abaixo, formatadas em JSON:


id_cotação: Identificação da estimativa no sistema da transportadora.


Posteriormente, é necessário enviar um Array denominado "cotacao", que compreende todas as estimativas obtidas na requisição anterior. Não há limite para a quantidade de objetos que podem ser transmitidos nesse cenário.


codigo: ID da transportadora.

valor: Custo do frete.

peso: Peso total do pedido.

prazo: Período estimado de entrega do pedido.

transportadora: Denominação da transportadora, a ser exibida ao cliente.

servico: Categoria de serviço, que será apresentada ao cliente (exemplos: "Expresso", "Econômico").

frete_gratis: Caso o pedido seja elegível para frete grátis, esta variável deve conter "1"; caso contrário, "0".

imagem: Imagem a ser exibida no carrinho do cliente. Se nenhum dado for fornecido nessa variável, a imagem configurada na plataforma será utilizada (detalhes adicionais em 3.3).


Entre as variáveis mencionadas acima, apenas as seguintes são obrigatórias para envio: "transportadora", "valor", "peso", "prazo" e "frete_gratis".


Exemplo:

{
    "cotacao": [
        {
            "codigo": "4422",
            "valor": 19.50,
            "peso": 1,
            "prazo": 5,
            "transportadora": "Correios",
            "servico": "SEDEX",
            "frete_gratis": 0,
            "imagem": ""
        }
    ],
    "id_cotacao": "11LEUbfrk55oll-5110-kjef-39dbvj-0001"
}


E caso você tenha algum questionamento referente à padronização apresentada, sinta-se à vontade para nos contatar por meio do e-mail suporte@uoou.com.


Como configurar o Gateway de Fretes - Integração via API

Procedimento de Estabelecimento na Plataforma:


Para configurar a aplicação em sua loja, siga o passo a passo descrito abaixo:

1ºPasso: Na área administrativa, no menu "CONFIGURAÇÃO", acesse a opção "Tipos de Frete".



2ºPasso: Na listagem dos fretes, busque pelo botão "+ Criar tipo de frete".



3ºPasso: Já na listagem dos fretes, escolha a opção "Gateway de Fretes - Integração via API".


Configurando o novo tipo de frete

Os tipos de frete possuem 6 abas de configuração: "Geral", "Canais", "Configurações do Frete", "Regras de Exibição", "Rastreamento", "Performance" e "Cálculo de ICMS". A seguir, veremos como configurar cada uma dessas abas:


Geral

Nas configurações gerais do tipo de frete, você deve preencher as informações básicas para que seja possível identificar esse frete facilmente.


Canais

Nesta aba, serão listados todos os seus canais. Assim, você deverá selecionar os canais que deseja vincular a essa transportadora.


Configurações do Frete

Nas configurações de frete, você irá estruturar as configurações para a ativação da transportadora escolhida.

Configurações de Integração

  • No campo "Formato", você deverá informar qual é o formato da integração. Atualmente, os formatos disponíveis são: Padrão UoouSolutions, Compatibilidade DLoja Virtual/HostGator e Compatibilidade Tray. 
  • Em "Token", você deve informar a sua chave de autenticação necessária para acessar a API. 
  • No "Endpoint", você deve informar a URL fornecida pela transportadora/hub, que será utilizada para realizar a cotação.
  • Já em "CNPJ", você deve informar seu CNPJ utilizado no contrato.
  • E no campo "CEP de Origem", informe o seu CEP, que é a origem de onde as mercadorias serão enviadas.

Embalagem

  • Os campos "Largura", "Altura" e  "Comprimento" devem ser preenchidos com as dimensões mínimas da embalagem em que você despachará as suas encomendas.  
  • Já o campo "Adicional de Peso" representa o peso adicional, que serve apenas como uma medida de segurança para o cálculo do frete. Recomendamos que seja informado valor 100, que indica 100g. 

Prazo

  • Em "Adicional de Prazo" você pode adicionar uma quantidade, em dias, ao prazo calculado pela transportadora. Esta margem existe pois o cálculo retornado para o frete é uma estimativa, sendo que quando você for efetivamente despachar a mercadoria pode haver uma diferença no prazo (por questões de qual embalagem será utilizada, os valores de peso e volume informados nos produtos, etc.). Além disso, pode ser que você tenha algum atraso para despachar suas mercadorias (que deveria ocorrer logo após a aprovação do pagamento do cliente). Logo, para evitar atrasos, pode-se preencher este campo e adicionar uma margem de segurança.
    Exemplo: O prazo do frete original calculado foi de 3 dias e você preencheu neste campo uma margem de 3 dias, logo, o cliente verá o prazo deste frete como 6 dias. 

Valor

  • Em "Adicional Fixo de Preço", você pode adicionar uma margem de segurança ao preço cobrado neste tipo de frete. Exemplo: O valor do frete original calculado foi de R$ 10,00 e você preencheu neste campo uma margem de R$ 5,00, logo, o cliente verá o preço deste frete como R$ 15,00.
  • Em "Adicional Percentual de Preço", é possível adicionar uma margem percentual de segurança ao preço cobrado neste tipo de frete.
    Exemplo: O valor do frete original calculado foi de R$ 10,00 e você preencheu este campo com 20% (R$ 2,00), sendo assim, o valor que será exibido para o usuário será de R$ 12,00.
  • Em "Frete grátis a partir de", você pode, caso desejar, inserir um valor para frete grátis para esta transportadora. 


Observação: Se você inserir um adicional percentual e um adicional fixo ao pedido, aplicará dessa forma: 

O Valor retornado (R$ 10,00) + Adicional Fixo de Preço (R$ 10,00)) + Adicional Percentual de Preço (20% - igual a R$ 4,00) = 20 + 4 = 24

ou seja, o Adicional Percentual de Preço é calculado sobre o valor retornado pela transportadora e também sobre o adicional fixo de preço informado.



Regras de Exibição

Após as configurações do Frete estarem completas, você deve configurar as "Regras de Exibição" conforme desejar. 

  • Em "Região" você deve escolher a região em que deseja que esse frete funcione. As regiões padrões cadastradas na loja virtual são todos os estados brasileiros individualmente, regiões (sul, centro-oeste etc) e o país Brasil. Caso desejar, você pode criar outras regiões como, por exemplo, a cidade a onde você tem sua empresa e as cidades ao lado dela. Saiba mais sobre regiões em: https://ajuda.uoou.com.br/solutions/article/26000048024-como-cadastrar-uma-regiao
  • Em "Grupos de cliente", é possível selecionar grupos específicos para visualizar esse tipo de frete. Caso queira disponibilizar esse frete para todos os clientes, basta deixar esse campo em branco.
  • Em "Ocultar quando não conseguir calcular o frete?", você consegue definir se irá exibir esse frete ou não, caso ele não consiga, por algum motivo, calculá-lo.
  • O campo "Categoria de frete" serve para escolher qual categoria de frete criada (caso tenha) você quer designar a esse frete em especifico. Caso você não possua categorias de fretes ou esse frete abrange todas as categorias, o campo pode permanecer vazio. 
  • O campo "Regra da categoria" só deve ser configurado caso uma categoria de frete tenha sido escolhida. Caso contrário, você pode deixar a opção "Pelo menos 1 produto do carrinho deve possuir a categoria de frete" marcada. 
  • Em "Visibilidade", é possível limitar a visualização do tipo de frete por "preço", "peso" e "volume" do pedido de um valor x, até um valor y. 



Rastreamento

Na aba de rastreamento, dependendo da transportadora é possível configurar um padrão de link de rastreio, que será automaticamente enviado para o cliente assim que o pedido for colocado como em transporte. Se o link de rastreio for uma página pública, pode-se configurar (dependendo do caso) para marcar automaticamente o pedido como entregue.

  • No campo "Link de Rastreamento - Formato" você deve inserir o link de rastreamento da transportadora.
  • Em "Entregue se existirem as palavras", você  pode escrever palavras que serão utilizadas para determinar se uma entrega já foi realizada ou não. É importante ressaltar que as palavras devem ser separadas por ponto e vírgula. Esse campo não é obrigatório.


Performance

Esta aba tem como objetivo principal se preparar para eventuais situações onde a plataforma da transportadora possa apresentar lentidão ou fique fora do ar. Com isso, seu sistema evita esses cenários e não tem o desempenho prejudicado. 

  • No campo "Tempo máximo de resposta", você deve preencher o tempo máximo de resposta (em segundos) para que esse tipo de frete seja retornado. Perceba que no exemplo em questão foi selecionada a opção "20 segundos". Ou seja, caso em 20 segundos a transportadora não forneça um retorno, o cálculo do mesmo será interrompido. 
  • Em "Tipo de frete de contingência", é possível selecionar o tipo de frete de contingência na situação de não ser possível calcular o frete. Basicamente a contingência funciona da seguinte forma: Quando o "Tempo máximo de resposta" é atingido e a transportadora não fornece um retorno, outro tipo de frete, que já deve estar previamente cadastrado, pode ser utilizado para retornar essas informações.



Cálculo de ICMS

Já nesta aba, você terá condições para habilitar o adicional de ICMS, que é calculado com base no estado de origem, a ser configurado dentro do tipo de frete, e do estado de destino, definido pelo cliente na finalização da compra. 



Sendo assim, a transportadora está configurada e pronta para ser utilizada em sua plataforma!