Regras e Uso em Produção

Para mantermos um ambiente saudável e totalmente disponível para plataformas e lojistas, é necessário seguir boas práticas de execução no ambiente de produção.

Processo para disponibilização

Para disponibilizar os produtos no Marketplace do Grupo Netshoes é necessário seguir alguns fluxos:

Obtenção do Token de Produção

Para obter a chave de acesso ao ambiente de produção, é necessário passar pela validação técnica das chamadas realizadas em Sandbox afim de garantir que a aplicação seguirá todos os processos necessários.

Boas práticas em Produção

01 - Configuração de Notificação

Com esta configuração, é possível evitar realização de diversas chamadas à API sem que o produto tenha sofrido alguma alteração de status.

Será nesta configuração que será enviado o informativo de qualquer ação de alteração por parte do time de catalogo.

A notificação também disponibiliza a opção de recebimento de informações para pedidos, onde também toda alteração de status é feito o disparo da informação.

Mais informações e modo de configuração na página 'Notificação'.

02 - Conceito de Família

Para considerar uma família completa, é necessário encaminhar, pelo menos o mínimo, de variações de um produto. Mesmo que o produto não possua estoque disponível, as numerações/tamanhos devem ser encaminhadas e serão cadastradas juntas.

Caso o produto seja único, é possível encaminhar apenas um, porém, a informação deve estar presente na descrição, com as medidas que aquele produto serve.

Por exemplo: Blusa Estampada - Único - Veste do 38 ao 44.

Quantidade de produtos para conceito de família:

- Roupas: minimo 3 produtos sequenciais (Exemplo: P, M e G).

- Calçados: minimo 4 produtos sequenciais (Exemplos: 33, 34, 35 e 36).

- Acessórios, por exemplo, possuem outras regras e o lojista deverá validar com a Netshoes qual será a quantidade necessária para auditoria do produto.

03 - Consulta de informações pré-cadastradas pela Netshoes

Na API encontra-se disponível endpoints que possuam informações que já foram cadastradas na Netshoes e que deverão ser utilizadas pelos lojistas e será com base nestas informações disponíveis que os produtos deverão ser cadastrados.

Estes endpoints são para Brands, Colors, Departaments, ProductType, entre outros, dos quais estão disponíveis seus respectivos endpoints dentro da nossa página de API Browser.

Caso uma informação necessária não esteja disponível em seus respectivos endpoints, o lojista deverá solicitar ao seu analista comercial o cadastramento do mesmo internamente para que seja refletido na API.

Esta regra deverá ser seguida obrigatoriamente, afim de evitar que o produto fique criticado e não siga para auditoria.

04 - Processo de atualização de status de pedido

É necessário respeitar as regras de fluxo e informações para atualização de status de pedidos, sendo alguns dos itens:

• PUT /invoiced

O campo 'issueDate' precisa conter, obrigatoriamente, a data de emissão da Nota Fiscal.

• PUT /shipped

O link de rastreamento sempre se torna obrigatório de preenchimento para todas as formas de entregas, com exceção de 'correios'.

Atentar-se também que, por exemplo se a forma de entrega for de fato correios, haverá o "comparativo" desta informação com base no trackingNumber (código de rastreio).

O correios utiliza um padrão de informação. Então supondo que passem um trackingNumber pertencente à uma transportadora mas for indicado no carrier o correios, não obterá sucesso.

Obrigatoriedade dos campos de produto

A tabela abaixo define a ação esperada para cada um dos campos validados pela API v2. Todos os campos abaixo são obrigatórios e exigidos na criação do produto.

Produto

Campo	Validação
Departamento Tipo de Produto	Validação assíncrona de valores pré-definidos O Tipo de produto dependerá da seleção do Departamento Endpoint para consulta: Departamento Netshoes – GET /api/v1/bus/{buId}/departments Tipo de Produto - GET /api/v1/department/{departmentCode}/productType
Nome	Preenchimento com validação de limite de 100 caracteres. Títulos dos produtos devem preferir seguir a padronagem: Público adulto: [Tipo de Produto] + [Marca] + [Modelo] + [Característica] + [Gênero] Quando o público alvo do produto for linha infantil: [Tipo de Produto] + [Marca] + [Modelo] + [Característica] + [Gênero] + [Infantil]
Descrição	Preenchimento com validação de limite de 3.000 caracteres. Não poderá conter formatações, incluindo tags HTML e sequências de escape.
SKU	É a chave do produto para o Lojista e não podem conter espaçamento ou carácter especial. Esse campo nunca é alterado pelo Marketplace
ProductGroup	O código agrupador identifica variações de um mesmo modelo de produto por tamanho e cor. O mesmo deverá ser igual para todos os skus do modelo cadastrado, dessa forma o cliente conseguirá identificar as cores e tamanhos disponíveis do modelo através das caixas disponíveis acima do botão comprar. Esse código é responsável por vincular todos as variações do produto cadastrado a fim de que reflitam todos na mesma página no site.
Marca	Validação assíncrona de valores pré-definidos Endpoint para consulta - GET /api/v1/brands
Altura	Preenchimento em centímetros com validação de formato decimal (limite de 3 casas decimais após o ponto) Exemplo de preenchimento: 0.001
Largura	Preenchimento em centímetros com validação de formato decimal (limite de 3 casas decimais após o ponto) Exemplo de preenchimento: 0.001
Profundidade	Preenchimento em centímetros com validação de formato decimal (limite de 3 casas decimais após o ponto) Exemplo de preenchimento: 0.001
Peso	Validação do peso máximo permitido em quilos (kg), baseado por tipo de produto
Cor ou Sabor	Todos os produtos exceto os alimentícios devem ser atrelados à uma da COR já cadastradas em nosso sistema e deverá levar em consideração as cores predominantes do produto. Exemplo: "Preto+Vermelho" ou "Preto" Já para os produtos alimentícios devem ser ubstituído pelo atributo SABOR e o mesmo deve ser atrelado à uma das opções disponíveis em nosso sistema. Exemplo: "Mamão+Laranja" ou "Laranja“ Endpoint para consulta: Cor – GET /api/v1/colors Sabor - GET /api/v1/flavors
Tamanho	Produtos que não tiverem variações de tamanho (acessórios e equipamentos), o campo deve ser preenchido como “Único” Demais produtos que possuirem esta informação deverá ser atrelado à uma das opções disponíveis em nosso sistema. Endpoint para consulta: GET /api/v1/sizes
Gênero	Validação de valores pré-definidos: Homem, Mulher, Unissex (case sensitive)
Imagem	Validação de urls permitidas: http Formato: .jpeg ou .jpg Dimensão: Max. 1200X1200px e Mín. 400pX400px Tamanho permitido: 5MB Quantidade de imagens: mínimo 1 e máximo 6 Acesso: As imagens devem ser cadastradas como URLs, para isso é necessário que estejam hospedadas em um servidor (exceto Google Drive, Dropbox, etc.)
Atributos	Os Atributos dependerão da seleção do Departamento > Tipo de Produto Os campos estarão indicados como “obrigatórios” ou “opcionais” Se o campo “opcional” for preenchido, passará pela validação dos valores pré-definidos

Preço

Campo	Validação
Product.Price	É preciso ter o preço DE e POR preenchidos, maior que zero

Estoque

Campo	Validação
Product.Stock	Validação de estoque mínimo por família na criação do produto

Informações adicionais

• Preço e Estoque: Importante atentar-se ao novo processo da API V2, onde todo produto cadastrado precisa obrigatoriamente possuir informação de preço e estoque enviado através da chamada de POST.

Quando necessário atualizar tais informações, mesmo que o produto ainda não esteja liberado pelo time de catalogo, basta realizar a chamada de PUT de preço e estoque para que as informações sejam atualizadas e assim que o produto for disponibilizado no Marketplace, subirá com a última informação enviada.

Fluxo de status de produto

Com a atualização de produtos para V2, será possível acompanhar o status do produto ao longo do processo de publicação.

Recebido: O produto já passou pelas validações síncronas, mas ainda passará pelas validações assíncronas.

Criticado: O produto já passou pelas validações assíncronas e possui uma ou mais críticas. No endpoint de status é possível consultar o detalhamento das críticas.

Em catalogação: O produto está em processo de validação interna do marketplace. A partir desta etapa, o produto não pode mais ser alterado.

Aprovado: O produto foi aprovado pela área interna de qualidade do marketplace. Nesta etapa o produto não pode mais ser alterado.

Fluxo de status de pedidos

Relação de possíveis status que um pedido poderá receber, sem considerar um pedido troca, que se encontrá destacado separadamente abaixo.

Cancelamento de Pedidos

Será possível realizar o cancelamento de pedidos via API, atentando-se às seguintes regras:

• Pedidos que ainda não foram faturados, podem ser cancelados.
  Ou seja, o pedido precisa encontrar-se como approved.
• O cancelamento pode gerar multa conforme regras vigentes do cancelamento manual.
  Esta informação não consta disponível na API, sendo um alinhamento/determinação diretamente entre Netshoes-Lojista.

Além da ação de cancelamento liberada, é importante atentar-se que para tal ação é necessário que se enquadre dentre um dos motivos que a Netshoes disponibiliza, do qual deverá ser validado (e informado no JSON de cancelamento) através do endpoint GET/orders/cancellation-reasons.

Pedido Congelado (status Frozen)

Pedidos que possuam este status representam uma validação interna do time de analise de risco na Netshoes, onde o mesmo foi congelado para que não haja o envio do produto ao cliente até a liberação interna ou cancelamento.

Este status poderá entrar em dois cenários: Após a aprovação do pagamento, quando houver esta validação tardia; ou quando na primeira analise já houver a validação e o bloqueio.

Recomendamos que pedidos neste status não sejam enviados ao cliente até que haja a liberação de forma automaticamente que reflita no pedido passando para o status 'approved'.

Se o produto for enviado enquanto o pedido ainda encontrar-se neste status, será necessário o acionamento direto com a Netshoes.

Pedidos que utilizam o NSEntregas

Caso tente realizar essa chamada através da API, retornará HTTPStatus 400 com a seguinte mensagem:
"NS Entregas orders cannot have their status changed to shipped or delivered".

Esta forma de entrega é visível via API através do campo "platformId" que constará com a informação "NETSHOES_ENTREGAS".

Preenchimento do campo 'volume'

Para lojistas que utilizam o NSEntregas, estará disponível o preenchimento do campo 'volume' no momento do faturamento do pedido.
Volume representa a quantidade de pacotes dentro da Nota Fiscal que será despachada ao cliente. Um único volume pode conter um ou mais produtos inteiros (como vários pares de meia) ou partes de um único produto (como as anilhas de uma estação de musculação).

Mensagens e tratamento de erro:

• O campo deve ser enviado somente para pedidos com platformId NETSHOES_ENTREGAS e transportadoras que não sejam Correios (carrierId diferente de 501 e 502);
• Caso o campo não esteja preenchido quando a informação for necessária, será inserido o valor "1" e retornar sucesso na chamada via API;
• Caso o campo esteja preenchido e o pedido não seja elegível, a API retornará o erro "Volume field is only required for NS Entregas orders (except Correios). Please, remove this information."
• Se um número negativo for enviado neste campo, a mensagem de erro corresponderá à "Volume number should be a positive number".

Processo de troca de pedido

Quando houver uma solicitação de troca de produto, será criado um pedido novo do tipo Troca. Este número de pedido será igual ao número do pedido original acrescentando ao final a letra T.

Por exemplo, supondo que o pedido original tenha o OrderNumber 123456, o pedido de troca será 123456T. Com isso, o pedido original 123456 permanecerá disponível para consulta e ele constará com as mesmas informações iniciais de entrega e a troca passará a ser tratada através do pedido 123456T.

Exemplo em Produção de pedido de troca:

Pedido original:

A diferenciação de ambos os pedidos se darão no campo 'orderType', onde quando for uma compra normal, a informação constará como 'Sale' e quando for uma troca, constará como 'Exchange'.

Quando for a troca, também haverá o acréscimo da letra T no final do número do pedido e o número do pedido original constará no campo 'originNumber'.

Inicialmente, o pedido de troca constará com o status ‘Waiting Checkin’, até que o lojista informe à Netshoes, via Portal do Lojista, o recebimento do produto solicitado para troca.

Assim que houver esta confirmação, o pedido de troca passará a ficar com o status ‘approved’ e estará apto a receber alterações de status via API para invoiced > shipped > delivered.

Processo de Reserva de Estoque

A Netshoes realiza o controle do estoque sistemicamente, controlando a disponibilidade e o reservado, com base no estoque do lojista. Todo pedido gerado devido a uma compra no site, automaticamente realizará a reserva do estoque do produto adquirido. Neste cenário, poderá haver duas ações internas:

• Pedido faturado - Quando é realizado o faturamento, o produto reservado é subtraído da Netshoes;
• Pedido cancelado - Supondo, por exemplo, que o pedido seja cancelado por falta de pagamento, o produto reservado voltará a disponibilidade para venda.

A visão do lojista/integradora deverá ser em relação ao estoque físico.

Com base nesta visão, as chamadas de PUT /stocks deverão sempre levar em consideração em quantos produtos o lojista possui de estoque físico e na Netshoes será realizado o controle da disponibilidade para venda e estoque reservado.

De forma ilustrada, pode-se pensar da seguinte forma:

Neste exemplo, temos o seguinte cenário:

• Realizado chamada de PUT /stock informando que o estoque físico do lojista para venda é de 1 produto. Neste cenário, o produto foi disponibilizado no site;
• Houve uma venda, e com isso o produto foi direcionado para o estoque reservado e consequentemente a quantidade de estoque disponível para venda ficou zerado;
• Foi realizado chamada de PUT /stock novamente informando que existe 1 produto no estoque físico, porém não foi para disponibilidade devido a possuir o estoque reservado;
• Em seguida, foi realizado novamente o PUT /stock passando 0 de estoque físico e com isso sistemicamente ele ficará negativo devido a reserva de estoque e consequentemente nenhum produto será disponibilizado para venda.

Importante ressaltar que o estoque reservado não é zerado por nenhuma ação do lojista e/ou integradora, somente mediante ações dos pedidos gerados.

Gateway de Pagamento

Para atender as demandas da Norma Técnica(NT) NF-e/NFC-e 2020.006 v 1.00, imposta pela SEFAZ, a Netshoes está disponibilizando através do GET /orders informações sobre o Gatway de Pagamentos dentro do escopo "paymentGatewayRegistrationNumber", onde poderá conter as seguintes informações expostas:

• CNPJ do MagaluPay (17.948.578/0001-77) - para os pedidos pagos com cartão de crédito.
• CNPJ da Netshoes (09.339.936/0002-05) - para os pedidos pagos com boleto e voucher-Netshoes.