Ambientes disponiveis: Homologação e Staging e Produção.
1. Introdução
- Objetivo: Permitir o retorno parcial de itens na primeira chamada do endpoint /freights quando todos os estoques requisitados não estiverem disponíveis. Atualmente, essa funcionalidade é implementada através da estrutura de grupos na cotação, o que demanda um alto processamento e, como consequência, aumenta o tempo de resposta dessa cotação.
Permitindo o retorno parcial na primeira chamada, vai ser possivel que o sistema retorne quais itens serão retornados com entrega valida para aquele carrinho, sem uma segunda ou terceira “subcotação”.
Beneficios:
- Melhoria na Experiência do Usuário: A resposta mais rápida e precisa permite ao usuário saber imediatamente quais itens podem ser enviados, melhorando a experiência de navegação e compra.
- Eficiência de Processamento: Reduz a carga no sistema, pois evita chamadas adicionais para calcular cotações de itens fora de estoque. Com isso, o sistema processa menos dados em uma etapa inicial.
- Otimização do Tempo de Resposta: A consulta inicial retorna mais rapidamente, já que lida com um menor volume de dados, agilizando o processo de cotação.
2. Escopo
- Critérios de priorização:
- Entrega completa (todos os itens em uma filial)
- Entrega com split (itens em diferentes filiais) – Apenas shipment
- Entrega parcial (itens em diferentes filiais, todos ou apenas um)
- Entrega parcial com split (itens em diferentes filiais, não contemplando todos da request)
- Caso o split esteja desabilitado na modalidade e houver duas ou mais entregas saindo de filiais diferentes nos partialDeliveries (Sem entregas completas), a entrega incompleta será priorizada de acordo com os critérios da modalidade.
A funcionalidade só passará a ser considerada quando parametrizado via Cockpit, na tela de Canais com a flag “Habilitar Cotação Parcial" no respectivo canal.
3 -Regras de Negócio:
- Disponibilidade de Estoque: A cotação parcial só é aplicada quando a quantidade disponível de pelo menos um item for menor que a solicitada em uma mesma filial.
- Nivel de configuração: A configuração é realizada a nível de canais de venda;
- Exceção: Os itens faltantes retornarão na estrutura de exceptions do método (Envio pela loja ou retira em loja).
- Shipment: A exception será retornada a nivel de modalidade de entrega, assim como é atualmente.
- Pickup: Será retornado a nivel de filial (location).
4. Exemplo de Retorno
Solicitação de Cotação (JSON):
{ "destinationZipcode": "01414010", "clientId": "qa", "channelId": "site", "groups": { "qatest": { "items": { "skuId-003": { "quantity": 1, "length": 100, "height": 100, "weight": 100, "width": 100, "price": 10 }, "skuId-004": { "quantity": 2, "length": 200, "height": 200, "weight": 200, "width": 200, "price": 20 } } } } }Resposta da Cotação (JSON): Novo campo que indica se é uma cotação parcial: "isPartialDelivery"
Json completo:
"pickup": {
"locationId-003": {
"method": "PICKUP",
"allowReservation": true,
"allowPrePaidPickup": true,
"fulfillments": {
"F1": {
"id": "F1",
"locationId": "locationId-003",
"locationType": "Own Store",
"location": {
"address": {
"zip": "03425070",
"city": "São Paulo",
"state": "SP",
"number": "7221",
"country": "Brasil",
"address1": "Av. Dra. Ruth Cardoso",
"address2": "Conj 701, Bloco A, Departamento 20, Sala 02, Edifício Birmann 21",
"neighbourhood": "Pinheiros",
"defaultBilling": false,
"defaultShipping": false
},
"tradingName": "locationId-003",
"businessName": "locationId-003",
"cnpj": "07695739000104",
"latitude": -30.93265056,
"longitude": -52.03780316
},
"type": "PICKUP",
"freightCosts": {
"deliveryEstimatedDate": "2024-11-11",
"deliveryEstimate": {
"days": 6,
"hours": 3,
"minutes": 3,
"dateTime": "2024-11-11 12:03"
},
"handlingPrice": 3,
"extraDeadlineTime": 1,
"handlingTime": 3,
"handlingHours": 3,
"handlingMinutes": 3,
"totalUtilDays": 4,
"recessDays": 2,
"totalPrice": 3,
"rulePrice": null,
"stockArrivalTime": 0,
"totalTime": 6,
"ruleTime": null
},
"appliedRules": {},
"items": {
"skuId-003": {
"sku": "skuId-003",
"lotId": null,
"quantity": 1,
"deliveryDate": null,
"daysToDelivery": 0,
"salesStartsAt": null,
"salesEndsAt": null,
"billingStartsAt": null,
"groupIds": [
11,
12,
13,
14,
56
],
"categoryIds": [
"categoryId-002",
"categoryId-003",
"categoryId-004"
],
"availableQuantity": 99999999
}
},
"stockTypes": {
"skuId-003": {
"PHYSICAL": 1
}
}
}
},
"isPartialDelivery": true,
"price": 3,
"time": 6,
"reserveDeadline": 2,
"pickupDeadline": 2,
"deliveryEstimatedDate": "2024-11-11",
"utilDays": 4,
"beforeRules": {}
},
"locationId-004": {
"method": "PICKUP",
"allowReservation": true,
"allowPrePaidPickup": true,
"fulfillments": {
"F1": {
"id": "F1",
"locationId": "locationId-004",
"locationType": "Seller",
"location": {
"address": {
"zip": "04425070",
"city": "São Paulo",
"state": "SP",
"number": "7221",
"country": "Brasil",
"address1": "Av. Dra. Ruth Cardoso",
"address2": "Conj 701, Bloco A, Departamento 20, Sala 02, Edifício Birmann 21",
"neighbourhood": "Pinheiros",
"defaultBilling": false,
"defaultShipping": false
},
"tradingName": "locationId-004",
"businessName": "locationId-004",
"cnpj": "07695739000104",
"latitude": -30.93265056,
"longitude": -52.03780316
},
"type": "PICKUP",
"freightCosts": {
"deliveryEstimatedDate": "2024-11-12",
"deliveryEstimate": {
"days": 7,
"hours": 4,
"minutes": 4,
"dateTime": "2024-11-12 13:04"
},
"handlingPrice": 4,
"extraDeadlineTime": 1,
"handlingTime": 4,
"handlingHours": 4,
"handlingMinutes": 4,
"totalUtilDays": 5,
"recessDays": 2,
"totalPrice": 4,
"rulePrice": null,
"stockArrivalTime": 0,
"totalTime": 7,
"ruleTime": null
},
"appliedRules": {},
"items": {
"skuId-004": {
"sku": "skuId-004",
"lotId": null,
"quantity": 2,
"deliveryDate": null,
"daysToDelivery": 0,
"salesStartsAt": null,
"salesEndsAt": null,
"billingStartsAt": null,
"groupIds": [
11,
12,
56,
92,
150
],
"categoryIds": [
"categoryId-002",
"categoryId-003"
],
"availableQuantity": 996
}
},
"stockTypes": {
"skuId-004": {
"PHYSICAL": 2
}
}
}
},
"isPartialDelivery": true,
"price": 4,
"time": 7,
"reserveDeadline": 6,
"pickupDeadline": 6,
"deliveryEstimatedDate": "2024-11-12",
"utilDays": 5,
"beforeRules": {}
}
},
"pickupExceptions": [
{
"locationId": "locationId-001",
"canReceiveFromStore": true,
"items": [
{
"skuId": "skuId-003",
"lotId": null,
"totalRequested": 1,
"totalAvailable": 999
},
{
"skuId": "skuId-004",
"lotId": null,
"totalRequested": 2,
"totalAvailable": 0
}
]
},
{
"locationId": "locationId-002",
"canReceiveFromStore": true,
"items": [
{
"skuId": "skuId-003",
"lotId": "lot-id-L3",
"totalRequested": 1,
"totalAvailable": 9999
},
{
"skuId": "skuId-004",
"lotId": null,
"totalRequested": 2,
"totalAvailable": 0
}
]
},
{
"locationId": "locationId-003",
"canReceiveFromStore": true,
"items": [
{
"skuId": "skuId-003",
"lotId": null,
"totalRequested": 1,
"totalAvailable": 99999999
},
{
"skuId": "skuId-004",
"lotId": null,
"totalRequested": 2,
"totalAvailable": 0
}
]
},
{
"locationId": "locationId-004",
"canReceiveFromStore": true,
"items": [
{
"skuId": "skuId-003",
"lotId": null,
"totalRequested": 1,
"totalAvailable": 996
},
{
"skuId": "skuId-004",
"lotId": null,
"totalRequested": 2,
"totalAvailable": 996
}
]
}
"shipment": {
"a2b3b9eb-2c10-4e04-8fd4-bac7a06695ce": {
"id": "a2b3b9eb-2c10-4e04-8fd4-bac7a06695ce",
"method": "Entrega Normal",
"methodId": "01",
"isPartialDelivery": true,
"poolDeadline": 10,
"price": 5.22,
"time": 7,
"deliveryEstimatedDate": "2024-11-11",
"deliveryEstimate": {
"days": 7,
"hours": 3,
"minutes": 4,
"dateTime": "2024-11-11 14:16"
},
"fulfillments": {
"F1": {
"id": "F1",
"locationId": "locationId-003",
"locationType": "Own Store",
"type": "SHIPMENT",
"freightCosts": {
"handlingPrice": 3,
"totalPrice": 5.22,
"rulePrice": null,
"handlingTime": 3,
"handlingHours": 3,
"handlingMinutes": 3,
"extraDeadlineTime": 1,
"recessDays": 0,
"totalTime": 7,
"ruleTime": null,
"totalUtilDays": 5,
"deliveryEstimatedDate": "2024-11-11",
"deliveryEstimate": {
"days": 7,
"hours": 3,
"minutes": 4,
"dateTime": "2024-11-11 14:16"
},
"transferPrice": 0,
"transferTime": 0,
"stockArrivalTime": 0,
"waitingTransferTime": 0
},
"shipment": {
"shippingPrice": 2.2222222222222223,
"shippingTime": 1,
"carrierId": "100",
"carrierName": "Razão social 100",
"contractId": "101",
"methodId": "01",
"method": "Entrega Normal",
"recessDays": 2,
"details": {
"minWeight": 0,
"maxWeight": 10,
"overweightFactor": 1,
"dimensionalFactor": 1,
"grisType": "",
"grisValue": 1,
"grisMinValue": 0,
"adValorenType": "",
"adValorenValue": 1,
"adValorenMinValue": 0,
"otherCharges": 1,
"icmsCost": 0.022222222222222143,
"provider": {
"id": "OMS",
"type": "INTERNAL"
}
}
},
"appliedRules": {},
"items": {
"skuId-003": {
"sku": "skuId-003",
"lotId": null,
"quantity": 1,
"deliveryDate": null,
"daysToDelivery": 0,
"salesStartsAt": null,
"salesEndsAt": null,
"billingStartsAt": null,
"groupIds": [
11,
12,
13,
14,
56
],
"categoryIds": [
"categoryId-002",
"categoryId-003",
"categoryId-004"
],
"availableQuantity": 99999999
}
},
"stockTypes": {
"skuId-003": {
"PHYSICAL": 1
}
}
}
},
"utilDays": 5,
"beforeRules": {}
},
"fae8fed7-5ddb-442f-b295-0765ab8bfb9e": {
"id": "fae8fed7-5ddb-442f-b295-0765ab8bfb9e",
"method": "Entrega Expressa",
"methodId": "02",
"isPartialDelivery": true,
"poolDeadline": 1,
"price": 6.83,
"time": 8,
"deliveryEstimatedDate": "2024-11-12",
"deliveryEstimate": {
"days": 8,
"hours": 5,
"minutes": 5,
"dateTime": "2024-11-12 16:17"
},
"fulfillments": {
"F1": {
"id": "F1",
"locationId": "locationId-004",
"locationType": "Seller",
"type": "SHIPMENT",
"freightCosts": {
"handlingPrice": 4,
"totalPrice": 6.83,
"rulePrice": null,
"handlingTime": 4,
"handlingHours": 4,
"handlingMinutes": 4,
"extraDeadlineTime": 1,
"recessDays": 2,
"totalTime": 8,
"ruleTime": null,
"totalUtilDays": 6,
"deliveryEstimatedDate": "2024-11-12",
"deliveryEstimate": {
"days": 8,
"hours": 5,
"minutes": 5,
"dateTime": "2024-11-12 16:17"
},
"transferPrice": 0,
"transferTime": 0,
"stockArrivalTime": 0,
"waitingTransferTime": 0
},
"shipment": {
"shippingPrice": 2.8282828282828283,
"shippingTime": 1,
"carrierId": "100",
"carrierName": "Razão social 100",
"contractId": "102",
"methodId": "02",
"method": "Entrega Expressa",
"recessDays": 0,
"details": {
"minWeight": 0,
"maxWeight": 10,
"overweightFactor": 1,
"dimensionalFactor": 2,
"grisType": "",
"grisValue": 1,
"grisMinValue": 0,
"adValorenType": "",
"adValorenValue": 1,
"adValorenMinValue": 0,
"otherCharges": 1,
"icmsCost": 0.028282828282828465,
"provider": {
"id": "OMS",
"type": "INTERNAL"
}
}
},
"appliedRules": {},
"items": {
"skuId-004": {
"sku": "skuId-004",
"lotId": null,
"quantity": 2,
"deliveryDate": null,
"daysToDelivery": 0,
"salesStartsAt": null,
"salesEndsAt": null,
"billingStartsAt": null,
"groupIds": [
11,
12,
56,
92,
150
],
"categoryIds": [
"categoryId-002",
"categoryId-003"
],
"availableQuantity": 996
}
},
"stockTypes": {
"skuId-004": {
"PHYSICAL": 2
}
}
}
},
"utilDays": 6,
"beforeRules": {}
}
},
"shipmentExceptions": [
{
"message": "[602] Method is not active.",
"methodId": "methodId-001",
"methodName": "Normal - methodId-001"
},
{
"message": "[602] Method is not active.",
"methodId": "methodId-002",
"methodName": "Expressa - methodId-002"
}
],
5. Requisitos Técnicos
Endpoints e APIs Envolvidas:
Rota principal de cotação, ativada feature via configuração. - /v1/clients/{clientId}/channels/{channelId}/freights
Métodos de Resposta: POST
Atenção: A cotação parcial não funcionará na rota por geolocalização: /v1/clients/{clientId}/channels/{channelId}/freights/distance
6. Casos de Uso
- Exemplo 1 Shipment: Cliente solicita uma cotação de 2 Skus diferentes, onde o skuId-003 só possui estoque em uma filial, e o skuId-004 em outra. A cotação trará o retorno parcial em modalidades diferentes, indicando no response o campo "isPartialDelivery": true. - Exemplo do response acima.
- Exemplo 2 Pickup: Cliente solicita uma cotação de 2 skus diferentes onde o skuId-003 só possui estoque em uma filial, e o skuId-004 em outra. A cotação trará o retorno parcial em locations diferentes, indica indicando no response o campo "isPartialDelivery": true. Na estrutura de exceptions retornará as filiais, e qual os seus respectivos estoques, o total requisitado: "totalRequested" e o total disponivel: "totalAvailable”. - Exemplo do response acima.
7. Ativação e Consultoria
Os retornos no response das cotações de frete passarão a incluir novos campos e/ou estruturas com isso é necessário desenvolvimento para adequação e uso da cotação parcial com seu e-commerce, podendo ser conduzido pelo time de Ativação Linx, via consultoria.
Nosso time avaliará seu ambiente atual e as integrações existentes com a API de frete para identificar possíveis impactos e ajustes necessários.
Para seguir com o processo, procure seu executivo de venda.