Como Homologar

Nesta seção é apresentado o processo de homologação de frete para utilização com o marketplace Americanas

É possível criar a própria política de logística ao implantar uma URL de frete que será responsável pela cotação do cálculo (de frete) para os produtos integrados. Abaixo é apresentada a estrutura esperada para a cotação do frete via URL.

Uma vez desenvolvida, a URL deverá ser encaminhada ao time de API para que sejam realizadas as devidas validações.

Regras para a implementação

Para garantir uma boa experiência para os compradores, o serviço de frete deve responder em até 400 ms. Caso o serviço demore mais do que 400 ms para responder, o cálculo de frete será realizado através da planilha de contingência cadastrada pelo seller no portal do marketplace.

Em relação a cotação para o cliente, o marketplace Americanas irá apresentar a opção mais barata entre as disponíveis; o segundo ponto é a entrega mais rápida, seguindo as regras do buybox, caso haja mais de uma resposta de cotação positiva.

Importante ressaltar que o servidor da Americanas se localiza na Virgínia.

A localização do servidor deve ser levada em consideração para que a URL seja capaz de responder em tempo adequado.

Os dados utilizados para a homologação são fictícios, não possuindo vínculo com nenhuma conta em produção, ou seja, serão realizadas requisições com dados aleatórios de um produto de teste que não pertencerá a uma loja em produção, porém espera-se sucesso na requisição.

Caso a URL a ser validada possua regras que impeçam o sucesso ao ser informado um SKU fictício não será possível dar andamento ao processo de homologação.

A homologação consiste em garantir que a URL informada esteja respondendo em tempo hábil (até 400 ms) e que não existam impeditivos para a cotação do frete, que deverá levar em consideração especialmente as informações de CEP e dimensões apresentadas.

POST - Teste unitário para homologação

Para validação serão realizadas requisições unitárias do método POST para a URL desenvolvida.

Todas as requisições contarão com dados fictícios e por este motivo é imprescindível que a URL não possua bloqueios de SKU.

Request body:

{
    "destinationZip": 22041001,
    "volumes": [
        {
            "sku": "SKU_1",
            "quantity": 2,
            "price": 15.20,
            "height": 0.55,
            "length": 0.63,
            "width": 0.21,
            "weight": 1.00
        },
        {
            "sku": "SKU_2",
            "quantity": 1,
            "price": 53.99,
            "height": 0.3,
            "length": 0.2,
            "width": 0.1,
            "weight": 1.75
        }
    ]
}

Formato dos dados:

Campo JSON	Tipo de Dado	Descrição
destinationZip	inteiro	CEP de destino que 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	Unidades da venda
price	double	Preço de venda do produto
height	double	Altura em metros
width	double	Largura em metros
length	double	Comprimento em metros
weight	double	Peso em quilos (Kg)

Example request:

curl --location --request POST 'https://URL_PARCEIRO' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "destinationZip": 22041001,
    "volumes": [
        {
            "sku": "SKU_1",
            "quantity": 2,
            "price": 15.20,
            "height": 0.55,
            "length": 0.63,
            "width": 0.21,
            "weight": 1.00
        },
        {
            "sku": "SKU_2",
            "quantity": 1,
            "price": 53.99,
            "height": 0.3,
            "length": 0.2,
            "width": 0.1,
            "weight": 1.75
        }
    ]
}'

Resposta (response) esperada

Ao executar a requisição apresentada acima, a API espera como resposta um JSON válido contendo as seguintes informações:

Response esperado:

200 [Success] - OK: Deverá ser retornado um body cujo padrão pode ser visualizado a seguir:

{
  "shippingQuotes": [
    {
      "shippingCost": 13,
      "deliveryTime": 3,
      "shippingEstimateId": "b413bfe83d704c76bd4f81f99abf30c9",
      "shippingMethodId": "8-Correios",
      "shippingMethodName": "Sedex",
      "shippingMethodDisplayName": "Sedex"
    }
  ]
}

Formato dos dados:

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
deliveryTime	integer	Objeto que trará as informações de prazo da entrega
shippingEstimateId	string	Identificador único gerado durante o cálculo do frete
shippingMethodId	string	ID da transportadora/tipo de frete selecionado
shippingMethodName	string	Nome da transportadora/tipo de frete selecionado
shippingMethodDisplayName	string	Nome do frete selecionado exibido para o cliente

Todos os campos do response devem ser apresentados conforme descritos.

Caso esteja informando em caixa alta uma letra que deve ser em caixa baixa, a requisição retornará erro.

Exceções

Caso não haja atendimento para um determinado range de CEP, basta retornar o erro HTTP 404 [not found]. Sugerimos a inclusão de uma mensagem padrão conforme exemplo abaixo:

{
  "message": "Região de entrega não atendida".
}

Importante reforçar que caso o tempo de resposta ultrapasse o limite de 400 ms haverá um retorno 499 [timeout] e a tabela de contingência será acionada.

Neste caso, é essencial que a loja possua uma tabela de contingência cadastrada e atualizada no portal da Americanas, evitando que perca vendas.