Fulfillment
Integração de pedidos Fulfillment
A Netshoes integra pedidos de sellers no serviço de fulfillment, onde todo o processo de armazenamento, faturamento e despacho dos produtos é realizado pelo Magalu Entregas. Em virtude dessa integração, algumas rotas de integração não poderão ser utilizadas devido ao caráter automatizado do serviço.
Adicionalmente, é disponibilizado um endpoint para que os sellers sinalizem os produtos que desejam comercializar por meio do serviço de fulfillment.
Diferenças no processo de pedido Fulfillment:
Os seguintes endpoints retornarão erros caso o pedido esteja na modalidade fulfillment:
PUT /api/v1/orders/:orderNumber/shippings/:shippingCode/status/invoiced
Status HTTP: 400 Bad Request
Mensagem: Order invoiced through Fulfillment service of Magalu Entregas.
Status HTTP: 400 Bad Request
Mensagem: Order invoiced through Fulfillment service of Magalu Entregas.
PUT /api/v1/orders/:orderNumber/shippings/:shippingCode/status/shipped
Status HTTP: 400 Bad Request
Mensagem: Order shipped through Fulfillment service of Magalu Entregas.
Status HTTP: 400 Bad Request
Mensagem: Order shipped through Fulfillment service of Magalu Entregas.
PUT /api/v1/orders/:orderNumber/shippings/:shippingCode/status/delivered
Status HTTP: 400 Bad Request
Mensagem: Order delivered through Fulfillment service of Magalu Entregas.
Status HTTP: 400 Bad Request
Mensagem: Order delivered through Fulfillment service of Magalu Entregas.
PUT /api/v1/orders/:orderNumber/shippings/:shippingCode/status/canceled
Status HTTP: 400 Bad Request
Mensagem: It is not possible for the seller to cancel orders from Magalu Entregas fulfillment stock.
Status HTTP: 400 Bad Request
Mensagem: It is not possible for the seller to cancel orders from Magalu Entregas fulfillment stock.
Como o processo, desde o faturamento do pedido até a entrega ao cliente, será realizado pelo serviço de fulfillment da Magalu, os status dos pedidos serão modificados automaticamente pelo sistema.
Os pedidos da modalidade fulfillment poderão ser identificados por quaisquer um dos critérios abaixo:
| Tela | Campo API | Valor Api |
|---|---|---|
| Código Transportadora | shippings.transport.carrierId | 906 |
| Transportadora | shippings.transport.carrier | Magalu Entregas - Fulfillment |
Exemplo:
json
{
"expands": [
"shippings",
"items",
"devolutionItems"
],
"agreedDate": 1675652400000,
"paymentDate": 1675194498000,
"paymentGatewayInfos": [
{
"totalValue": 320.04,
"paymentGatewayRegistrationNumber": "17948578000177"
}
],
"orderDate": 1675194212000,
"orderNumber": "600367264",
"totalQuantity": 2,
"originSite": "NETSHOES",
"orderStatus": "Invoiced",
"orderType": "Sale",
"totalGross": 320.04,
"totalCommission": 0,
"totalDiscount": 0,
"totalFreight": 26.04,
"totalNet": 294,
"shippings": [
{
"expands": [
"items",
"devolutionItems"
],
"shippingCode": 1960863295,
"status": "Invoiced",
"shippingEstimate": 1675738800000,
"deliveryTime": 5,
"freightAmount": 26.04,
"country": "BR",
"transport": {
"expands": [],
"trackingNumber": "",
"trackingLink": "",
"deliveryService": "Normal",
"deliveryId": "52",
"carrier": "Magalu Entregas - Fulfillment", // Nome da transportadora
"carrierId": "906", // Código da transportadora
"links": []
},
"invoice": {
"expands": [],
"accessKey": "35230185302486000175550018120613951162574778",
"date": 1675220399000,
"shipDate": 1675194695000,
"volume": 1,
"errors": [],
"validationErrors": [],
"links": []
},
"customer": {
"expands": [],
"document": "07364746927",
"stateInscription": "",
"customerName": "Maria da Silva",
"recipientName": "João da Silva",
"tradeName": "",
"cellPhone": "",
"landLine": "(47)999999999",
"address": {
"expands": [],
"neighborhood": "Centro",
"postalCode": "89120000",
"city": "TIMBO",
"complement": "1",
"state": "SC",
"stateName": "SANTA CATARINA",
"street": "Outros Pedido",
"number": "1",
"links": []
},
"links": []
},
"sender": {
"expands": [],
"supplierCnpj": "08330104000176",
"sellerCode": 12904,
"sellerName": "Loja de tênis LTDA",
"supplierName": "Loja de tênis LTDA",
"links": []
},
"platformId": "MAGALU_ENTREGAS",
"serviceId": "52",
"serviceName": "Normal",
"links": [
{
"rel": "self",
"href": "https://api-sandbox.netshoes.com.br/api/v1/orders/600367264/shippings/1960863295"
},
{
"rel": "order",
"href": "https://api-sandbox.netshoes.com.br/api/v1/orders/600367264"
}
]
}
],
"links": [
{
"rel": "self",
"href": "https://api-sandbox.netshoes.com.br/api/v1/orders/600367264"
},
{
"rel": "shippings",
"href": "https://api-sandbox.netshoes.com.br/api/v1/orders/600367264/shippings"
}
]
}json
{
"expands": [
"shippings",
"items",
"devolutionItems"
],
"agreedDate": 1675652400000,
"paymentDate": 1675194498000,
"paymentGatewayInfos": [
{
"totalValue": 320.04,
"paymentGatewayRegistrationNumber": "17948578000177"
}
],
"orderDate": 1675194212000,
"orderNumber": "600367264",
"totalQuantity": 2,
"originSite": "NETSHOES",
"orderStatus": "Invoiced",
"orderType": "Sale",
"totalGross": 320.04,
"totalCommission": 0,
"totalDiscount": 0,
"totalFreight": 26.04,
"totalNet": 294,
"shippings": [
{
"expands": [
"items",
"devolutionItems"
],
"shippingCode": 1960863295,
"status": "Invoiced",
"shippingEstimate": 1675738800000,
"deliveryTime": 5,
"freightAmount": 26.04,
"country": "BR",
"transport": {
"expands": [],
"trackingNumber": "",
"trackingLink": "",
"deliveryService": "Normal",
"deliveryId": "52",
"carrier": "Magalu Entregas - Fulfillment", // Nome da transportadora
"carrierId": "906", // Código da transportadora
"links": []
},
"invoice": {
"expands": [],
"accessKey": "35230185302486000175550018120613951162574778",
"date": 1675220399000,
"shipDate": 1675194695000,
"volume": 1,
"errors": [],
"validationErrors": [],
"links": []
},
"customer": {
"expands": [],
"document": "07364746927",
"stateInscription": "",
"customerName": "Maria da Silva",
"recipientName": "João da Silva",
"tradeName": "",
"cellPhone": "",
"landLine": "(47)999999999",
"address": {
"expands": [],
"neighborhood": "Centro",
"postalCode": "89120000",
"city": "TIMBO",
"complement": "1",
"state": "SC",
"stateName": "SANTA CATARINA",
"street": "Outros Pedido",
"number": "1",
"links": []
},
"links": []
},
"sender": {
"expands": [],
"supplierCnpj": "08330104000176",
"sellerCode": 12904,
"sellerName": "Loja de tênis LTDA",
"supplierName": "Loja de tênis LTDA",
"links": []
},
"platformId": "MAGALU_ENTREGAS",
"serviceId": "52",
"serviceName": "Normal",
"links": [
{
"rel": "self",
"href": "https://api-sandbox.netshoes.com.br/api/v1/orders/600367264/shippings/1960863295"
},
{
"rel": "order",
"href": "https://api-sandbox.netshoes.com.br/api/v1/orders/600367264"
}
]
}
],
"links": [
{
"rel": "self",
"href": "https://api-sandbox.netshoes.com.br/api/v1/orders/600367264"
},
{
"rel": "shippings",
"href": "https://api-sandbox.netshoes.com.br/api/v1/orders/600367264/shippings"
}
]
}Sinalização de produtos candidatos ao serviço Fulfillment
Incluímos nos endpoints de criação e atualização de produtos um novo campo para que o seller indique produtos para o serviço de fulfillment:
Headers:
- client_id: APP usado para autenticar.
- access_token: Access Token usado para autenticar.
Request Body:
- fulfillment.candidate: Habilita ou desabilita a candidatura do produto para o serviço fulfillment
Criação de produtos:
http
POST /api/v2/products/
Headers:
client_id: "APP Token usado para autenticar"
access_token: "Access Token usado para autenticar"
{
"sku": "tenisGelMasculino0001",
"productGroup": "tenisGelMasculino",
"department": "Running",
"productType": "Tênis",
"brand": "Marca",
"name": "Tênis Gel Masculino",
"description": "Descubra o máximo em conforto e desempenho com o nosso Tênis de Gel, projetado para proporcionar uma experiência única aos seus pés. Este tênis combina tecnologia avançada com um design moderno, oferecendo suporte e amortecimento superiores para todas as suas atividades diárias e esportivas.",
"color": "Azul",
"gender": "Unissex",
"manufacturerCode": "32874283829",
"size": "42",
"eanIsbn": "8949461894984",
"height": 130,
"width": 37,
"depth": 28,
"weight": "117",
"fulfillment": { // Novo campo
"candidate": true
},
"images": [
{
"url": "https://static.netshoes.com.br/produtos/tenis-asics-gel-sparta-2-masculino/00/2FW-0899-300/2FW-0899-300_zoom1.jpg?ts=1711562367"
}
],
"attributes": [
{
"name": "Público Alvo",
"values": [
"Adulto"
]
}
]
}
http
POST /api/v2/products/
Headers:
client_id: "APP Token usado para autenticar"
access_token: "Access Token usado para autenticar"
{
"sku": "tenisGelMasculino0001",
"productGroup": "tenisGelMasculino",
"department": "Running",
"productType": "Tênis",
"brand": "Marca",
"name": "Tênis Gel Masculino",
"description": "Descubra o máximo em conforto e desempenho com o nosso Tênis de Gel, projetado para proporcionar uma experiência única aos seus pés. Este tênis combina tecnologia avançada com um design moderno, oferecendo suporte e amortecimento superiores para todas as suas atividades diárias e esportivas.",
"color": "Azul",
"gender": "Unissex",
"manufacturerCode": "32874283829",
"size": "42",
"eanIsbn": "8949461894984",
"height": 130,
"width": 37,
"depth": 28,
"weight": "117",
"fulfillment": { // Novo campo
"candidate": true
},
"images": [
{
"url": "https://static.netshoes.com.br/produtos/tenis-asics-gel-sparta-2-masculino/00/2FW-0899-300/2FW-0899-300_zoom1.jpg?ts=1711562367"
}
],
"attributes": [
{
"name": "Público Alvo",
"values": [
"Adulto"
]
}
]
}
Atualização de produtos:
http
PUT /api/v2/products/tenisGelMasculino0001/
Headers:
client_id: "APP Token usado para autenticar"
access_token: "Access Token usado para autenticar"
{
"sku": "tenisGelMasculino0001",
"productGroup": "tenisGelMasculino",
"department": "Running",
"productType": "Tênis",
"brand": "Marca",
"name": "Tênis Gel Masculino",
"description": "Descubra o máximo em conforto e desempenho com o nosso Tênis de Gel, projetado para proporcionar uma experiência única aos seus pés. Este tênis combina tecnologia avançada com um design moderno, oferecendo suporte e amortecimento superiores para todas as suas atividades diárias e esportivas.",
"color": "Azul",
"gender": "Unissex",
"manufacturerCode": "32874283829",
"size": "42",
"eanIsbn": "8949461894984",
"height": 130,
"width": 37,
"depth": 28,
"weight": "117",
"fulfillment": { // Novo campo
"candidate": true
},
"images": [
{
"url": "https://static.netshoes.com.br/produtos/tenis-asics-gel-sparta-2-masculino/00/2FW-0899-300/2FW-0899-300_zoom1.jpg?ts=1711562367"
}
],
"attributes": [
{
"name": "Público Alvo",
"values": [
"Adulto"
]
}
]
}
http
PUT /api/v2/products/tenisGelMasculino0001/
Headers:
client_id: "APP Token usado para autenticar"
access_token: "Access Token usado para autenticar"
{
"sku": "tenisGelMasculino0001",
"productGroup": "tenisGelMasculino",
"department": "Running",
"productType": "Tênis",
"brand": "Marca",
"name": "Tênis Gel Masculino",
"description": "Descubra o máximo em conforto e desempenho com o nosso Tênis de Gel, projetado para proporcionar uma experiência única aos seus pés. Este tênis combina tecnologia avançada com um design moderno, oferecendo suporte e amortecimento superiores para todas as suas atividades diárias e esportivas.",
"color": "Azul",
"gender": "Unissex",
"manufacturerCode": "32874283829",
"size": "42",
"eanIsbn": "8949461894984",
"height": 130,
"width": 37,
"depth": 28,
"weight": "117",
"fulfillment": { // Novo campo
"candidate": true
},
"images": [
{
"url": "https://static.netshoes.com.br/produtos/tenis-asics-gel-sparta-2-masculino/00/2FW-0899-300/2FW-0899-300_zoom1.jpg?ts=1711562367"
}
],
"attributes": [
{
"name": "Público Alvo",
"values": [
"Adulto"
]
}
]
}
Retornos HTTP:
| Status HTTP | Descrição do Status HTTP | Descrição |
|---|---|---|
| 202 | Accepted | Os produtos serão solicitados como candidatos a participar do fulfillment. |
| 400 | Bad Request | Payload de entrada não conforme. |
| 401 | Unauthorized | Credenciais de autenticação fornecidas são inválidas. |
| 403 | Forbidden | O usuário não possui permissão para modificar/consultar a API solicitada. |
| 404 | Not Found | Nenhum produto encontrado com os parâmetros passados. |
| 500 | Internal Server Error | Erro de disponibilidade do serviço. |
O campo fulfillment tem como objetivo sinalizar que um produto é elegível para participar do serviço de fulfillment. O produto passará por uma avaliação para ser aprovado para comercialização utilizando o fulfillment, com o estoque sendo enviado para os centros de distribuição da Magalu.
Consulta de produtos que foram candidatados para o fulfillment
É disponibilizado um campo chamado fulfillment na busca de produtos para informar se o produto já foi sugerido pelo seller como candidato a participar do serviço de fulfillment:
Headers:
- client_id: APP Token usado para autenticar.
- access_token: Access Token usado para autenticar.
Novos campos:
- fulfillment.candidate: Indica a candidatura do produto para o serviço de fulfillment pelo seller
Busca de lista de produtos:
http
GET /api/v2/products
Headers:
client_id: "APP Token usado para autenticar"
access_token: "Access Token usado para autenticar"
{
"items": [
{
"expands": [
"images",
"attributes",
"status"
],
"sku": "1124",
"productGroup": "1124",
"department": "Beleza",
"productType": "Antisséptico Bucal",
"brand": "Nike",
"name": "Teste preço máximo menor que o limite API",
"description": "12",
"color": "Amarelo",
"gender": "Mulher",
"size": "0/6M",
"height": 1,
"width": 1,
"depth": 1,
"weight": 1,
"fulfillment": { // Novo campo
"candidate": true
},
"_links": {
"self": {
"href": "https://api-sandbox.netshoes.com.br/v2/products"
},
"price": {
"href": "https://api-sandbox.netshoes.com.br/v2/products/1124/prices"
},
"stock": {
"href": "https://api-sandbox.netshoes.com.br/v2/products/1124/stocks"
}
}
}
],
"page": 0,
"totalPages": 543,
"size": 1,
"total": 543,
"_links": {
"self": {
"href": "https://api-sandbox.netshoes.com.br/v2/products?page=0&size=1"
},
"first": {
"href": "https://api-sandbox.netshoes.com.br/v2/products?page=0&size=1"
},
"next": {
"href": "https://api-sandbox.netshoes.com.br/v2/products?page=1&size=1"
},
"last": {
"href": "https://api-sandbox.netshoes.com.br/v2/products?page=542&size=1"
}
}
}
http
GET /api/v2/products
Headers:
client_id: "APP Token usado para autenticar"
access_token: "Access Token usado para autenticar"
{
"items": [
{
"expands": [
"images",
"attributes",
"status"
],
"sku": "1124",
"productGroup": "1124",
"department": "Beleza",
"productType": "Antisséptico Bucal",
"brand": "Nike",
"name": "Teste preço máximo menor que o limite API",
"description": "12",
"color": "Amarelo",
"gender": "Mulher",
"size": "0/6M",
"height": 1,
"width": 1,
"depth": 1,
"weight": 1,
"fulfillment": { // Novo campo
"candidate": true
},
"_links": {
"self": {
"href": "https://api-sandbox.netshoes.com.br/v2/products"
},
"price": {
"href": "https://api-sandbox.netshoes.com.br/v2/products/1124/prices"
},
"stock": {
"href": "https://api-sandbox.netshoes.com.br/v2/products/1124/stocks"
}
}
}
],
"page": 0,
"totalPages": 543,
"size": 1,
"total": 543,
"_links": {
"self": {
"href": "https://api-sandbox.netshoes.com.br/v2/products?page=0&size=1"
},
"first": {
"href": "https://api-sandbox.netshoes.com.br/v2/products?page=0&size=1"
},
"next": {
"href": "https://api-sandbox.netshoes.com.br/v2/products?page=1&size=1"
},
"last": {
"href": "https://api-sandbox.netshoes.com.br/v2/products?page=542&size=1"
}
}
}
Busca de produto:
http
GET /api/v2/products/:sku
Headers:
client_id: "APP usado para autenticar"
access_token: "Access Token usado para autenticar"
{
"expands": [
"images",
"attributes",
"status"
],
"sku": "1124",
"productGroup": "1124",
"department": "Beleza",
"productType": "Antisséptico Bucal",
"brand": "Nike",
"name": "Teste preço máximo menor que o limite API",
"description": "12",
"color": "Amarelo",
"gender": "Mulher",
"size": "0/6M",
"height": 1,
"width": 1,
"depth": 1,
"weight": 1,
"fulfillment": { // Novo campo
"candidate": true
},
"_links": {
"self": {
"href": "https://api-sandbox.netshoes.com.br/v2/products/1124"
},
"price": {
"href": "https://api-sandbox.netshoes.com.br/v2/products/1124/1124/prices"
},
"stock": {
"href": "https://api-sandbox.netshoes.com.br/v2/products/1124/1124/stocks"
}
}
}
http
GET /api/v2/products/:sku
Headers:
client_id: "APP usado para autenticar"
access_token: "Access Token usado para autenticar"
{
"expands": [
"images",
"attributes",
"status"
],
"sku": "1124",
"productGroup": "1124",
"department": "Beleza",
"productType": "Antisséptico Bucal",
"brand": "Nike",
"name": "Teste preço máximo menor que o limite API",
"description": "12",
"color": "Amarelo",
"gender": "Mulher",
"size": "0/6M",
"height": 1,
"width": 1,
"depth": 1,
"weight": 1,
"fulfillment": { // Novo campo
"candidate": true
},
"_links": {
"self": {
"href": "https://api-sandbox.netshoes.com.br/v2/products/1124"
},
"price": {
"href": "https://api-sandbox.netshoes.com.br/v2/products/1124/1124/prices"
},
"stock": {
"href": "https://api-sandbox.netshoes.com.br/v2/products/1124/1124/stocks"
}
}
}
Retornos HTTP:
| Status HTTP | Descrição do Status HTTP | Descrição |
|---|---|---|
| 200 | OK | Produto buscado com sucesso. |
| 401 | Unauthorized | Credenciais de autenticação fornecidas são inválidas. |
| 403 | Forbidden | O usuário não possui permissão para modificar/consultar a API solicitada. |
| 404 | Not Found | Nenhum produto encontrado com os parâmetros passados. |
| 500 | Internal Server Error | Erro de disponibilidade do serviço. |
Download de notas fiscais de pedidos da modalidade Fulfillment
Para que o seller possua a possibilidade de realizar o download de notas fiscais, será disponibilizado um endpoint para a obtenção das notas fiscais dos pedidos na modalidade fulfillment.
O download das notas fiscais poderá ser realizado de duas maneiras:
- Por período (limitado a 30 dias)
- Por pedido
Download de notas fiscais por período
A utilização serviço de download de notas fiscais por período terá as seguintes características:
Headers:
- client_id: APP Token usado para autenticar.
- access_token: Access Token usado para autenticar.
Parâmetros:
- from: Data de início do período de download das notas fiscais.
(Formato ISO 8601: yyyy-MM-dd'T'HH:mm:ss, Exemplo: 2024-09-30T12:30:00) - until: Data do fim do período de download das notas fiscais.
(Formato ISO 8601: yyyy-MM-dd'T'HH:mm:ss, Exemplo: 2024-09-30T12:30:00)
http
GET /api/v1/orders/fulfillment/invoices/download?from={dataInicioDoPeriodo}&until={dataFimDoPeriodo}
Headers:
client_id: "APP Token usado para autenticar"
access_token: "Access Token usado para autenticar"
http
GET /api/v1/orders/fulfillment/invoices/download?from={dataInicioDoPeriodo}&until={dataFimDoPeriodo}
Headers:
client_id: "APP Token usado para autenticar"
access_token: "Access Token usado para autenticar"
Retorno:
Arquivo compactado (zip) com as notas fiscais do período.
Retornos HTTP:
| Status HTTP | Descrição do Status HTTP | Descrição |
|---|---|---|
| 200 | OK | Download da nota fiscal realizada com sucesso. |
| 204 | No Content | Nenhuma nota fiscal encontrada com os parâmetros passados. |
| 400 | Bad Request | Parâmetros de entrada não conforme. |
| 401 | Unauthorized | Credenciais de autenticação fornecidas são inválidas. |
| 500 | Internal Server Error | Erro de disponibilidade do serviço. |
Download de notas fiscais por pedido
A utilização serviço de download de notas fiscais por pedido terá as seguintes características:
Headers:
- client_id: APP Token usado para autenticar.
- access_token: Access Token usado para autenticar.
Parâmetros:
- codigoDoPedido: Código do pedido para o download da nota fiscal.
http
GET /api/v1/orders/{codigoDoPedido}/fulfillment/invoices/download
Headers:
client_id: "APP Token usado para autenticar"
access_token: "Access Token usado para autenticar"
http
GET /api/v1/orders/{codigoDoPedido}/fulfillment/invoices/download
Headers:
client_id: "APP Token usado para autenticar"
access_token: "Access Token usado para autenticar"
Retorno:
Arquivo compactado (zip) com a nota fiscal do pedido.
Retornos HTTP:
| Status HTTP | Descrição do Status HTTP | Descrição |
|---|---|---|
| 200 | OK | Download da nota fiscal realizada com sucesso. |
| 204 | No Content | Nenhuma nota fiscal encontrada com os parâmetros passados. |
| 400 | Bad Request | Parâmetros de entrada não conforme. |
| 401 | Unauthorized | Credenciais de autenticação fornecidas são inválidas. |
| 404 | Not Found | Pedido não encontrado. |
| 500 | Internal Server Error | Erro de disponibilidade do serviço. |