Este contenido solo está disponible en portugués.
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:
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
}
]
}{
"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
}
]
}
]
}{
"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.
- 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.
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: