API de Frete

A implementação dessa operação deverá permitir a consulta do frete de um ou mais produtos para um CEP específico. Será possível consultar, em tempo real, o preço e prazo de um frete para um CEP específico.

Atenção:

A utilização dessa funcionalidade pelo Lojista somente será permitida após a configuração dos passos abaixo:

1. Configurar o Gateway de acesso através do Portal do Marketplace.

2. Importar a tabela de Frete do Lojista através do Portal do Marketplace.

Request API do Lojista

URL (Url de acesso a API do Lojista)

Configuração do Gateway feita no Portal do Marketplace.

METHOD (Método HTTP que acessa a API do Lojista)

POST

HEADERS (Cabeçalho da solicitação)

Content-Type: application/json

Obs: A configuração da autenticação deverá ser feita no Portal do Marketplace e será encaminhado no Header da requisição.

REQUEST (Dados da solicitação)

Campo

Tipo

Obrigatório

Descrição

Exemplo

zipCode

Numérico (Texto)*

Sim

CEP de destino do produto, sem formatação.

32310370

catalogCode

Alfanumérico(A-Za-z0-9_)

Sim

Código do catálogo da loja (Netshoes,Zattini) solicitando a cotação.

CAT_NETSHOESNOVA

products

Coleção

Sim

Lista de produtos sendo cotados.

-

products.skuCode

Alfanumérico(A-Za-z0-9_\-)

Sim

Código do SKU Seller/Lojista.

sku-1234-01

products.quantity

Numérico

Sim

Quantidade de produtos do SKU sendo cotados.

1

products.weight

Decimal

Sim

Peso, em Quilos, por unidade do SKU sendo cotado.

0.5

products.width

Decimal

Sim

Largura, em centímetros, por unidade do SKU sendo cotado.

10.0

products.height

Decimal

Sim

Altura, em centímetros, por unidade do SKU sendo cotado.

20.0

products.length

Decimal

Sim

Comprimento, em centímetros, por unidade do SKU sendo cotado.

30.0

products.preSale

Booleano

Sim

Informação se o SKU está em pré-venda ou não.

true, false

Obs. ¹: Lembrando que um CEP pode iniciar com o dígito zero ("0"). Para maior definição da estrutura do CEP consulte Estrutura do CEP

Exemplo de solicitação (REQUEST)

{
	"zipCode": "01512651",
	"catalogCode": "CAT_NETSHOESNOVA",
	"id": "6dccffe9-52e7-456c-b814-b72ae3e49cc1",
	"products": [
		{
			"skuCode": "sku-1234-01",
			"quantity": 1,
			"weight": 0.5,
			"width": 10.0,
			"height": 10.0,
			"length": 25.0,
			"preSale": true
		}
	]
}

Response API do Lojista

HTTP Status

Código de Status da resposta deverá ser 200 (OK) sempre que for bem-sucedido.

HEADERS (Cabeçalho da resposta)

Content-Type: application/json

RESPONSE (Dados da resposta)

Atributo

Tipo

Obrigatório

Descrição

Exemplo

id

Alfanumérico(A-Za-z0-9\-)

Não

ID único da cotação gerado no Shipping para realização de rastreamento.

6dccffe9-52e7-456c-b814-b72ae3e49cc1

zipCode

Numérico (Texto)¹

Sim

CEP de destino do produto, sem formatação.

32310370

shippingQuotes

Coleção

Sim

Lista de cotações retornadas (Caso algum SKU esteja fora da área de cobertura, encaminhar a coleção vazia)

-

shippingQuotes.skuCode

Alfanumérico(A-Za-z0-9_\-)

Sim

Código do SKU Seller ou SKU do Lojista.

sku-1234-01

shippingQuotes.deliveryOptions

Coleção

Sim

Lista com as opções de entrega disponíveis.

-

shippingQuotes.deliveryOptions.deliveryMinHH

Numérico

Sim

Previsão de tempo, em horas, minimo para entrega do SKU.

10

shippingQuotes.deliveryOptions.deliveryMaxHH

Numérico

Sim

Previsão de tempo, em horas, máximo para entrega do SKU.

100

shippingQuotes.deliveryOptions.freightType

Enumeração

Sim

Tipo de entregra para o SKU.

Expressa ou Normal

shippingQuotes.deliveryOptions.priceInCents

Numérico

Sim

Preço da cotação em centavos do frete para o SKU.

1000

shippingQuotes.deliveryOptions.carrierId

Numérico

Sim

ID da Transportadora

20

shippingQuotes.deliveryOptions.carrierName

Alfanumérico(A-Za-z0-9\-)

Sim

Nome da Transportadora

Jamef

shippingQuotes.deliveryOptions.originWareHouseId

Numérico

Sim

ID do Centro de Distribuição

1

Obs. ¹: Lembrando que um CEP pode iniciar com o dígito zero ("0"). Para maior definição da estrutura do CEP consulte Estrutura do CEP

Exemplo de resposta (RESPONSE)

{
	"id" : "6dccffe9-52e7-456c-b814-b72ae3e49cc1",
	"zipCode" : "30512651",
	"shippingQuotes" : [
	{
		"skuCode" : "127-0004-064-01",
		"deliveryOptions" : [
		{
			"deliveryMinHH" : 360,
			"deliveryMaxHH" : 384,
			"freightType" : "NORMAL",
			"priceInCents" : 1524,
			"carrierId" : 1,
			"carrierName" : "Correios",
			"originWareHouseId" : 1
		},
		{
			"deliveryMinHH" : 120,
			"deliveryMaxHH" : 150,
			"freightType" : "EXPRESSA",
			"priceInCents" : 3575,
			"carrierId" : 2,
			"carrierName" : "Jamef",
			"originWareHouseId" : 1
		}
		]
	}
	]
}

Regras para a utilização

É muito importante que sejam seguidas fielmente as nomenclaturas/documentação aqui disponibilizadas.

Os seguintes requisitos funcionais precisam ser respeitados:

- Deverá ser gerada uma cotação de frete para cada tipo de entrega, objeto de resposta: deliveryOptions.

- Deverá ser retornado somente os tipos de entrega que são comuns a todos os SKUs da cotação.

- Deverá ser retornado somente os tipos de entregas conhecidos pela plataforma de e-commerce: Expressa, Normal ou Super expressa.

- Caso algum SKU esteja fora da área de cobertura, encaminhar a coleção de ShippingQuotes vazia.

As seguintes regras serão executadas no modo de contingência:

- Em caso de erro na resposta ao Consultar o Frete (diferente de 200) será utilizado o modo de contingência.

- Em caso do conteúdo da resposta inválida será utilizado o modo de contingência.

Os seguintes requisitos não funcionais precisam ser respeitados:

- Tempo de resposta menor que 400 ms.

- Disponibilidade de 99,9%, 24 horas, sete dias por semana.

- Suportar a volumetria de 500 requisições por minuto ou 9 por segundo.

OBS.: O calculo é realizado baseando em dias uteis.

Configuração da autenticação

O Lojista deve configurar o Gateway através do Portal do Marketplace, abaixo os tipos de autenticação suportados:

Tipo

Atributo

Obrigatório

Descrição

Exemplo

Endereço do Endpoint (URL)

-

Sim

URL da api do Lojista que será consumida ao consultar frete.

https://lojista.com/api/v1/freight

Basic Authentication¹

-

Não

Autenticação que utiliza os atributos usuário e senha. O seguinte parâmetro será encaminhado no cabeçalho da requisição: Authorization.

username

Sim

Usuário da requisição.

admin

password

Sim

Senha da requisição.

******

Token Authentication¹

-

Não

Autenticação que utiliza os atributos cliente id e token de acesso. Os seguintes parâmetros serão encaminhados no cabeçalho da requisição: APP_KEY e APP_TOKEN.

App Token

Sim

Token da aplicação.

eyJ0eXAiOiJKV1QiLA0KICJhbGciO

App Key

Sim

Chave da aplicação.

cGxlLmNvbS9pc19yb290Ijp0cnVlfQ

Authorization Header¹

-

Não

Autenticação pelo cabeçalho da requisição. O seguinte parâmetro será encaminhado no cabeçalho da requisição: Authorization.

Header

Sim

Chave de autorização.

BASIC bmV0c2hvZXM6cm9ja3M=

Obs. ¹: Pelo menos um tipo de autenticação deve se selecionado.

Abaixo um exemplo (wireframe) da configuração no portal:

Endereço do Endpoint (URL): [ ]
	
	(*) Basic Autentication:
	- Username: [ ] - Password: [ ]
	
	( ) Token Authentication:
	- App Token: [ ] - App Key: [ ]
	
	( ) Authorization Header
	- Header: [ ]