Histórico da Página
Índice
Índice
1. Objetivo
Este documento tem como objetivo oferecer uma descrição abrangente das regras de negócios incorporadas no TOTVS Varejo PDV Omni. Além disso, apresentar de maneira detalhada as etapas requeridas para realizar a integração entre o sistema de ERP e o PDV Omni. Aqui, você encontrará informações essenciais para compreender e implementar de forma eficaz a integração entre esses os sistemas, assegurando uma integração fluida e eficiente.
2. TOTVS Varejo PDV Omni
O TOTVS Varejo PDV Omni foi desenvolvido com as melhores práticas de mercado, incorporando inovação tecnológica e experiência de usuário. Sua interface amigável foi cuidadosamente projetada para simplificar o processo de venda, proporcionando não apenas eficiência operacional, mas também uma experiência agradável para os usuários. Por meio da configuração flexível de seu modo de operação, o PDV Omni oferece a versatilidade necessária para se adaptar às necessidades específicas do varejo. É possível definir se o sistema atuará no modo de checkout tradicional, gestão de pedidos de venda ou self checkout. Por meio de sua solução multiplaforma, o PDV Omni possibilita a utilização em sistemas operacionais Windows e Android. Essa versatilidade amplia as opções dos usuários, permitindo uma experiência integrada e eficaz em diferentes ambientes operacionais.
A seguir, apresentamos uma descrição detalhada das regras de negócios implementadas no PDV Omni, proporcionando uma compreensão clara de seu funcionamento e possibilitando uma integração fluida e eficiente.
| Page Tree | ||
|---|---|---|
|
EM CONSTRUÇÃO VALIDAR COM PAULO
3. Integração entre o ERP e PDVSync
O PDVSync é a camada responsável por orquestrar as operações de sincronização de dados entre o TOTVS Varejo PDV Omni e as suas respectivas retaguardas/ERPs.
Toda comunicação entre a retaguarda/ERP e o TOTVS Varejo PDV Omni será executada e orquestrada pelo PDVSync.
O PDVSync é composto por dois componentes principais:
- O PDVSync Server: Conjunto de APIs, serviços e bases de dados hospedados em nuvem pública responsáveis pela execução, orquestração e controle das sincronizações entre PDVs e retaguardas/ERPs e vice-versa.
- PDVSync Client: Serviço instalado no pacote do TOTVS Varejo PDV Omni que será responsável por fazer a comunicação entre o PDV e o PDVSync Server, conforme ilustração a seguir:
4. Fluxo de integração entre o ERP e PDVSync
Exemplo de Fluxo de chamadas de API´s com Abertura de lote, Fechamento de Lote e Solicitação de Retorno do Status do Lote Enviado.
- Devemos Abrir um Lote
- Esta abertura deve ocorrer antes do envio de um lote de informações para o PDVSync é neste momento que informamos para o PDVSync quais informações estarão no lote de dados enviados. Para o exemplo estaremos enviando as informações de "compartilhamentos" e "lojas" e no final estaremos informando o PDVSync que encerramos o envio de informações.
- /api/retaguarda/inquilinolotesexternos → POST Fazemos a abertura do Lote
- /api/retaguarda/compartilhamentos → POST Enviamos os dados da API de Compartilhamentos
- /api/retaguarda/lojas → POST Enviamos os dados da API de Loja
- /api/retaguarda/inquilinolotesexternos/{idInquilino}/{lote} → PUT Fazemos o encerramento do Lote
- Após o encerramento do Lote de envio de informações, poderemos solicitar informações sobre o processamento e validação deste lote de informação.
- /api/retaguarda/LoteExternoRetornos/{idInquilino}/{loteOrigem} → GET Nesta chamada pedimos a informação para o PDVSync sobre um determinado lote que ja foi encerrado.
OBS: Todos Schemas e Retornos disponíveis estão no Swagger.
5. Conceitos de ID Inquilino / ID Retaguarda / ID Proprietário
IDInquilino : OMXKpmP8hVjbqE
Código que identifica toda uma estrutura de Redes, Franquias, Centrais, Lojas e todos os dados enviados e recebidos no PDVSync dentro do ambiente SaaS.
Hoje este código é fornecido pela equipe de produto no início dos trabalhos para se conectar com o PDVSync.
IDRetaguarda :
Código que identifica todas as informações enviadas para a PDVSync, em todas as entidades seus registros possuem um IDRetaguarda no ERP/Retaguarda.
Este código é de controle do ERP/Retaguarda e deve ser único para um registro de informação (tabela) de um IDInquilino. O ID Retaguarda é o código comum entre o ERP/Retaguarda e o PDVSync, todas os registros tem a informação de ID Retaguarda.
Exemplos:
Produto, o ID Retaguarda identifica o produto no ERP/Retaguarda.
Cliente, o ID Retaguarda identifica o cliente no ERP/Retaguarda.
Loja, o ID Retaguarda identifica a loja no ERP/Retaguarda.
IDProprietário :
Código que identifica o proprietário da informação enviada para PDVSync.
Este código determina na estrutura da “Compartilhamento”, todas as lojas abaixo do ID Proprietário que deverão receber os dados enviados para o PDVSync.
Exemplo (01) de uma Estrutura de Rede ou Franquia com Centrais e Lojas.
No exemplo abaixo temos uma estrutura com o ID Inquilino = OAKLMImP8hVjbqE e com ID Retaguarda da (loja, central ou rede) e ID Proprietário sendo o mesmo código para o conjunto de lojas e Rede e centrais e seus próprios nomes são os códigos e lembrando que podem ser qualquer informação do ERP/Retaguarda (nome, código, CNPJ).
Lembrando que o ID Retaguarda é determinado pelo ERP/Retaguarda e tem que ser único para uma loja, central e Rede/Franqueadora dentro da estrutura utilizada em um ID Inquilino.
Exemplo (02) de uma Estrutura de Rede ou Franquia com Lojas.
No exemplo abaixo temos uma estrutura com o ID Inquilino = OAKLMImP8hVjbqE e o ID Retaguarda da (loja, central ou rede)do conjunto de lojas e Rede são seus próprios nomes e podem ser qualquer informação do ERP/Retaguarda (nome, código, CNPJ).
Lembrando que o ID Retaguarda é determinado pelo ERP/Retaguarda e tem que ser único para uma loja, central e Rede/Franqueadora dentro da estrutura utilizada em um ID Inquilino.
6. Domínios Microsserviços
Para o PDVSync foram definidos microsserviços independentes, levando em consideração a utilização e afinidade das informações trafegadas e armazenadas.
Os microsserviços foram divididos em:
7. Pré-requisitos
Pre-Requisitos para instalação do Client:
- PDVSync Omni instalado.
- Configuração de variáveis de ambiente DOTNET_ENVIRONMENT e ASPNETCORE_ENVIRONMENT. Elas servem para definir qual é o ambiente para o qual o Client irá apontar (Produção = Production, Homologação = Quality, ou Desenvolvimento = Development):
- Node.Js - Fazer o download do instalador do Node.Js em https://nodejs.org/en/download/. Instalar a versão 16.0 ou superior. Seguir os passos da instalação até a conclusão.
- .NET - Fazer o download do instalador do .NET em https://dotnet.microsoft.com/en-us/download. Instalar a versão 6.0. Seguir os passos da instalação até a conclusão.
- Conhecimento básico da ferramenta do Postman.
- Solicitar para o suporte do Winthor via ticket:
- Credenciais para viabilizar as criações dos dados iniciais do PDVSync. Conforme template:
- Nome do cliente
- CNPJ
- E-mail administrativo para cadastro do tenant
- Serviços clients do PDVSync para a instalação na maquina do PDV.
- Credenciais para viabilizar as criações dos dados iniciais do PDVSync. Conforme template:
8. Instalação/Configuração
Este documento tem por objetivo orientar a instalação e configuração do PDVSync. Esse processo deve ser realizado em dois ambientes Server e Client:
- Server
Onde deverá conter as informações de loja, inquilino, parâmetros, etc.
Para realizar as configurações para a utilização do PDV Sync no PDV Omni, é necessário realizar os cadastros abaixo através das APIs de Parâmetros.
O passo a passo do Postman se encontra no Google Drive no caminho: https://drive.google.com/drive/folders/1KriEZNs0ofg2uBF8u3TLniozko3IA063 (IMPORTANTE: caso não tenha acesso a esse diretório, solicitar o acesso ao time de Integração)
Lá se encontra o arquivo com as Collections montadas para a configuração e as variáveis para a utilização da criação de parâmetros.
1º - Criação do Inquilino
Para a criação do inquilino, utilizar o request 01. Criar Inquilino, informar os valores de acordo com as informações do cliente, realizar a autenticação e em seguida realizar o POST.
Após a criação, utilizar o valor do campo IdInquilino na variável para a configuração dos próximos passos.
2º - Criação dos Parâmetros Controle
Para a criação dos parâmetros do controle, basta apenas realizar a autenticação e realizar o POST.
3º - Criação dos Parâmetros Comercial
Para a criação dos parâmetros comerciais, basta apenas realizar a autenticação e realizar o POST.
4º - Criação do Parâmetro para a subida de Clientes
Para a criação do parâmetro de subida de cliente, basta apenas realizar a autenticação e realizar o POST.
Obs.: Para realizar esses procedimentos nos ambientes de desenvolvimento e homologação, seguir os mesmos passos acima, mas utilizar sua respectiva pasta (Passo a Passo - Homologação e Passo a Passo - Desenvolvimento).
Os passos a seguir já estão contemplados nos passos descritos anteriormente. Seguir a partir do passo 3 e ignorar o passo 9.
1° - Criação Inquilino
O inquilino é criado pela equipe do PDVSync pelo email: [email protected], com as seguintes informações:
- Nome Fantasia da Empresa
- CNPJ da Empresa
Será retornado o IdInquilino e o token authorization para inclusão no pdvsync e nas api's dos passos seguintes.
2º - Cadastrar os parâmetros, conforme exemplo:
Incluir Authorization OAuth2.0 conforme retornado no email.
endpoint: https://pdvsync.varejo.totvs.com.br/controle/api/pdvsyncserver/parametros
Post
[{
"idInquilino": "IdDoInquilino01-01", /*O código do IdInquilino conforme retornado no email.*/
"tipoProcesso": 1,/* OnLine = 0, Descida = 1, Subida = 2*/
"quantidadeRegistros": 1000,
"tempoChamada": 2000,
"tempoExpurgoLogs": 365,
"tipoDado": {
"codigoTipo": 1,
"descricaoTipo": "Loja",
"tipoUtilizador": 0,/*ClienteDown = 0, Server = 1, ClienteUp = 2, ClienteOnLine = 3 */
"tipoProcesso": 0 /*Criacao = 0, Atualizacao = 1, Interno = 2*/
}
}]
Lista de Parâmetros:
...
codigoTipo
...
descricaoTipo
...
tipoProcesso
...
3º - Abrir Lote com Parâmetro 01 - Loja
Incluir Authorization OAuth2.0 conforme retornado no email.
endpoint: https://pdvsync.varejo.totvs.com.br/controle/api/retaguarda/inquilinolotesexternos
...
Response:
{
"success": true,
"message": "",
"data": {
"loteOrigem": "20221004175001554",
"mensagem": null,
"status": 0,
"tipoLote": [
6
],
"id": "DLoi3SX5HDoPOcDlyf0m",
"idInquilino": "",
"dataAtualizacao": "2022-10-04T17:50:01.6441804Z",
"dataCadastro": "2022-10-04T17:50:01.6442468Z",
"_expandables": []
}
}
4º - Cadastro de uma Loja
**Os dados de cadastros devem ser enviados nas propriedades do json abaixo.
endpoint: https://pdvsync-core-dadosbasicos-prd-q6yz66olca-rj.a.run.app/api/retaguarda/lojas
Post
[
{
"razaoSocial": " ",
"nomeFantasia": " ",
"cnpj": " ", /*obrigatório e valido - 14 caracteres*/
"inscricaoEstadual": " ", /*obrigatório - 2 e 14 caracteres*/
"inscricaoMunicipal": " ", /*obrigatório - até 15 caracteres*/
"endereco": " ",
"numero": " ",
"complemento": " ",
"bairro": " ",
"cidade": " ",
"estado": " ",
"siglaUf": " ",
"codigoUFIBGE": " ", /*obrigatório - 2 caracteres*/
"codigoMunicipioIbge": " ", /*obrigatório - 7 caracteres*/
"cep": "", /*obrigatorio*/
"telefone": "", /*obrigatório - 6 e 14 caracteres*/
"codigoIdentificacaoLoja": "",
"modeloFiscal": 0,
"regimeTributario": 1,
"rede": "", /*obrigatório*/
"numeroLoja": "0",
"idRetaguardaRede": "",
"codigoMaster": " ",
"nomeMaster": " ",
"situacao": 1,
"idInquilino": " ", /*Gerado no passo 1*/
"idRetaguarda": "3 ", /*código da loja na retaguarda*/
"idProprietario": " ", /*compartilhamento da loja*/
"loteOrigem": " " /*Gerado no passo 3*/
}
]
5º - Fechar lote de loja
metodo: PUT
{idInquilino} - Gerado no passo 01
{loteOrigem} - Gerado no passo 03
6º - Abrir Lote com Parâmetro 06 - Compartilhamento
Incluir Authorization OAuth2.0 conforme retornado no email.
endpoint: https://pdvsync.varejo.totvs.com.br/controle/api/retaguarda/inquilinolotesexternos
...
Response:
{
"success": true,
"message": "",
"data": {
"loteOrigem": "20221004175001554",
"mensagem": null,
"status": 0,
"tipoLote": [
6
],
"id": "DLoi3SX5HDoPOcDlyf0m",
"idInquilino": "",
"dataAtualizacao": "2022-10-04T17:50:01.6441804Z",
"dataCadastro": "2022-10-04T17:50:01.6442468Z",
"_expandables": []
}
}
7º - Criar Compartilhamento
endpoint: https://pdvsync-core-controle-prd-q6yz66olca-rj.a.run.app/api/retaguarda/compartilhamentos
Post
[
{
"IdRetaguardaLoja": "",
"IdRetaguarda": "32796d0b-8399-490e-b972-1db212c514fa",
"IdProprietario": "32796d0b-8399-490e-b972-1db212c514fa",
"IdInquilino": "",
"NomeCompartilhamento": "PDV Master",
"Nivel": 0,
"IdRetaguardaPai": "",
"loteOrigem": "20221004175001554"
},
{
"IdRetaguardaLoja": "3f054f05-ee67-407b-935d-9db0fc5e7c58",
"IdRetaguarda": "3f054f05-ee67-407b-935d-9db0fc5e7c58",
"IdProprietario": "3f054f05-ee67-407b-935d-9db0fc5e7c58",
"IdInquilino": "",
"NomeCompartilhamento": "PDV Loja",
"Nivel": 1,
"IdRetaguardaPai": "",
"loteOrigem": "20221004175001554"
}
]
...
{
"success": true,
"message": "compartilhamento inserido com sucesso: [{\"IdRetaguarda\":\"32796d0b-8399-490e-b972-1db212c514fa\",\"IdProprietario\":\"32796d0b-8399-490e-b972-1db212c514fa\",\"NomeCompartilhamento\":\"PDV Master\",\"Nivel\":0,\"IdRetaguardaPai\":\"\",\"LoteOrigem\":\"20221004175001554\",\"Lote\":null,\"IdRetaguardaLoja\":\"\",\"Id\":null,\"IdInquilino\":\"\",\"DataAtualizacao\":\"0001-01-01T00:00:00\",\"DataCadastro\":\"0001-01-01T00:00:00\",\"_expandables\":[]},{\"IdRetaguarda\":\"3f054f05-ee67-407b-935d-9db0fc5e7c58\",\"IdProprietario\":\"3f054f05-ee67-407b-935d-9db0fc5e7c58\",\"NomeCompartilhamento\":\"PDV Loja\",\"Nivel\":1,\"IdRetaguardaPai\":\"32796d0b-8399-490e-b972-1db212c514fa\",\"LoteOrigem\":\"20221004175001554\",\"Lote\":null,\"IdRetaguardaLoja\":\"3f054f05-ee67-407b-935d-9db0fc5e7c58\",\"Id\":null,\"IdInquilino\":\"\",\"DataAtualizacao\":\"0001-01-01T00:00:00\",\"DataCadastro\":\"0001-01-01T00:00:00\",\"_expandables\":[]}].",
"data": null
}
8º - Fechar o Lote
metodo: PUT
{idInquilino} - Gerado no passo 01
{loteOrigem} Gerado no passo anterior
9º - Cadastrar os parâmetros comerciais para a consulta de operações de vendas e caixa
URL: https://pdvsync.varejo.totvs.com.br/comercial/api/pdvsyncserver/parametros
Post
[
{
"idInquilino": "", /*Gerado no passo 01*/
"dataAtualizacao": "2022-10-07T18:59:54.530Z",
"dataCadastro": "2022-10-07T18:59:54.530Z",
"codigo": 1,
"tipo": 1,
"valor": "10"
},
{
"idInquilino": "", /*Gerado no passo 01*/
"dataAtualizacao": "2022-10-07T18:59:54.530Z",
"dataCadastro": "2022-10-07T18:59:54.530Z",
"codigo": 2,
"tipo": 2,
"valor": "10"
},
{
"idInquilino": "", /*Gerado no passo 01*/
"dataAtualizacao": "2022-10-07T18:59:54.530Z",
"dataCadastro": "2022-10-07T18:59:54.530Z",
"codigo": 3,
"tipo": 3,
"valor": "10"
},
{
"idInquilino": "", /*Gerado no passo 01*/
"dataAtualizacao": "2022-10-07T18:59:54.530Z",
"dataCadastro": "2022-10-07T18:59:54.530Z",
"codigo": 4,
"tipo": 4,
"valor": "10"
},
{
"idInquilino": "", /*Gerado no passo 01*/
"dataAtualizacao": "2022-10-07T18:59:54.530Z",
"dataCadastro": "2022-10-07T18:59:54.530Z",
"codigo": 5,
"tipo": 0,
"valor": "https://pdvsync-core-fila-prd-q6yz66olca-rj.a.run.app/api/stub/historicovenda"
}
]
10º Baixar Serviços Clients
...
- API – Responsável pela comunicação entre o PDV e os Serviços de UP e Down.
- Controle – Responsável por informar aos Serviços de DOWN que existe informações novas para serem baixadas no PDV.
- Up – Serviço responsável pela subida de informações do PDV para o Server.
- Down – Serviço responsável pela baixa de informações do Server para o PDV.
2. Integração com Protheus - SmartHub
Consulte : TOTVS Varejo PDV OMNI
falar sobre ponto de entrada
3. Integração com Winthor
Consulte : Integração WinThor TOTVS Varejo PDV Omni - Documento de Implantação
Instalação dos Serviços UP, DOWN, CONTROLE e API:
- Criar a pasta C:\PDVSync e executar a instalação dos serviços disponibilizados pelo time do suporte.
- Acessar a pasta C:\PDVSync descompactar o arquivo baixado acima e executar o arquivo "servicos.bat" como Administrador.
- Após os passos acima os serviços PDVSync.Client.Api.WebApi, PDVSync.Client.Servico.Up, PDVSync.Client.Servico.Down e PDVSync.Client.Servico.Controle serão instalados e iniciados.
Desinstalação dos Serviços UP, DOWN, CONTROLE e API:
- Para desinstalar os serviços acima basta acessar a pasta C:\PDVSync executar o arquivo “servicos-delete.bat”.
18. Documentação APIs
19. Criação dos Jobs para Expurgo das tabelas log_pdvsync e histórico_integracao do PDV Omni
1º - Pré-requisito
Alterar o arquivo pg_hba.conf localizado no diretório C:\Program Files\PostgreSQL\15\data para que o Agendador de Tarefas tenha acesso a realizar os comandos na máquina local.
Alterar as linhas selecionadas abaixo para “trust”
2º - Criação da tarefa para o expurgo da tabela log_pdvsync
Abrir o Agendador de Tarefas do Windows
Abrir a ramificação Biblioteca do Agendador de Tarefas e criar uma nova pasta com o nome “PDV Omni”
Dentro da pasta PDV Omni criar uma nova tarefa básica para o expurgo da tabela log_pdvsync
No disparador manter como diariamente
No campo de data e hora, colocar a data atual e no horário informar as 00:00:00. E para repetir, colocar a cada 1 dia.
Ação executada deixar a primeira opção “Iniciar um programa”
No próximo passo selecionar o programa psql.exe localizado no diretório C:\Program Files\PostgreSQL\15\bin
E no campo Adicione Argumentos, informar o seguinte texto:
-U postgres -d TotvsPDV -w -c "delete from log_pdvsync lp where date_part('day', now() - lp.data_criacao) > 7"
Concluir o agendamento e pronto. O agendador de tarefas vai rodar o expurgo todo dia no horário planejado. Mas antes deve se configurar o usuário de execução. Na tarefa agendada ir em Propriedades
Na Opções de segurança, selecionar a opção “Executar estando o usuário conectado ou não”
Clique em Ok, e caso ele peça a senha do usuário, informar a senha do usuário logado no Windows.
Importante: recomendado deixar a máquina ligada para que a tarefa seja executada.
3º - Criação da tarefa para o expurgo da tabela histórico_integracao
Com o Agendador de Tarefas abertos no passo anterior, dentro da pasta PDV Omni, criar uma nova tarefa básica
Criar uma nova Tarefa Básica
Manter o disparador como “Diariamente”
No campo de data e hora, colocar a data atual e no horário informar as 00:00:00. E para repetir, colocar a cada 1 dia.
Ação executada deixar a primeira opção “Iniciar um programa”
No próximo passo selecionar o programa psql.exe localizado no diretório C:\Program Files\PostgreSQL\15\bin
E no campo Adicione Argumentos, informar o seguinte texto:
-U postgres -d TotvsPDV -w -c "delete from historico_integracao hi where date_part('day', now() - hi.data_atualizacao) > 7"
Concluir o agendamento e pronto. O agendador de tarefas vai rodar o expurgo todo dia no horário planejado. Mas antes deve se configurar o usuário de execução. Na tarefa agendada ir em Propriedades
| Informações | ||
|---|---|---|
| ||
Para maiores informações sobre a funcionalidade de desconto, consulte Como aplicar desconto no PDV Omni |
Na Opções de segurança, selecionar a opção “Executar estando o usuário conectado ou não”
Clique em Ok, e caso ele peça a senha do usuário, informar a senha do usuário logado no Windows.
...
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas