Integração de Frete

Atualmente disponibilizamos duas formas para integração de frete.

Segue o detalhamento abaixo:

Integração Gateway de Frete
Objetivo Disponibilizar cotações de frete ao lojista, conforme disponibilidade de envio do integrador
Documentação https://traydevelopers.zendesk.com/hc/pt-br/articles/360017423314-Gateway-de-Frete
Funcionalidade A integração via Gateway de Frete, não é necessário um aplicativo para disponibilizar as cotações.
Conforme a documentação, você precisará apenas disponibilizar uma url para integrar com a loja do cliente.
A informação da url e o token, são disponibilizado no painel administrativo da loja, dessa forma, para efetuar o cadastro da url do Gateway de Frete,  o integrador deverá informar o lojista para que o mesmo efetue a configuração da url e o token dentro da loja para integração do Gateway de Frete, lembrando que o token deverá ser fornecido por loja que integrar e o mesmo deverá ser fixo.
Esse token do Gateway de Frete, ele não pode ser atualizado, ele deverá ser fixo por loja.

 

Captura_de_tela_de_2020-01-30_16-29-25.png

 

Integração API de Frete
Usabilidade Geralmente utilizada pelos MARKETPLACES e serviços externos, para realizar uma cotação fora da loja
Objetivo Realizar cotações e listar formas de envio mediante configurações na loja, atualizando os pedidos da loja, conforme necessidade
Documentação https://traydevelopers.zendesk.com/hc/pt-br/articles/360013056153-API-DE-FRETE-C%C3%A1lculo-de-Frete
https://traydevelopers.zendesk.com/hc/pt-br/articles/360012934234-API-DE-FRETE-Listagem-de-Formas-de-Envio
Funcionalidade Conforme a documentação informada acima, para acessar alguma informação do cliente e realizar cotação de frete ou inserir rastreio, será necessário realizar ter acesso a API de Frete e API do Pedido.
No entanto, para consumir qualquer tipo de API, atualmente é obrigatório possuir o aplicativo credenciado junto a plataforma, pois através desse aplicativo, será possível gerar uma chave chamada access_token, onde poderá realizar a integração com a Tray e realizar o consumo das APIs.
Para isso, será necessário primeiramente entrar em contato diretamente com a nossa equipe de parcerias

 

No caso de algumas Transportadoras, elas possuem dois tipos de integração:

1- Integração via Gateway de Frete (utilizada para cotação de frete);

2- Integração via Aplicativo - API Rest (utilizada para manutenção de pedidos)

Onde no Gateway elas disponibilizam a url e o token diretamente ao lojista e na integração via aplicativo, utilizando a API de Pedido https://traydevelopers.zendesk.com/hc/pt-br/sections/360001619073-APIs-de-Pedidos ela envia os dados para o pedido do cliente. Lembrando que para integrar o aplicativo, é necessário contatar nossa equipe de parcerias.

 

Captura_de_tela_de_2020-01-30_16-29-35.png

 

Gateway de Frete

Integração com o Gateway de Frete

Para a integração com o Gateway de Frete, deverá ser construído pelo parceiro um modelo de integração que receba e retorne os dados de cotação de frete seguindo o modelo predefinido pela Tray.
A url que integrador disponibilizará para realizar as cotações, deverá ser uma url preparada tanto para enviar o retorno das cotações, quanto para receber as informações da Tray através de parâmetros na url. No caso esses parâmetros necessário para cotação, como os ceps e dados do produto, a Tray irá enviar para a url configurada no Gateway de Frete.
Essa será as informações que serão enviadas de forma automática para sua url, (toda vez que houver uma cotação na loja), desde que a mesma esteja preparada para receber.
A preparação dessa url deverá ser desenvolvida diretamente no lado da aplicação de vocês, da forma que desejarem.

Consultar Informações de Frete

Para a consulta, deverá ser disponibilizada uma URL para envio (via GET) dos dados da consulta de frete.

  • DADOS QUE A TRAY IRÁ ENVIAR PARA A URL DO INTEGRADOR

Abaixo segue os dados enviados para a URL:

Parâmetros Enviados  
token Chave para identificação da loja no gateway
cep CEP de origem (Vendedor)
cep_destino CEP de destino (Comprador)
envio Sempre é enviado o valor 1
num_ped Número do pedido. Sempre enviado 1 na cotação devido não existir o pedido.
prods Produto(s) para calculo do frete.
session_id Código da sessão do usuário

No campo prods são enviados todos os dados dos produtos, onde cada produto é separado por uma barra (/). Já os valores dos produtos são separados por ponto e virgulá (;), onde os valores são respectivamente o comprimento(em metros), largura(em metros), altura(em metros), cubagem(em metros cúbicos), quantidade(unitário), peso(em kg, por unidade), código produto(na plataforma), valor(unitário).

Exemplo da URL enviada para consultar os dados de frete:

http://www.cotacaomodelo.com.br/cotacao?token=123ABC456DEF&cep=04001001 
&cep_destino=04001001&envio=1&num_ped=1&session_id=bengn5mowbdrqkm0rlnilpdtg8& 
prods=0.2;0.2;0.2;0.008;1;0.1;6;43.99/0.3;0.22;0.5;0.033;2;0.235;8;151.33

Retorno da Consultar de Frete

Após a consulta, é necessário o retorno de um XML, em um padrão predefinido, para possibilitar a exibição dessas informações no momento da consulta de frete na loja.

Abaixo segue os campos necessários no XML de retorno:

XML de Retorno  
cotacao Dados da sotação
resultado Resultado(s) da consulta
codigo Código do cotação
transportadora Nome da Transportadora
servico Nome do serviço
transporte Tipo de transporte
peso Peso completo da encomenda
valor Valor da cotação
prazo_min Prazo mínimo de entrega
prazo_max Prazo máximo de entrega
imagem_frete URL da imagem do tipo de frete

Obs: o tamanho da imagem no campo `imagem_frete`, deverá possuir a seguinte configuração: Formato: PNG; Tamanho: 120x120px

  • DADOS E FORMATO QUE A URL DO INTEGRADOR DEVERÁ RETORNAR.

O retorna da url deverá ser no formato exclusivamente em XML, de acordo com o exemplo disponibilizado abaixo:


<?xml version="1.0" encoding="windows­1252"?>
<cotacao>     
	<resultado>         
		<codigo>123</codigo>         
		<transportadora>CORREIOS</transportadora>         
		<servico>ENTREGA RAPIDA</servico>         
		<transporte>TERRESTRE</transporte>         
		<valor>23,51</valor>         
		<peso>0,10</peso>         
		<prazo_min>2</prazo_min>         
		<prazo_max>4</prazo_max>     
	</resultado>     
	<resultado>         
		<codigo>456</codigo>         
		<transportadora>TRANSPORTADORA A</transportadora>         
		<servico>ENTREGA EXPRESSA</servico>         
		<transporte>TERRESTRE</transporte>         
		<valor>15,41</valor>         
		<peso>0,10</peso>         
		<prazo_min>5</prazo_min>         
		<prazo_max>7</prazo_max>     
	</resultado> 
</cotacao>
</code></pre>

Configuração do Gateway na Loja

Para configurar o Gateway de Frete na loja, basta acessar o menu Configurações > Frete e envio na área administrativa da loja.

Após acessar, clique no botão Integrações externas:

Captura_de_tela_de_2020-01-30_16-26-40.png

Mantenha habilitada e digite um nome para identificar a integração. Depois clique em continuar:

Captura_de_tela_de_2020-01-30_16-26-48.png

Preencha a URL do WebService e o token de identificação do cliente (este é o token que será enviado via GET na consulta do frete). Depois clique em Salvar.

Captura_de_tela_de_2020-01-30_16-26-55.png

OBS: No momento que salvar estas configurações, a URL do WebService deve retornar um XML válido, senão as configurações são desconsideradas.

Após salvar, o gateway já estará disponível na consulta da loja.

As APIs de Frete disponibiliza o consultar as informações de frete, por aplicações externas, conforme cadastrados dentro da plataforma Tray.

Cálculo de Frete

Requisição para consultar os dados de diversas formas de envio.

Método GET

https://{api_address}/shippings/cotation/

Código de Exemplo

<?php
    $params["access_token"] = "### Chave de Acesso ###";
    $params["zipcode"] = "04001001";
    $params["products[0][product_id]"] = "123";
    $params["products[0][price]"] = "58.50";
    $params["products[0][quantity]"] = "2";
    $params["products[1][product_id]"] = "456";
    $params["products[1][price]"] = "85.50";
    $params["products[1][quantity]"] = "1";

    $url = "https://{api_address}/shippings/cotation/?".http_build_query($params);

    ob_start();

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
    curl_exec($ch);

    // JSON de retorno  
    $resposta = json_decode(ob_get_contents());
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    ob_end_clean();
    curl_close($ch);

    if($code == "200"){
        //Tratamento dos dados de resposta da consulta.
    }else{
        //Tratamento das mensagens de erro
    }
?>

string URLAuth = "https://{api_address}/shippings/cotation/";

NameValueCollection queryParameters = new NameValueCollection();

queryParameters.Add("access_token", "### Chave de Acesso ###");
queryParameters.Add("products[0][product_id]", "123");
queryParameters.Add("products[0][price]", "58.50");
queryParameters.Add("products[0][quantity]", "2");
queryParameters.Add("products[1][product_id]", "456");
queryParameters.Add("products[1][price]", "85.50");
queryParameters.Add("products[1][quantity]", "1");

List items = new List();

foreach (String name in queryParameters)
    items.Add(String.Concat(name, "=", System.Web.HttpUtility.UrlEncode(queryParameters[name])));

string argsString = String.Join("&", items.ToArray());

WebRequest request = WebRequest.Create(URLAuth + "?" + argsString);
    
request.Credentials = CredentialCache.DefaultCredentials;
    
WebResponse response = request.GetResponse();
  
Console.WriteLine(((HttpWebResponse)response).StatusDescription);
    
Stream dataStream = response.GetResponseStream();
    
StreamReader reader = new StreamReader(dataStream);

string responseData = reader.ReadToEnd();

Console.WriteLine(responseData);
reader.Close();
response.Close();
			

String url = "https://{api_address}/shippings/cotation/";

Map<String, String> mapToConvert = new HashMap<>();
mapToConvert.put("access_token", "### Chave de Acesso ###");
mapToConvert.put("products[0][product_id]", "123");
mapToConvert.put("products[0][price]", "58.50");
mapToConvert.put("products[0][quantity]", "2");
mapToConvert.put("products[0][product_id]", "456");
mapToConvert.put("products[0][price]", "85.50");
mapToConvert.put("products[0][quantity]", "1");

String queryString = "";

for (Entry<String, String> entry : mapToConvert.entrySet()) {
    queryString += entry.getKey()+"="+ entry.getValue()+"&";
}

try {
    URL obj = new URL(url+"?"+queryString);
    HttpURLConnection con = (HttpURLConnection) obj.openConnection();
    
    con.setRequestMethod("GET");
    con.setRequestProperty("User-Agent", USER_AGENT);

    int responseCode = con.getResponseCode();

    BufferedReader in ;
    if (responseCode >= 200 && responseCode < 300){
        in = new BufferedReader(
            new InputStreamReader(con.getInputStream()));
    }else{
        in = new BufferedReader(
            new InputStreamReader(con.getErrorStream()));
    }
    
    String inputLine;
    StringBuilder response = new StringBuilder();

    while ((inputLine = in.readLine()) != null) {
            response.append(inputLine);
    }
    in.close();
    
    String resposta = response.toString();

} catch (Exception ex){
    // Tratamento da Exception
}
			

Parâmetros enviados

Field Type Description
access_token String

Chave de acesso

zipcode Number

CEP do comprador

products Array[]

Código do produto

  product_id Number

Código do produto

  price Decimal

Preço do produto

  quantity Number

Quantidade do produto

  sku String

SKU do produto

Retorno em caso de sucesso (status code 200 ou 201)

Field Type Description
Shipping Object

Dados da forma de envio

  origin Object

Dados de origem

    zipcode String

CEP de origem

    address String

Endereço de origem

    neighborhood String

Bairro de origem

    city String

Cidade de origem

    state String

Estado de origem

  destination Object

Endereço do destinatário

    zipcode String

CEP do destinatário

    address String

Endereço do destinatário

    neighborhood String

Bairro do destinatário

    city String

Cidade do destinatário

    state String

Estado do destinatário

  cotation Object[]

Dados do cálculo de frete

    id Number

Código da forma de envio

    id_quotation Number

Código externo de cotação de frete (Gateway de Frete)

    name String

Nome da forma de envio

    value Decimal

Valor de frete

    min_period Number

Período mínimo

    max_period Number

Período máximo

    estimated_delivery_date Number

Tempo estimado de entrega

    information String

Informações sobre a cotação

    taxe Object

Dados do acréscimo / taxa

      name String

Nome do acréscimo / taxa

      value Decimal

Valor de acréscimo / taxa

 

Json de Retorno

HTTP/1.1 200 OK
{
    "Shipping": {
        "origin": {
            "zipcode": "04001001",
            "address": "Endereço de Origem, 123",
            "neighborhood": "Bairro de Origem",
            "city": "São Paulo",
            "state": "SP"
        },
        "destination": {
            "zipcode": "04001001",
            "address": "Endereço de Destino, 123",
            "neighborhood": "Bairro de Destino",
            "city": "São Paulo",
            "state": "SP"
        },
        "cotation": [
            {
                "id": "1",
                "id_quotation": "1",
                "name": "Nome da Forma de Envio 1",
                "identifier": "forma_envio_1",
                "value": "35.10",
                "min_period": "2",
                "max_period": "8",
                "estimated_delivery_date": "2016-08-15",
                "information": "Prazo de entrega: de 02 a 08 dias úteis.",
                "taxe": {
                    "name": "Emissão de Nota Fiscal",
                    "value": "0"
                }
           },
           {
                "id": "2",
                "id_quotation": "2",
                "name": "Nome da Forma de Envio 2",
                "identifier": "forma_envio_2",
                "value": "16.20",
                "min_period": "3",
                "max_period": "10",
                "estimated_delivery_date": "2016-08-30",
                "information": "Prazo de entrega: 03 a 10 dias úteis.",
                "taxe": {
                    "name": "Emissão de Nota Fiscal",
                    "value": "0"
                }
            }
        ]
    }
}

 

Listagem de Formas de Envio

Requisição para consultar os dados de diversas formas de envio.

Método GET

https://{api_address}/shippings/

Código de Exemplo

Gateway de Frete

<?php
    $params["access_token"] = "### Chave de Acesso ###";

    $url = "https://{api_address}/shippings/?".http_build_query($params);

    ob_start();

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
    curl_exec($ch);

    // JSON de retorno  
    $resposta = json_decode(ob_get_contents());
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    ob_end_clean();
    curl_close($ch);

    if($code == "200"){
        //Tratamento dos dados de resposta da consulta.
    }else{
        //Tratamento das mensagens de erro
    }
?>

string URLAuth = "https://{api_address}/shippings/";

NameValueCollection queryParameters = new NameValueCollection();

queryParameters.Add("access_token", "### Chave de Acesso ###");

List items = new List();

foreach (String name in queryParameters)
    items.Add(String.Concat(name, "=", System.Web.HttpUtility.UrlEncode(queryParameters[name])));

string argsString = String.Join("&", items.ToArray());

WebRequest request = WebRequest.Create(URLAuth + "?" + argsString);
    
request.Credentials = CredentialCache.DefaultCredentials;
    
WebResponse response = request.GetResponse();
  
Console.WriteLine(((HttpWebResponse)response).StatusDescription);
    
Stream dataStream = response.GetResponseStream();
    
StreamReader reader = new StreamReader(dataStream);

string responseData = reader.ReadToEnd();

Console.WriteLine(responseData);
reader.Close();
response.Close();
			

String url = "https://{api_address}/shippings/";

Map<String, String> mapToConvert = new HashMap<>();
mapToConvert.put("access_token", "### Chave de Acesso ###");

String queryString = "";

for (Entry<String, String> entry : mapToConvert.entrySet()) {
    queryString += entry.getKey()+"="+ entry.getValue()+"&";
}

try {
    URL obj = new URL(url+"?"+queryString);
    HttpURLConnection con = (HttpURLConnection) obj.openConnection();
    
    con.setRequestMethod("GET");
    con.setRequestProperty("User-Agent", USER_AGENT);

    int responseCode = con.getResponseCode();

    BufferedReader in ;
    if (responseCode >= 200 && responseCode < 300){
        in = new BufferedReader(
            new InputStreamReader(con.getInputStream()));
    }else{
        in = new BufferedReader(
            new InputStreamReader(con.getErrorStream()));
    }
    
    String inputLine;
    StringBuilder response = new StringBuilder();

    while ((inputLine = in.readLine()) != null) {
            response.append(inputLine);
    }
    in.close();
    
    String resposta = response.toString();

} catch (Exception ex){
    // Tratamento da Exception
}
			

Parâmetros enviados

Field Type Description
access_token String

Chave de acesso

id Number

Código da forma de envio

status Number

Status da forma de envio (Veja Tabela A)

Retorno em caso de sucesso (status code 200 ou 201)

Field Type Description
paging Object

Dados de paginação

  total Number

Total de registros

  page Number

Páginas corrente

  offset Number

Registro inicial da página

  limit Number

Limite de registros

  maxLimit Number

Máximo de registros

sort Object[]

Ordenação

availableFilters String[]

Filtros disponíveis

appliedFilters String[]

Filtros utilizados

Shippings Object[]

Lista das forma de envio

  Shipping Object

Dados da forma de envio

    id Number

Código da forma de envio

    cod String

Código secundário da forma de envio

    name String

Nome da forma de envio

    display_name String

Nome de exibição

    status String

Status da forma de envio (Veja Tabela A)

    gateway Number

 

Json de Retorno

HTTP/1.1 200 OK

{
    "paging": {
        "total": 6,
        "page": 1,
        "offset": 0,
        "limit": 30,
        "maxLimit": 50
    },
    "sort": [
        {
            "id": "asc"
        }
    ],
    "availableFilters": [
        "status",
        "gateway"
    ],
    "appliedFilters": [],
    "Shippings": [
        {
            "Shipping": {
                "id": "1",
                "cod": "1",
                "name": "Sedex",
                "identifier": "sedex_1",
                "display_name": "Sedex",
                "status": "1",
                "gateway": "0"
            }
        }
    ]
}

Tabela A - Disponibilidade da forma de envio (campo status)

Valor Descrição
0 Forma de envio inativa
1 Forma de envio ativa
Bruna Lourencini 
Tem mais dúvidas? Envie uma solicitação

Comentários

    Artigos nessa seção

    Powered by Zendesk