Guia Integrando via API com a Neomode

Owned by Lukas Burda Ferreira
Last updated: Mar 28, 2024
10 min read

Resumo

A Neomode possui uma estrutura de APIS REST para parceiros. Este artigo traz algumas dicas e esclarecimentos de regras de negócio para facilitar a implementação.

Documentação API Oficial

https://neomode.readme.io/reference/

Conectar como ERP ou Canal de Venda?

É possível utilizar as API’s de gerenciamento da Neomode como um ERP ou um Canal de venda. Cada parte tem responsabilidades diferentes e isso reflete na utilização das rotas.

Responsabilidades conectando como um ERP

  1. Cadastrar a árvore de categorias.

  2. Cadastrar os produtos & skus.

  3. Inserir preço nos produtos da loja.

  4. Inserir estoque nos skus da loja.

Ações em Pedidos

  1. Adquirir os novos pedidos.

  2. Aprovar os novos pedidos.

  3. Faturar os pedidos aprovados (inserindo os dados da nota fiscal).

  4. Inserir os dados de transporte ou confirmar retirada dos pedidos faturados.

Responsabilidades conectando como um Canal de Venda

Ações em Pedidos

  1. Criar pedido.

  2. Aprovar pagamento.

  3. Consumir dados de faturamento.

  4. Consumir dados de entrega ou retirada do pedido.

Ações em Catálogo

  1. Consumir árvore de categorias.

  2. Consumir produtos & skus.

  3. Consumir movimentações de estoque.

  4. Consumir movimentações de preço.

Autenticação https://neomode.readme.io/reference/gerar-anonymous-token

A autenticação é feita via Bearer Token, que expira em 1 hora. É preciso gerar um novo a cada expiração.
Os dados necessários: clientId, clientSecret & scope serão disponibilizados pelo time de implantação.

Com sucesso na resposta (200 OK):

{"access_token":"your_token_will_be_here","expires_in":3600,"token_type":"Bearer"}

O valor de "access_token" será usado no Header em todas as requisições, dessa forma:

--header 'Authorization: Bearer put_token_here' \

Estrutura de catálogo

Para entender como replicar um catálogo na Neomode, vamos dividir os elementos principais.

  1. Categorias

  2. Produtos (Agrupador)

  3. Skus (Variações)

  4. Preços

  5. Saldos de estoque.

  6. Loja(s)

1. Árvore de categorias

A Lori possui um sistema de categorias em níveis. É possível ter uma lista de categorias e as categorias dentro desta lista possuírem vinculo com outros níveis de categorias, veja:

A categoria de nível superior é atrelada a categoria de nível inferior através de um campo identificador parentId dentro dela mesma.

  • A identificação de uma categoria PAI é a falta do parentId.

  • A identificação de uma SUBcategoria é a presença do parentId.

    • Esta mesma SUBcategoria pode ser PAI de outra categoria através do parentId.

 

{ "id": "00000000-0000-0000-0000-000000000000" <- Este é o campo identificador para os próximos níveis. "code": "11", "name": "Alimentos", "isActive": true, "children": [ { "parentId": "00000000-0000-0000-0000-000000000000" "id": "11111111-1111-1111-1111-111111111111" "code": "21", "name": "Frutas", "isActive": true, "children": [ { "parentId": "11111111-1111-1111-1111-111111111111" "id": "20000000-0000-0000-0000-000000000000" "code": "31", "name": "Doces", "isActive": true }, { "parentId": "11111111-1111-1111-1111-111111111111" "id": "30000000-0000-0000-0000-000000000000" "code": "32", "name": "Amargas", "isActive": true } ] } ] }

 

Vamos entender na prático com o pasos a passo.

Passo a passo: Como criar a árvore de categorias

Criar as categorias em níveis, pois o o Id do primeiro nível será utilizado para vincular a categoria de segundo nível.

1. Criando o primeiro nível:

Endpoint: https://neomode.readme.io/reference/upsert-batch-categorires

Payload (Lista de NeoCategory sem parentId)

O Id (GUID) atribuído a categoria foi e2690e5c-d54d-4aea-9c9f-d3fd89869ad2. Utilizaremos para criar o próximo nível.

2. Criando os demais níveis:

Endpoint: https://neomode.readme.io/reference/upsert-batch-categorires

Atribuímos o Id (GUID) da cateogria mais alto ao campo parentId para criar o vínculo com a categoria mais baixa.

Payload (Lista de NeoCategory comparentId)

Agora, Frutas está abaixo de Alimentos.

O parentId será sempre o Id da categoria de nível superior.

 

Consultando as categorias criadas

Endpoint:

2. Produtos & Skus

Para construção do catálogo, existem duas formas de preenchimento dos produtos através do modelo de variações que ele foi montado:

  1. Produto único ou com preço por única variação (ex: perfume, valor diferente por frasco)

  2. Produto com grade com variação de cor ou tamanho.

 

Passo a passo: Como criar os produtos & skus

Forma 1: Produto único ou preço por variação

“Um produto para um sku”

  1. Criar 1 produto ( )

  2. Criar 1 Sku a partir do Guid do produto ()

Este cenário é utilizado para produtos que são tamanho único, não possuem grade ou não estão agrupados devidamente em sua grade.

Também é utilizado para necessidade de Preço por variação ("ml" de frascos de perfumes por exemplo) 

 

“Um produto para muitos skus”

  1. Criar 1 produto ( )

  2. Criar os Skus a partir do Guid do produto ()

Este cenário é utilizado para produtos que tem variação de tamanho ou cor (ou ambos) e são agrupados a um produto pai (ou código agrupador).

Ambiente Multi-loja

Nesse cenário, cada NeoProductPrice ou NeoSkuStock precisa ser relacionado a uma única loja ( ao NeoSeller). 

Gerenciamento de seller via API

  • Consultando a lista de sellers:

  • Criando um novo seller:

  • Editando um seller existente:

Estrutura dos pedidos

A estrutura de pedidos varia sendo ERP ou Canal de Venda. Durante a vida de um pedido nós podemos separar em fases.

  1. Criação do pedido pelo canal de venda.

  2. Reserva pelo ERP. (opcional)

  3. Aprovação do pagamento pelo canal de venda.

  4. Confirmação do pedido pelo ERP. (obrigatória)

  5. Faturamento do pedido pelo ERP.

  6. Dados de transporte preenchidos pelo ERP.

  7. Consumo das atualizações pelo canal de venda.

  8. Finalização do pedido.

 

Campos Identificadores do pedido

Campo

Tipo

Função

Onde encontrar via painel?

Campo

Tipo

Função

Onde encontrar via painel?

id

String (Guid)

Unique Identifier interno da Neomode.

Na URL (Link) da página.

ExternalId

String

Identificador do pedido no Canal de Venda.

No primeiro bloco do pedido

SellerOrderId

String

Identificarod do pedido no ERP.

No primeiro bloco do pedido

Implementando um fluxo de pedido Neomode via API como um ERP

Este modelo utiliza a API de pedidos v1 da Neomode.

Embora o uso da esteira de pedidos seja flexível. Segue abaixo uma sugestão de implementação e funcionamento

Status de pedidos na API:

Id

Status

CannonicalStatus

Descrição

Id

Status

CannonicalStatus

Descrição

0

None

CreatedInternal

Pedido Recebido

1

Pending

CreatedInternal

Pedido criado na Lori

2

PendingCreate

AwaitingCreation

Aguardando criação do pedido

3

PendingApproval

AwaitingCreation

Aguardando confirmação de ponto de venda

4

ApprovedExternal

CreatedExternal

Pedido confirmado no ponto de venda

5

Processing

AwaitingInvoiceCreation

Em faturamento

6

Separate

Separated

Produtos separados

7

InDelivery

Shipping

Em transporte

8

ReadyForPickup

ReadyForPickup

Pronto para retirada

9

Finalized

Finalized

Finalizado

10

CandeledBySeller

Canceled

Cancelado pelo ponto de venda

11

CanceledByBuyer

Canceled

Cancelado pelo consumidor

12

CanceledByAdmin

Canceled

Cancelado pelo administrador

13

PendingCancel

Canceled

Pendente de cancelamento

14

PendingCreatePreOrder

AwaitingCreation

Aguardando criação da pré-venda

15

PreOrderCreated

CreatedExternal

Pré-venda criada no ponto de venda

16

ErrorCancel

Error

Erro ao cancelar pedido

17

PendingUpdate

InProgress

Pendente de atualização

18

Updated

InProgress

Pedido atualizado

19

ErrorUpdate

Error

Erro ao atualizar pedido

20

InvoiceCreated

InvoiceCreated

Nota fiscal emitida

21

CanceledByProcessor

Canceled

Cancelado via processo

1. Buscar um pedido na Lori

Um pedido está pronto para coleta do ERP quando estiver no status aguardando criação do pedido Id:2 na API.

  1. Rota de consulta do pedido: ou .

  2. Na collection Postman fornecida, estão no caminho “Pedidos > Consultas”.

2. Confirmar pedido criado no ERP

Ao criar um pedido com sucesso, o ERP deve confirmar o pedido para pedido confirmado no pdv no painel Id:4 na API.

  1. Rota de atualização de status do pedido: .

  2. Na collection Postman fornecida, está no caminho “ERP - Ações do pedido > 1. Aprovar pedido”.]

 

2.1 Inserir o Código do ERP no pedido

Logo em seguida o ERP deve informar o código interno gerado para identificação.

  1. Rota de inserção do Código do ERP/PDV: .

  2. Na collection Postman fornecida, está no caminho “ERP - Ações do pedido > 2. Atualizar SellerOrderId através do Guid ”

Status transacionais (extras) flexíveis

Exemplo: Um pedido pode ficar em faturamento no painel e Processing ou Id:5 na API, logo após pedido confirmado no pdv (step anterior) se necessário.
📢 Os status transacionais são flexíveis e geralmente são utilizados para normatização da exibição ou mapeamento de fase de pedidos entre os canais de venda.
📢 Transições automáticas nascem desligadas por padrão.

 

3. Inserir dados de NFe / Faturar um pedido

Ao inserir os dados de faturamento o pedido transitará para nota fiscal emitida no painel e InvoiceCreated ou Id:20 na API.

  1. Rota de inserção dos dados de nota-fiscal
    (ao inserir a nota-fiscal o pedido transitará de 4 ou 5 para 20).

  2. Na collection Postman fornecida, está no caminho “ERP - Ações do pedido > 3. Inserir dados de faturamento através do SellerOrderId”

4. Notificar Entrega ou Retirada

Inserir dados de Entrega e Notificar Pedido em Transporte

Ao inserir os dados de rastreio o pedido transitará para em transporte no painel.

  1. Rota de inserção dos dados de entrega:

  2. Na collection Postman fornecida, está no caminho “ERP - Ações do pedido > 4. Inserir rastreio de entrega através do SellerOrderId”

 

 

Notificar pedido Pronto para Retirada

  1. Rota para inserir o status Pronto para retirada no painel ou ReadyForPickup e Id: 8 na API
    .

  2. Na collection Postman fornecida, deve alterar a rota de atualização para o respectivo status.

5. Finalizar pedido.

  1. Rota para inserir o status finalizado no painel ou Finalized e Id: 9 na API
    .

 

Arquivos para Download

Postman Collection & Environment

Como baixar e importar no Postman

  • Collection, Download:

  • Environment, Download: