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 a seguir como ter acesso à API pública e quais endpoints podem ser utilizados.
| Nota |
|---|
Pré-requisitosPara garantir o uso correto da funcionalidade, é necessário atender aos seguintes pré-requisitos:
|
...
Nesta documentação você aprenderá sobre:
| Índice | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
...
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:
...
Conforme indicado na ilustração, altera 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.
Role a tela para baixo até a seção BODY PARAMS e preencha os campos usuário e senha.
...
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.
...
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”.
...
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.
...
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:
...
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:
| Bloco de código | ||
|---|---|---|
| ||
[
{
"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.
...
No canto inferior direito é possível encontrar um exemplo de retorno da consulta em caso de sucesso.
...
Nota: 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.
...
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.
...
Para realizar uma inscrição no Webhook, o endpoint /configuracoes/topicos-webhook do tipo POST localizado na seção Configurações, vá até a opção Cadastrar e Atualizar Inscrição no 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.
...
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.
...
| Bloco de código | ||
|---|---|---|
| ||
{
"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.