...

Table of Contents

minLevel	1
maxLevel	3
include
outline	false
indent
style	default
exclude
type	list
class
printable	true

A Interface de conexão da Neomode

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

Documentação API Oficial

...

Arquivos para Download

Coleção do Postman + Environment

Como baixar e importar no Postman https://learning.postman.com/docs/getting-started/importing-and-exporting/importing-and-exporting-overview/

Collection (coleção) Download:
View file
name NEOMODE - Lori APIs.postman_collection.json
Environment (variáveis de automação) Download:
View file
name LORI API-production.postman_environment.json

Atribuições de Integração: ERP vs 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

...

Ações em Catálogo

Cadastrar a árvore de categorias.
Cadastrar os produtos & skus.
Inserir preço nos produtos da loja.
Inserir estoque nos skus da loja.

Ações em Pedidos

Adquirir os novos pedidos.
Aprovar os novos pedidos.
Faturar os pedidos aprovados (inserindo os dados da nota fiscal).
Inserir os dados de transporte ou confirmar retirada dos pedidos faturados.

...

Responsabilidades conectando como um Canal de Venda

...

Ações em Pedidos

Criar pedido.
Aprovar pagamento.
Consumir dados de faturamento.
Consumir dados de entrega ou retirada do pedido.

Ações em Catálogo

Consumir árvore de categorias.
Consumir produtos & skus.
Consumir movimentações de estoque.
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):

Code Block

language	json

{"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:

Code Block
--header 'Authorization: Bearer put_token_here' \

...

Estrutura de catálogo

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

Categorias
Produtos (Agrupador)
Skus (Variações)
Preços
Saldos de estoque.
Loja(s)

...

1. Árvore de categorias

Anchor

	Como-criar-categorias
	Como-criar-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 parentIddentro 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.

...

Expand

title	Estrutura de um NeoCategory

Code Block

language	json

{
    "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

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

Expand

title	Passo a passo: Como criar a Árvore de Categorias

1. Criando o primeiro nível:

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

Payload (Lista de NeoCategory sem parentId)

Code Block

language	json

[
  {
		"code": "11",
		"name": "Alimentos"
  }
]

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)

Code Block

language	json

[
    {
        "parentId": "e2690e5c-d54d-4aea-9c9f-d3fd89869ad2",
        "code": "21",
        "name": "Frutas"
    }
]

Agora, Frutas está abaixo de Alimentos.

Panel

panelIconId	1f4a1
panelIcon	:bulb:
panelIconText	💡
bgColor	#FFFAE6

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

Consultando as categorias criadas

Endpoint: https://neomode.readme.io/reference/consultar-categorias

...

2. Produtos & Skus

Anchor

	Como-criar-produtos-&-skus
	Como-criar-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:

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

...

Image Added

Passo a passo: Como criar os produtos & skus

Expand

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

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

“Um produto para um sku”

Criar 1 produto (https://neomode.readme.io/reference/create-product )
Criar 1 Sku a partir do Guid do produto (https://neomode.readme.io/reference/create-sku)

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)

...

Image Added

Expand

title	Forma 2: Produto com grade ou preço tabelado

Info
Forma 2: Produto com grade ou preço tabelado

“Um produto para muitos skus”

Criar 1 produto (https://neomode.readme.io/reference/create-product )
Criar os Skus a partir do Guid do produto (https://neomode.readme.io/reference/create-sku)

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).

...

Image Added

Observações

O produto (agrupador) é atribuído a uma categoria.
Um sku (variação) só existe a partir de um produto.
O preço é atribuído ao produto & a uma loja.
- O preço do produto vale para todos os Skus.
O estoque é atribuído ao sku & a uma loja.

...

Ambiente Multi-loja

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

Note
Haverá mais de um estoque & preço apenas quando houver mais de uma loja.

Gerenciamento de seller via API

Consultando a lista de sellers: https://neomode.readme.io/reference/get-sellers-list
Criando um novo seller: https://neomode.readme.io/reference/post-create-seller
Editando um seller existente: https://neomode.readme.io/reference/put-update-seller

Estrutura dos pedidos

Anchor

	Estrutura-de-pedidos
	Estrutura-de-pedidos

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

Criação do pedido pelo canal de venda.
Reserva pelo ERP. (opcional)
Aprovação do pagamento pelo canal de venda.
Confirmação do pedido pelo ERP. (obrigatória)
Faturamento do pedido pelo ERP.
Dados de transporte preenchidos pelo ERP.
Consumo das atualizações pelo canal de venda.
Finalização do pedido.

Campos Identificadores do pedido

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

Anchor

	Fluxo-do-pedido-via-Enpoints-Lori
	Fluxo-do-pedido-via-Enpoints-Lori

`Status` de pedidos na API:

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

Status

title	aguardando criação do pedido

Id:2 na API.
Rota de consulta do pedido: https://neomode.readme.io/reference/getordersbyguidid ou https://neomode.readme.io/reference/consulta-pedidos-por-loja-getordersbyseller.
Na collection Postmanfornecida, 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
Status
colour Green
title pedido confirmado no pdv
no painel Id:4 na API.
Rota de atualização de status do pedido: https://neomode.readme.io/reference/atualiza-status-de-um-pedido-updateorderstatus.
Na collection Postmanfornecida, 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.
Rota de inserção do Código do ERP/PDV: https://neomode.readme.io/reference/update-sellerorderid-of-an-order.
Na collection Postmanfornecida, 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
Status
colour Yellow
title em faturamento
no painel e Processing ou Id:5 na API, logo após
Status
colour Green
title 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
Status
colour Blue
title nota fiscal emitida
no painel e InvoiceCreated ou Id:20 na API.
Rota de inserção dos dados de nota-fiscal
https://neomode.readme.io/reference/atualizar-detalhes-da-nota-fiscal-updateinvoicedetailsasync (ao inserir a nota-fiscal o pedido transitará de 4 ou 5 para 20).
Na collection Postmanfornecida, 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
Status
colour Blue
title em transporte
no painel.
Rota de inserção dos dados de entrega: https://neomode.readme.io/reference/upsertordertrackingdetailsasync
Na collection Postmanfornecida, está no caminho “ERP - Ações do pedido > 4. Inserir rastreio de entrega através do SellerOrderId”
Image Modified
Notificar pedido Pronto para Retirada
Rota para inserir o status
Status
colour Green
title Pronto para retirada
no painel ou ReadyForPickup e Id: 8 na API
https://neomode.readme.io/reference/atualiza-status-de-um-pedido-updateorderstatus.
Na collection Postmanfornecida, deve alterar a rota de atualização para o respectivo status.
...
5. Finalizar pedido.
Rota para inserir o status
Status
colour Green
title finalizado
no painel ou Finalized e Id: 9 na API
https://neomode.readme.io/reference/atualiza-status-de-um-pedido-updateorderstatus.
...
Histórico da atualizações da página
Expand
Change History

Versions Compared

Old Version 45

New Version Current

Key

A Interface de conexão da Neomode

Arquivos para Download

Coleção do Postman + Environment

Atribuições de Integração: ERP vs Canal de Venda

Responsabilidades conectando como um ERP

Ações em Catálogo

Ações em Pedidos

Responsabilidades conectando como um Canal de Venda

Ações em Pedidos

Ações em Catálogo

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

Estrutura de catálogo

1. Árvore de categorias

Passo a passo: Como criar a árvore de categorias

1. Criando o primeiro nível:

2. Criando os demais níveis:

Consultando as categorias criadas

2. Produtos & Skus

Passo a passo: Como criar os produtos & skus

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

Forma 2: Produto com grade ou preço tabelado

Ambiente Multi-loja

Gerenciamento de seller via API

Estrutura dos pedidos

Implementando um fluxo de pedido Neomode via API como um ERP

`Status` de pedidos na API:

1. Buscar um pedido na Lori

2. Confirmar pedido criado no ERP

2.1 Inserir o Código do ERP no pedido

Status transacionais (extras) flexíveis

3. Inserir dados de NFe / Faturar um pedido

4. Notificar Entrega ou Retirada

Inserir dados de Entrega e Notificar Pedido em Transporte

Notificar pedido Pronto para Retirada

5. Finalizar pedido.

Histórico da atualizações da página

Page Comparison

Versions Compared

Old Version 45

New Version Current

Key

A Interface de conexão da Neomode

Arquivos para Download

Coleção do Postman + Environment

Atribuições de Integração: ERP vs Canal de Venda

Responsabilidades conectando como um ERP

Ações em Catálogo

Ações em Pedidos

Responsabilidades conectando como um Canal de Venda

Ações em Pedidos

Ações em Catálogo

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

Estrutura de catálogo

1. Árvore de categorias

Passo a passo: Como criar a árvore de categorias

1. Criando o primeiro nível:

2. Criando os demais níveis:

Consultando as categorias criadas

2. Produtos & Skus

Passo a passo: Como criar os produtos & skus

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

Forma 2: Produto com grade ou preço tabelado

Ambiente Multi-loja

Gerenciamento de seller via API

Estrutura dos pedidos

Implementando um fluxo de pedido Neomode via API como um ERP

Status de pedidos na API:

1. Buscar um pedido na Lori

2. Confirmar pedido criado no ERP

2.1 Inserir o Código do ERP no pedido

Status transacionais (extras) flexíveis

3. Inserir dados de NFe / Faturar um pedido

4. Notificar Entrega ou Retirada

Inserir dados de Entrega e Notificar Pedido em Transporte

Notificar pedido Pronto para Retirada

5. Finalizar pedido.

Histórico da atualizações da página

`Status` de pedidos na API: