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.
Authorization Header¹	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: [ ]