Como Homologar
Saiba como homologar sua API de frete para utilização com o marketplace Americanas.
É possível utilizar a API de Frete para integrar o Marketplace Americanas e informar a cotação de preço e prazo de frete para os produtos integrados. Assim podendo criar a própria política de logística.
Abaixo demonstramos todos os passos para desenvolver o serviço de frete. Uma vez que finalizarem o desenvolvimento, devem entrar em contato com a SkyHub junto com a URL de frete, para que possamos efetuar um teste de carga.

Requisição (Request)

Será feita uma requisição POST na URL configurada para o parceiro, onde será enviado o seguinte conteúdo, veja o exemplo:
{
"destinationZip": 22041001,
"volumes": [
{
"sku": "SKU_PARCEIRO_1",
"quantity": 2,
"price": 15.20,
"height": 0.55,
"length": 0.63,
"width": 0.21,
"weight": 1.00
},
{
"sku": "SKU_PARCEIRO_2",
"quantity": 1,
"price": 53.99,
"height": 0.3,
"length": 0.2,
"width": 0.1,
"weight": 1.75
}
]
}
Campo JSON
Tipo de Dado
Descrição
destinationZip
integer
CEP de destino, será passado como um inteiro. Por exemplo: 5010010 (para o CEP “05010-010″)
volumes
array
Lista de itens
sku
string
SKU do Parceiro
quantity
integer
Número de unidades
price
double
Preço de venda do Produto
height
double
Altura em Metros. Exemplo: será enviado como “0.2”
width
double
Largura em Metros. Exemplo: será enviado como “0.2”
length
double
Comprimento em Metros. Exemplo: será enviado como “0.2”
weight
double
Peso em Quilos (Kg). Exemplo: 0.35 quilos será enviado como “0.35”

Resposta (Response)

O retorno deve ser um JSON válido, seguindo o exemplo abaixo, e com o Header Content-Type com o valor de application/json
A API espera como resposta o json abaixo contendo as seguintes informações:
{
"shippingQuotes": [
{
"shippingCost": 1020.0,
"deliveryTime": {
"total": 10,
"transit": 8,
"expedition": 2
},
"shippingMethodId": "8-Correios",
"shippingMethodName": "Sedex",
"shippingMethodDisplayName": "Sedex"
}
]
}
Todos os campos do response devem ser exatamente iguais. Caso uma letra que esteja no body em caixa baixa e vocês enviem em caixa alta, a request retornará erro.
Campo JSON
Tipo de Dado
Descrição
shippingQuotes
array
Lista com resultados do cálculo de frete. Só será considerada a PRIMEIRA posição
shippingCost
double
Valor do frete
Total
integer
Tempo total da entrega em dias (soma de transit e expedition)
transit
integer
tempo de transporte da mercadoria em dias
expedition
integer
tempo para expedir o produto (informar o prazo CD + prazo Cross-docking quando existir)
shippingMethodId
string
Id da transportadora / tipo de frete selecionado.Campo alfanumérico
shippingMethodName
string
Nome da transportadora / tipo de frete selecionado
shippingMethodDisplayName
string
Nome do frete selecionado exibido para o cliente.

Regras de Implementação

Importante ressaltar que o servidor da Americanas se localiza na Virginia
Para garantir uma boa experiência para os compradores, o serviço de frete do parceiro deve responder em até 500ms. Caso o serviço de frete demore mais do que isso para responder será utilizado o cálculo via planilha de contingência.
Outro ponto importante é que no processo de homologação do frete, não existe vínculo com nenhuma conta em operação, ou seja, o Marketplace fará uma requisição com dados fictícios e aleatórios de um produto de teste que NÃO PERTENCERÁ a nenhum produto da loja, mas ele espera receber sucesso no teste como pontuamos acima. Então se você tiver qualquer tipo de regra em que só dê sucesso na requisição para obter a cotação de frete se o SKU informado existir, provavelmente no ambiente de teste terá erro e não será possível dar andamento à homologação de frete pois é necessário obter sucesso em toda e qualquer requisição que for feita pelo marketplace. Assim como no teste de carga onde serão feitas diversas requisições simultaneamente e todas com dados fictícios.
Outro informativo é que a Americanas sempre irá apresentar a opção mais barata na cotação entre as opções que forem disponibilizadas, e o segundo ponto será a entrega mais rápida, seguindo as mesmas regras do buybox caso tenha mais de uma resposta de cotação positiva.

Exceções

Citamos abaixo alguns exemplos de aplicação do serviço:
  • Caso não haja atendimento para um determinado range de CEP, basta retornar o erro HTTP 404 (NOT FOUND).
{
"message": "Região de entrega não atendida".
}
Como regra de boas práticas, poderá informar uma mensagem padrão seguindo o exemplo acima.
Caso o tempo de resposta ultrapasse o limite de 500 ms, o retorno será de 499 (Timeout na integração), ou seja, a tabela de contingência será acionada. Neste caso é essencial que a loja tenha a tabela de contingência cadastrada no portal da Americanas, para que o frete seja calculado.