/
APIs de Integração agnóstica com PDVs
  • Verificado
  • APIs de Integração agnóstica com PDVs

    Pré-requisitos

    Para garantir o uso correto da funcionalidade, é necessário atender aos seguintes pré-requisitos:

    • Ser cliente da Wake OMS.


    Nesta documentação você aprenderá sobre:


    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.
    image-20250205-193544.png

    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.

     

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

     

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

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

    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.

     

    1. Role a tela para baixo até a seção BODY PARAMS e preencha os campos usuário e senha.

    1. 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 /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:


    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:

    Related content

    Configuração de Integração
    Configuração de Integração
    More like this
    Contas e Permissões da Conta
    Contas e Permissões da Conta
    Read with this
    API Pública para Consulta de Ruptura de Pedidos
    API Pública para Consulta de Ruptura de Pedidos
    More like this
    Integração Transportadoras
    Integração Transportadoras
    More like this

    @2024 Síntese, uma empresa LWSA