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)

(*) Em caso de produto variável, o SKU na requisição será o da variação.

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.

Last updated