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.

PUT /api/v1/orders/:orderNumber/shippings/:shippingCode/status/shipped
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.

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.

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:

{
  "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://ingress-hmg-gcp-a.netshoes.io/api/v1/orders/600367264/shippings/1960863295"
        },
        {
          "rel": "order",
          "href": "https://ingress-hmg-gcp-a.netshoes.io/api/v1/orders/600367264"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "https://ingress-hmg-gcp-a.netshoes.io/api/v1/orders/600367264"
    },
    {
      "rel": "shippings",
      "href": "https://ingress-hmg-gcp-a.netshoes.io/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:

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:

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:

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://ingress-hmg-gcp-a.netshoes.io/v2/products"
        },
        "price": {
          "href": "https://ingress-hmg-gcp-a.netshoes.io/v2/products/1124/prices"
        },
        "stock": {
          "href": "https://ingress-hmg-gcp-a.netshoes.io/v2/products/1124/stocks"
        }
      }
    }
  ],
  "page": 0,
  "totalPages": 543,
  "size": 1,
  "total": 543,
  "_links": {
    "self": {
      "href": "https://ingress-hmg-gcp-a.netshoes.io/v2/products?page=0&size=1"
    },
    "first": {
      "href": "https://ingress-hmg-gcp-a.netshoes.io/v2/products?page=0&size=1"
    },
    "next": {
      "href": "https://ingress-hmg-gcp-a.netshoes.io/v2/products?page=1&size=1"
    },
    "last": {
      "href": "https://ingress-hmg-gcp-a.netshoes.io/v2/products?page=542&size=1"
    }
  }
}

Busca de produto:

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://ingress-hmg-gcp-a.netshoes.io/v2/products/1124"
    },
    "price": {
      "href": "https://ingress-hmg-gcp-a.netshoes.io/v2/products/1124/1124/prices"
    },
    "stock": {
      "href": "https://ingress-hmg-gcp-a.netshoes.io/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)
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.
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.