APIs de Integração agnóstica com PDVs

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.

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, altera a palavra “domain” para o domínio personalizado da empresa.

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.

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.

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.

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.

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
  }
]

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.

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.

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 /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 requisitos necessários para a API de envio das 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:

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
}