WAKE OMS - APIs de Integração agnóstica com PDVs

Sobre a API de Integração Agnóstica

A API agnóstica para Pontos de Venda (PDVs) foi desenvolvida com o objetivo de proporcionar uma integração flexível e eficiente entre diferentes sistemas de vendas e plataformas de e-commerce. Esta API permite que os PDVs se conectem de maneira uniforme e padronizada, independentemente das tecnologias ou infraestruturas subjacentes.

Através da API REST pública da Wake OMS os PDVs poderão integrar dados de estoque, pedidos e faturamento.

Veja no fluxograma abaixo, como a API Agnóstica pode interagir com os principais players do mercado de e-commerce:

Clique na imagem para aumenta-la.


Veja a seguir como ter acesso à API pública e quais endpoints podem ser utilizados.

Principais Benefícios

Os principais benefícios de uma API agnóstica são:

• Flexibilidade: Adapta-se a diferentes ambientes e necessidades de negócios, proporcionando uma solução versátil e robusta.
  
  
• Redução de Custos: Diminui a necessidade de desenvolvimento de integrações específicas para cada sistema, reduzindo custos operacionais e de manutenção.
  
  
• Agilidade: Acelera a implementação de novos PDVs e funcionalidades, permitindo uma resposta rápida às demandas do mercado.
  
  
• Segurança: Garante a segurança dos dados transacionados, utilizando padrões de segurança reconhecidos e atualizados.
  
  

Público Alvo

O público-alvo para a API agnóstica para Pontos de Venda (PDVs) seria principalmente.

1. Empresas de Tecnologia: Organizações que oferecem soluções de software para o setor de varejo e e-commerce. A API permitiria que essas empresas oferecessem produtos mais versáteis e compatíveis com diversas infraestruturas.
   
   

2. Lojistas e Varejistas: Negócios que utilizam múltiplos sistemas de PDV e plataformas de e-commerce. A API ajudaria a unificar e padronizar a integração entre esses sistemas, facilitando a gestão e operação das vendas.
   
   
3. Consultores de TI: Profissionais que aconselham empresas sobre a implementação de tecnologias e sistemas de vendas. Eles poderiam recomendar o uso da API para melhorar a integração e eficiência dos sistemas de seus clientes.

Todas essas personas se beneficiariam diretamente da capacidade da API de proporcionar uma integração uniforme e padronizada, independentemente das tecnologias ou infraestruturas subjacentes. Isso resulta em maior eficiência, flexibilidade e compatibilidade entre diferentes sistemas de vendas e plataformas de e-commerce.

Acessando, configurando e autenticando a API

1. Para acessar a documentação da API pública do Wake OMS utilize o link API Wake OMS.
2. Após acessar a página da documentação, será necessário atualizar o domínio da URL responsável por enviar a requisição conforme demonstrado abaixo.
   
   No lado superior direito da tela o usuário encontrará o seguinte campo pré preenchido:
   
         Conforme indicado na ilustração, é necessário alterar a palavra “domain” para o domínio personalizado da empresa.
   
   Nota: Caso a empresa ainda não possua um domínio para uso da Wake OMS API, entre em contato com o suporte técnico para proceder com a solicitação.
3. Role a tela para baixo até a seção BODY PARAMS e preencha os campos usuário e senha.
   
4. Na seção RESPONSE, localizada do lado direito, é possível obter os dados de retorno. Caso a requisição tenha sido realizada com sucesso (código 200), copie o código impresso no campo token para utilizá-lo em outros endpoints de API.

    

Nota:

• Será retornado um token com validade de 1 hora e um refresh token com validade de 7 dias. O token deve ser usado em todas as requisições, o renovar token deve ser usado no endpoint "renovar-token" quando expirado o token, para obter um novo token válido por mais uma hora.
  
  
• O usuário e senha para acesso à API é o mesmo utilizado para acessar o Wake OMS Web e App, porém o acesso a API deverá ser habilitado nos parâmetros da conta conforme mostrado Aqui 

Estoques

Na seção estoques é possível localizar os endpoints necessários para gerenciar o compartilhamento de dados de estoque com a Wake OMS.

Atualizar Estoque
O primeiro passo será inserir informações relativas ao estoque. Para isso, usaremos o endpoint /pub/estoques.

Na documentação, seção Estoques, localizada à esquerda da tela, selecione o endpoint “Atualizar Estoque”.

Caso já tenha passado pelo processo de Autenticação, repare que o campo URL também presente na página deste endpoint já estará preenchido com os dados corretos.

Acima do campo URL estará o campo AUTHORIZATION, que deverá receber o token gerado no processo de autenticação.

O método utilizado neste endpoint é do tipo POST e deverá ter os parâmetros necessários preenchidos na seção BODY PARAMS (role a barra de rolagem até localizar a seção) do documento.

Notas:

• Os campos contaOms e cnpjLoja funcionam como chave de consulta. Ao menos um dos campos deverá ser preenchido para enviar os dados com sucesso.
  
  
• O campo com a subscrição “required” destacado em vermelho é de preenchimento obrigatório, juntamente com um dos campos citados anteriormente (contaOms e/ou cnpjLoja).
• O campo codigosBarras é do tipo Array de Strings, para adicionar registro neste campo de teste, basta clicar no campo abaixo ADD STRING. Para adicionar mais de uma informação, basta continuar clicando no campo ADD STRING.
• O campo quantidade possui valor padrão igual a “0”, o usuário deverá informar aqui a quantidade do produto em estoque.
  
  

Consultar Estoque

Além da inclusão/atualização do estoque, é possível consultá-lo através do endpoint /pub/estoques. Veja abaixo como utilizá-lo.

Em Consultar Estoque, seção disponível do lado esquerdo da tela, logo abaixo de Atualizar Estoques, caso já tenha realizado testes em outro endpoint, o campo AUTHORIZATION já conterá o token necessário para prosseguir com a consulta.

Ao contrário do endpoint anterior, este utiliza o método GET para enviar requisições. É possível ainda enviar QUERY PARAMS, conforme abaixo, para filtrar o resultado.

Notas:

• Os campos contaOms e cnpjLoja funcionam como chave de consulta. Ao menos um dos campos deverá ser preenchido para enviar os dados com sucesso.
  
  
• O parâmetro pagina é obrigatório.

Exemplo de retorno da requisição em caso de sucesso:

{
"mensagem": "Sucesso",
"dados": 
{
"lista":
[
{
"contaOms": "contaOms",
"cnpjLoja": "29488489000174",
"codigoSkuPdv": "01.01.0001_003_1",
"codigosBarra": "01010001003P",
"codigoSkuVinculoEcommerce": "01.01.01.062_003_1",
"idSkuEcommerce": "123456",
"descricaoSku": "Blusa Síntese - Azul - P",
"quantidadeSku": 10,
"ajusteSku": -1,
"deflatorSku": 1,
"deflatorContaOms": 0,
"deflatorCluster": 0,
"dataHoraIntegracaoLoja": "2023-10-03T12:23:26.163",
"dataHoraIntegracaoSite": "2024-05-28T20:20:20.873"
}
],
"pagina": 1,
"por_Pagina": 100,
"total": 758,
"paginas": 8
}
}

Criar ou Atualizar Deflatores

Outro recurso disponível na seção Estoques é o deflator de estoque. Trata-se de uma ferramenta que permite parametrizar uma quantidade segura de um determinado produto no estoque da loja, especialmente ao atender à prateleira infinita.

Exemplo: suponha que a loja possua 3 unidades de um determinado produto em estoque. Se for definido um deflator com valor 1 para esse produto, o sistema considerará a disponibilidade de apenas 2 unidades para atender o e-commerce ou outras unidades.

Para configurar o deflator em uma loja/estoque, devemos utilizar o endpoint /pub/estoques/atualizar-deflator do tipo POST.

Caso os passos de acesso e autenticação tenham sido realizados, o campo AUTHORIZATION e URL já estarão com os dados necessários para prosseguir com a requisição.

Desça com a barra de rolagem até localizar a seção BODY PARAMS.

Notas:

• Repare que os parâmetros contaOms e codigoSkuPdv são obrigatórios para este POST.
  
  
• O campo deflator tem valor padrão 0 e terá efeito apenas se já existir o registro de deflator para o produto.
  
  

Exemplo do array JSON que deverá ser enviado através do BODY:

[
{
"contaOms": "Loja1",
"codigoSkuPdv": "74.01.0300_73_1",
"deflator": 1
},
{
"contaOms": "Loja2",
"codigoSkuPdv": "74.01.0300_73_2",
"deflator": null
}
]

Notas:

• Esse endpoint permite a atualização do deflator de estoque para uma lista de até 20 Sku por vez.
  
  
• Para remover o deflator do SKU, enviar null, se enviar 0 (zero) será considerado que o SKU deve ter o deflator 0.
• O Deflator no nível de SKU tem prioridade sobre o deflator no nível de loja.
  
  

Pedidos

O passo seguinte no processo de integração do PDV é integrar os pedidos e realizar a atualização de dados de faturamento. O usuário deverá acessar a seção Pedidos, localizado do lado esquerdo da página de documentação da API.

Consultar Pedidos

Para realizar a consulta aos pedidos, deverá ser utilizado o endpoint /pub/pedidos do tipo GET.
Conforme já mencionado anteriormente, caso os passos de acesso e autenticação tenham sido realizados, o campo AUTHORIZATION e URL já estarão com os dados necessários para prosseguir com a requisição.

Utilizando a barra de rolagem, para chegar até a seção QUERY PARAMS, poderá se testar os parâmetros obrigatórios e opcionais de consulta dos pedidos.

A integração deverá ter ao menos um dos dois campos, contaOms ou cnpjLoja preenchidos para prosseguir, conforme descritivo dos campos no site da documentação.

No canto inferior direito é possível encontrar um exemplo de retorno da consulta em caso de sucesso.

Notas:

Caso a consulta seja realizada apenas pelo status do pedido, o valor deverá ser 2 - Aceito

Faturar

 

Após consultar um pedido com status de Aceito, o PDV poderá processar a fatura, para isso, utilizará o endpoint /pub/pedidos/faturar do tipo POST. A documentação estará disponível na seção Pedidos.

Conforme já mencionado anteriormente, caso os passos de acesso e autenticação tenham sido realizados, o campo AUTHORIZATION e URL já estarão com os dados necessários para prosseguir com a requisição.

Utilizando a barra de rolagem, para chegar até a seção BODY PARAMS, poderá se testar os parâmetros obrigatórios e opcionais para envio dos dados.

Notas:

O campo com a subscrição “required” destacado em vermelho é de preenchimento obrigatório.

 

É necessário informar a conta (parâmetro contaOms) a qual está tentando consultar, ou CNPJ (parâmetro cnpjLoja) da conta.

A seção de Pedidos ainda conta com diversos outros endpoints que podem complementar o quadro de informações para uma integração com PDV:

 

• Cancelar Pedido (endpoint do tipo POST: /pub/pedidos/cancelar) - Através desse endpoint é possível enviar o cancelamento de um pedido.
  
  
• Pedido Entregue (endpoint do tipo POST: /pub/pedidos/entregue) - Através desse endpoint é possível comunicar a entrega de um pedido.
  
  
• Expedir Pedido (endpoint do tipo POST: /pub/pedidos/expedir) - Através desse endpoint é possível indicar que um pedido foi expedido no ponto de envio.
  
  
• Consultar Faturamento (endpoint do tipo GET: /pub/pedidos/dados-faturamento) - Através desse endpoint é possível consultar os dados de faturamento de um pedido na OMS.
  
  

Configurar Atualização Automática de Pedido por Webhook

Através da seção Configurações, é possível criar a inscrição no Webhook para obter atualização automática de pedidos.
O processo se resume a enviar para inscrição a URL com o Endpoint da API que deverá receber os dados e informar quais filtros o webhook deverá considerar para realizar o disparo automático. Veja a seguir como deverá funcionar.

Cadastrar e Atualizar Inscrição no Webhook
Para realizar uma inscrição no Webhook, o endpoint /pub/configuracoes/topicos-webhook do tipo POST localizado na seção Configurações, vá até a opção Cadastrar e Atualizar Inscrição no Webhook.

Conforme já mencionado anteriormente, caso os passos de acesso e autenticação tenham sido realizados, o campo AUTHORIZATION e URL já estarão com os dados necessários para prosseguir com a requisição.

Utilizando a barra de rolagem, para chegar até a seção BODY PARAMS, poderá se testar os parâmetros obrigatórios e opcionais para envio dos dados.

id: caso a requisição seja para atualizar uma inscrição existente, o usuário deverá informar neste campo a ID da inscrição que deverá ser atualizada. Caso seja um cadastro, basta deixar o campo null.

topico: refere-se ao tópico da qual está se escrevendo. Veja na requisição de exemplo abaixo.

url: endereço da api e endpoint da qual o webhook deverá enviar a atualização.

filtros: Os filtros são um array de objtos com os seguintes parâmetros:

contasOms: conta(s) que serão monitoradas pelo webhook, caso a inscrição deva ter efeito em todas as contas o sinal * deverá ser utilizado.

contasOmsIgnorar: conta(s) que serão ignoradas pelo webhook. Esse parâmetro sobrepõe o parâmetro anterior e deverá ser enviada com o valor null caso não haja contas a serem ignoradas.

idsStatus: trata-se da id do status do pedido que será notificado pelo webhook.

headers: O campo headers é um array de objetos e trata-se de parâmetros que poderão ser enviados de acordo com a necessidade da API para onde serão enviadas as atualizações. Caso não sejam necessários, os campos deverão ser enviados com valor null

chave: tipo de chave de acesso à API.

valor: valor que será enviado para a chave.

email: conta de e-mail na qual será enviada notificação em caso de falha de envio das atualizações.

observacao: campo de texto livre, para por exemplo, guardar informações sobre o motivo da inscrição.

inativo: campo que guarda o status da inscrição, possui valor padrão false.

Exemplo de requisição:

 

{
"id": 0,
"topico": "Pedido.Status",
"url": "https://minhaApi.teste.com.br/notificacaoStatus",
"filtros": [
{
"contaOms": ["*"],
"contaOmsIgnorar": ["Loja 1"],
"idsStatus": ["1","2"]
}
],
"headers": [
{
"chave": "Token",
"valor": "abcs"
}
],
"email": "testes@teste.com.br",
"observacao": "inscrição utilizada para integração dos pedidos com o PDV",
"inativo": false
}

Consultar Inscrições do Webhook

Para atualizar uma inscrição no Webhook é necessário ter o seu ID, para isso, basta utilizar o endpoint /configuracoes/topicos-webhook do tipo GET.

Conforme já mencionado anteriormente, caso os passos de acesso e autenticação tenham sido realizados, o campo AUTHORIZATION e URL já estarão com os dados necessários para prosseguir com a requisição.

Utilizando a barra de rolagem, para chegar até a seção QUERY PARAMS, poderá se testar o parâmetro obrigatório para consulta dos dados.

Veja o exemplo:

Exemplo de Response body:

Notas:

• Conforme explicado sobre o campo email, através dele é possível informar uma conta de e-mail para receber notificações de falha de envio no Webhook. Caso seja gerado um total de 50 erros de envio, o sistema automaticamente desativará o serviço para aquela inscrição.
  
  
• É necessário que a conta utilizada para se conectar a Wake API tenha o recurso Webhook habilitado, conforme demonstrado Aqui.

Incluir Vendedores

É possível utilizar o endpoint do tipo POST /pub/vendedores para incluir ou atualizar vendedores no sistema. A inclusão do cadastro dos vendedores no sistema é essencial para associar cada vendedor às respectivas vendas, permitindo a geração de relatórios de desempenho detalhados posteriormente.
Conforme já mencionado anteriormente, caso os passos de acesso e autenticação tenham sido realizados, o campo AUTHORIZATION e URL já estarão com os dados necessários para prosseguir com a requisição.

Utilizando a barra de rolagem, para chegar até a seção BODY PARAMS, poderá se testar os parâmetros obrigatórios e opcionais para envio dos dados.

Exemplo do JSON de requisição:

 

{
"código": "V123",
"contaOms": "Loja1",
"cnpjLoja": "29488489000174",
"nome": "Joana Silva",
"apelido": "Joan",
"dataAtivacao": "2022-01-10",
"dataDesativacao": null
}

Notas:

O campo com a subscrição “required” destacado em vermelho é de preenchimento obrigatório.
É necessário informar a conta (parâmetro contaOms) a qual está tentando consultar, ou CNPJ (parâmetro cnpjLoja) da conta.

 

O campo dataDesativacao possui valor padrão null, qualquer outro valor no formato campo, irá desativar o cadastro do vendedor.