Atualização automática de PDVs via ERP – Versões por empresa e regras de bloqueio

Resumo do que será ensinado

Este documento explica como funciona o processo de atualização automática de PDVs via ERP, utilizando o recurso de versão específica por PDV/empresa e bloqueio de atualização, bem como o uso das rotas de API relacionadas (ping autenticado, ping sem autenticação e consulta direta à tabela de versão). O objetivo é que qualquer responsável técnico de PDV consiga configurar e consumir corretamente essas rotas para controlar versões de forma segura e centralizada.

Segue um Vídeo explicativo do processo

Detalhamento do uso correto

Com este guia, você deve ser capaz de utilizar o recurso de versão por PDV no ERP, configurando regras por empresa, bloqueando atualizações quando necessário e consumindo as rotas de API adequadas (com ou sem autenticação). Siga cada passo cuidadosamente e aproveite as funcionalidades do sistema!

Segue o detalhamento de como utilizar a atualização automática de PDVs via ERP

1. Entendendo o conceito de versão por PDV no ERP.

   • O ERP disponibiliza uma rota utilizada pelos PDVs para informar seu estado atual e, em resposta, receber qual versão devem utilizar.
   • Os PDVs (incluindo PDVs legados) já possuem a prática de consumir uma rota de ping, informando dados básicos do terminal.
   • Ao receber a chamada dessa rota, o ERP:
     
     • Identifica o PDV e o módulo correspondente.
     • Calcula qual é a versão “resolvida” que aquele PDV deve utilizar (considerando regras globais e específicas por empresa).
     • Retorna para o PDV:
     • Versão definida para aquele PDV (por exemplo, 13.1 ou 14.0).
     • Link de download da versão indicada (URL para obter o instalador/atualizador).
   • Ponto de atenção: o PDV deve sempre utilizar essa rota de ping para saber qual versão usar antes de iniciar qualquer processo de atualização.

2. Fluxo padrão de consulta de versão e atualização do PDV.

   • Ação do PDV – Chamada da rota de ping:
     
     • O PDV chama a rota de ping para informar:
     • Serial atual do PDV.
     • Versão atualmente instalada no PDV.
     • Demais informações técnicas necessárias (modelo, nome, etc. – detalhadas mais abaixo).
   • Resposta do ERP:
     
     • O ERP analisa as regras de versão e retorna:
     • O módulo do PDV.
     • A versão que o PDV deve utilizar (versão oficial ou específica) – por exemplo, 13.1.
     • A URL de download do pacote de atualização correspondente àquela versão.
   • Processo de atualização no PDV:
     
     • O PDV recebe a versão e o link de download.
     • Inicia o processo de download e instalação da nova versão.
     • Após concluir a atualização, o PDV:
     • Volta a chamar a rota de ping informando sua nova versão instalada (por exemplo, 14.0).
   • Atualização do painel no ERP:
     
     • Ao receber o novo ping com a versão atualizada:
     • O ERP passa a exibir esse PDV na nova versão em seus relatórios/consultas (por exemplo, PDV na versão 14.0).
   • Ponto de atenção: o retorno da versão correta depende das regras configuradas por empresa e da versão padrão global do ERP.

3. Configurando regra de versão específica por empresa.

   • O ERP permite definir uma versão específica para uma determinada empresa, diferente da versão global.
   • Exemplo de uso:
     
     • Versão oficial global: 13.1.
     • Desejo que uma empresa específica receba a versão 14.0 (por exemplo, versão beta ou teste).
   • Passos para configurar a regra no ERP:
   1. Acesse o módulo de configuração de versão no ERP.
   2. Selecione a empresa desejada (pela identificação cadastrada no ERP).
   3. Defina que, para esta empresa:
      
      • A versão a ser entregue será, por exemplo, 14.0.
      • Configure a URL de download correspondente à versão 14.0 (pode ser uma URL diferente da versão oficial).
   4. Aplique a regra para essa empresa.
   • Comportamento após configurar:
     
     • Na próxima chamada de ping realizada pelo PDV dessa empresa:
     • Em vez de receber a versão padrão 13.1, o ERP retornará:
       
       • Versão 14.0 como versão resolvida.
       • Link de download da versão 14.0.
     • O PDV seguirá para o processo de atualização, instalará a versão 14.0 e informará essa versão no próximo ping.
   • Retorno à versão padrão:
     
     • Caso você remova a regra específica da empresa:
     • Na próxima consulta de versão (ping), o PDV voltará a receber a versão padrão global (por exemplo, 13.1).
     • O PDV poderá atualizar novamente para essa versão padrão, comunicar no ping e ser exibido como estando na versão padrão.
   • Pontos de atenção:
     
     • Use regras específicas para testes controlados, versões beta ou correções temporárias em uma empresa.
     • Lembre-se de excluir a regra quando quiser que a empresa volte a receber a versão oficial global.

4. Entendendo o bloqueio de atualização por empresa.

   • Além de versões específicas, o ERP permite bloquear a atualização de uma empresa, mantendo-a sempre em uma determinada versão, mesmo que versões novas sejam lançadas.
   • Objetivo do bloqueio:
     
     • Garantir que uma empresa não seja atualizada automaticamente, por motivos como:
     • Ambiente crítico.
     • Dependência de integrações não compatíveis com novas versões.
     • Período de testes ou homologação interna.
   • Passos para configurar bloqueio de atualização:
   1. Acesse a tela de configuração de bloqueio de atualização no ERP.
   2. Selecione a empresa que deseja bloquear.
   3. Informe o CNPJ desta empresa (ou identificador equivalente).
   4. Marque a empresa como bloqueada para atualização.
   • Comportamento após o bloqueio:
     
     • Ao consultar a versão para essa empresa, o ERP continuará retornando a versão atual da empresa (por exemplo, 13.1).
     • O sistema registra que essa empresa está bloqueada, e:
     • Mesmo que seja lançada uma nova versão global (por exemplo, 13.2),
     • Essa empresa continuará recebendo a versão 13.1.
     • As demais empresas (não bloqueadas) passarão a receber a nova versão global 13.2 normalmente.
   • Pontos de atenção:
     
     • O bloqueio afeta somente a empresa configurada, sem alterar o fluxo das demais.
     • Utilize o bloqueio quando quiser impedir qualquer atualização automática, garantindo estabilidade naquele ambiente.

5. O que mudou para o PDV: novos campos “modelo” e “nome”.

   • A rota de ping já existia e era utilizada pelos PDVs, porém foram adicionados dois novos campos: modelo e nome.
   • Campo “modelo”:
     
     • Pode representar, por exemplo:
     • O sistema operacional utilizado no computador do PDV.
     • A versão da maquininha (terminal físico).
     • Utilidade:
     • Ajuda o ERP e a equipe técnica a identificar o ambiente do PDV, especialmente em ações como atualização em massa ou análise de compatibilidade.
   • Campo “nome”:
     
     • Pode ser o nome do computador ou identificação amigável do PDV.
     • Facilita o reconhecimento do equipamento em relatórios ou telas de monitoramento.
   • Impacto para PDVs já integrados:
     
     • Como a rota já era utilizada, a adaptação é simples:
     • Basta adicionar esses dois novos campos (modelo e nome) nas chamadas já existentes.
   • Ponto de atenção:
     
     • Certifique-se de enviar valores significativos nesses campos, para que o ERP possa utilizar essas informações em diagnósticos e ações de suporte.

6. Ping sem autenticação para PDVs não integrados ao ERP.

   • Foi adicionada a possibilidade de chamar a rota de ping sem autenticação, voltada para PDVs que ainda não utilizam autenticação com o ERP.
   • Diferença em relação ao ping autenticado:
     
     • No ping autenticado, normalmente são informados API Key ou Authorization (token).
     • No ping sem autenticação, esses campos não são enviados.
   • Campos obrigatórios no ping sem autenticação:
     
     • Em vez de API Key/Authorization, o ERP precisa saber a empresa responsável pelo PDV.
     • Por isso, é necessário informar:
     • CPF ou CNPJ da empresa.
     • Número do PDV na loja (identificação do terminal – campo opcional).
   • Detalhamento dos campos:
     
     • CPF/CNPJ da empresa:
     • Permite ao ERP rastrear a qual empresa o PDV pertence.
     • É essencial para associar o PDV às regras de versão e bloqueio configuradas para aquela empresa.
     • Número do PDV (opcional):
     • Identifica o PDV dentro da loja.
     • Caso não exista ou não seja necessário, pode ser omitido.
   • Demais informações enviadas:
     
     • Todos os outros campos enviados no ping autenticado (serial, versão atual, modelo, nome etc.) continuam sendo enviados também no ping sem autenticação.
   • Resumo de uso:
     
     • PDVs autenticados: enviam API Key/Authorization para identificar a empresa e o PDV.
     • PDVs não autenticados: enviam CPF/CNPJ e, opcionalmente, o número do PDV, para que o ERP possa rastrear a empresa e aplicar as regras de versão/bloqueio.

7. Consulta direta à tabela de versão de PDV (rota de versão).

   • Além da rota de ping, existe uma rota que consulta diretamente a tabela de versão de PDV no ERP, retornando qual é a versão atual disponível para aquele PDV.
   • Esta rota é utilizada, por exemplo, pelo PDV de determinados parceiros (como o PDV “do Joe”, citado no vídeo).
   • Comportamento dessa rota:
     
     • A rota consulta o registro de versão associado ao PDV.
     • Retorna a versão mais recente disponível conforme as regras aplicadas (global, por empresa, bloqueios etc.).
   • Atualizações na rota de versão:
     
     • Essa rota passou a receber os mesmos parâmetros que a rota de ping.
     • Para quem já chamava a rota no formato PDV/versão/…, agora pode enviar os mesmos parâmetros utilizados no ping (incluindo modelo, nome, CNPJ/CPF quando não autenticado, etc.).
     • A lógica de resolução será a mesma da rota de ping.
   • Ponto de atenção:
     
     • As três rotas (ping autenticado, ping sem autenticação e consulta direta à versão) passam a funcionar de forma equivalente na resolução de versão, com apenas diferenças no perfil de autenticação e forma de identificação da empresa/PDV.

8. Uso das três rotas de forma integrada.

   • O ERP oferece, portanto, três mecanismos principais para o PDV consultar a versão:
   1. Rota de ping autenticado:
      
      • Envia API Key/Authorization.
      • Utiliza a autenticação para identificar empresa e PDV.
   2. Rota de ping sem autenticação:
      
      • Não utiliza API Key/Authorization.
      • Identifica a empresa por CPF/CNPJ e, opcionalmente, o número do PDV.
   3. Rota de consulta direta à versão (tabela de versão):
      
      • Vai diretamente na tabela de versão de PDV.
      • Recebe hoje os mesmos parâmetros que o ping, e resolve a versão da mesma forma.
   • Perfil de uso (O PFL diferente):
     
     • Cada rota pode ter um perfil de uso diferente (por tipo de integração, segurança, legado, etc.), porém:
     • Todas acabam por resolver a versão de maneira consistente, considerando regras globais, específicas por empresa e bloqueios.

9. Documentação complementar disponível no ERP.

   • Para auxiliar equipes de desenvolvimento e suporte dos PDVs, foi criada uma documentação oficial disponível via link dentro do ERP.
   • Essa documentação inclui:
     
     • Explicação detalhada de como funciona o mecanismo de versão por PDV.
     • Diferença entre as três rotas (ping autenticado, ping sem autenticação, rota de versão).
     • Como chamar cada rota, com exemplos práticos.
     • Lista de informações obrigatórias e opcionais em cada requisição.
     • Modelos de chamada via HTTP/API e orientações sobre parâmetros.
   • Ponto de atenção:
     
     • Consulte sempre esta documentação para obter o formato exato dos requests, headers e estruturas de dados esperadas, evitando erros de integração.

10. Integração via MQTT para notificações de novas versões.

    • Além das rotas HTTP de consulta, o ERP fornece um padrão de integração via MQTT, semelhante ao que é utilizado pela interface do sistema.
    • Funcionamento básico:
      
      • O PDV faz uma conexão via MQTT seguindo o padrão definido na documentação.
      • Recebe uma URL com tempo limite (time-limited URL), que será utilizada para receber notificações de nova versão.
      • Sempre que uma nova versão for publicada no ERP:
      • Os PDVs que estiverem assinados no canal/URL receberão uma notificação informando que existe nova versão disponível.
    • Vantagens:
      
      • Permite que PDVs sejam notificados em tempo real sobre novas versões, sem precisar consultar a rota de ping de forma contínua.
      • Auxilia em estratégias de atualização em massa, reduzindo tráfego desnecessário e tempo de resposta.
    • Ponto de atenção:
      
      • O padrão de conexão MQTT (broker, tópicos, payloads, autenticação, etc.) está descrito na documentação do ERP e deve ser seguido rigorosamente para garantir o recebimento das notificações.

11. Orientações práticas para implementação no PDV.

    • Ao implementar ou ajustar a integração do PDV:
      
      • Sempre envie a versão atual instalada do PDV nas chamadas de ping.
      • Adicione os campos modelo e nome, conforme indicado, para melhor rastreio e suporte.
      • Se o PDV estiver autenticado:
      • Utilize API Key/Authorization nas requisições.
      • Se o PDV não estiver autenticado:
      • Informe corretamente o CPF/CNPJ da empresa e, se possível, o número do PDV.
    • Ao trabalhar com empresas específicas:
      
      • Verifique se há alguma regra de versão específica configurada para a empresa.
      • Confirme se a empresa não está em estado de bloqueio de atualização, o que impediria o recebimento de novas versões.
    • Ao planejar atualizações em massa:
      
      • Utilize os campos modelo e nome para selecionar grupos de PDVs por sistema operacional, tipo de maquininha ou identificação de estação.
      • Considere o uso do MQTT para disparar notificações coordenadas de nova versão e, assim, iniciar processos de atualização simultâneos.

12. Boas práticas e possíveis variações de uso.

    • Variações de versão:
      
      • As regras podem apontar para:
      • Versões novas/oficiais.
      • Versões beta (para testes).
      • Versões retroativas (voltar temporariamente a uma versão anterior).
    • Gestão de risco:
      
      • Utilize o bloqueio de atualização em empresas com operações críticas, onde qualquer mudança precisa ser planejada.
      • Use versões específicas para pilotos controlados, antes de liberar uma nova versão para todo o parque de PDVs.
    • Monitoramento:
      
      • Após alterações de regras de versão ou bloqueio, monitore os pings recebidos e versões instaladas reportadas pelos PDVs, garantindo que o comportamento esteja conforme o planejado.

Informações Importantes

• Resumo das principais orientações.

  • Sempre use a rota de ping (autenticada ou não) para o PDV descobrir qual versão deve instalar.
  • Configure regras específicas por empresa quando precisar diferenciar a versão recebida por determinados clientes.
  • Utilize o bloqueio de atualização para impedir que uma empresa receba versões novas automaticamente.
  • Adicione e mantenha atualizados os campos modelo e nome nas chamadas do PDV.

• Dicas de uso.

  • Antes de uma grande atualização, planeje:
  • Quais empresas receberão a nova versão imediatamente.
  • Quais permanecerão bloqueadas.
  • Quais utilizarão versão específica (beta ou retroativa).
  • Use a integração via MQTT para notificar PDVs sobre novas versões e reduzir consultas repetitivas à API.

• Recomendações gerais sobre o processo.

  • Documente internamente quais regras estão ativas por empresa e qual o motivo de cada configuração.
  • Mantenha as URLs de download sempre acessíveis e compatíveis com o ambiente dos PDVs (sistema operacional, tipo de terminal, etc.).
  • Em caso de dúvida sobre parâmetros, obrigatoriedade de campos ou formatos de chamada, consulte a documentação oficial disponível no ERP.

• Benefícios de seguir corretamente o procedimento.

  • Maior controle sobre qual versão cada empresa/PDV utiliza.
  • Redução de problemas de compatibilidade, pois é possível bloquear ou direcionar versões conforme necessidade.
  • Facilidade para realizar atualizações em massa e acompanhar a adoção de novas versões.
  • Melhora na estabilidade operacional do parque de PDVs, com menor risco de atualizações indevidas ou mal planejadas.