Índice
maxLevel 2

Objetivo

Propor e definir um padrão de documentação para o PDVSync, considerando integração com o PDV, organização clara dos dados e alinhamento entre os times envolvidos.

Descrição

Atualmente, a documentação do PDVSync apresenta problemas de fluidez e clareza, especialmente em relação às diferentes versões existentes e à integração com tabelas do PDV. Por vezes, dados relacionados a tabelas distintas do PDV são tratados na mesma API do Sync, o que resulta em descentralização de informações e dificuldade de uso.

...

• APIs Online:
  • Fluxos de dados em tempo real entre o PDV e a retaguarda.
• Baixa de Dados:
  • Processos de transferência de informações da retaguarda para o PDV.
• Envio de Dados:
  • Processos de envio de informações do PDV para a retaguarda.
• As etapas incluem:
  • Criação dos modelos
    • Desenvolver propostas claras e organizadas para documentar os três fluxos mencionados, integrando informações relacionadas às tabelas do PDV de forma centralizada.
  • Comparação com a documentação atual do Sync
    • Avaliar os modelos propostos em relação à documentação existente, identificando melhorias necessárias.
  • Alinhamento entre times
    • Compartilhar os modelos com os times PDV e Sync, promovendo uma discussão colaborativa para chegar a um consenso sobre o padrão mais eficiente.
  • Unificação ou independência
    • Decidir, em conjunto, se a documentação do Sync será unificada com a documentação do PDV ou seguirá um modelo independente.

...

Em discussões identificamos até o momento duas soluções de como resolver este problema, conforme descritas abaixo.

Soluções

Solução 1 - Documentação separada: PDVSync 

• Primeira versão criada de documentação PDVSync: Microserviços - TOTVS Varejo PDV Omni - TDN . Nesta documentação como pode ser vista é focada apenas no PDVSync abordando os seguintes pontos:
  • Como implementar a integração
  • O que é e detalhes dos Microsserviços
  • APIs separadas por microsserviços
  • APIs com detalhes de seus métodos (POST, GET, PUT, DELETE e PATCH)
  • Payloads detalhados com seus tipos (Tabelas com tipos de campos, limites de caracteres, versões, etc...)
  • Detalhe do retorno esperado para sucesso (200 ok) e erro (400 Bad Request) 
  • Englobando o processo offline e online
  • Troubleshooting

• Modelo 1 →
• Image Added

Critérios de Aceite

• Modelos de documentação elaborados para os três fluxos principais:
  • APIs Online.
  • Baixa de Dados.
  • Envio de Dados.
• Comparação estruturada entre os novos modelos e a documentação atual do Sync, com registro das melhorias propostas.
• Reunião realizada com os times PDV e Sync, com feedback documentado e consenso sobre o melhor modelo.
• Definição clara sobre unificação ou independência da documentação do Sync em relação ao PDV.
• Entrega de um documento consolidado com o padrão aprovado e plano de implementação.

...

• ✅ Vantagens:
  • ✔ Liberdade para estruturação da documentação - Sem depender de como a documentação do PDV esta disposta.
  • ✔ Maior visibilidade para desenvolvedores externos – Facilita o acesso para parceiros, startups e integradores focado na integração.
  • ✔ Facilidade de versionamento – É mais fácil gerenciar e documentar versões diferentes da API sem interferir no produto.
• ❌ Desvantagens:
  • ✖ Pode gerar desconexão do produto – Se não houver sincronização eficiente, a documentação pode ficar desatualizada em relação ao produto.
  • ✖ Exige manutenção separada – A equipe pode precisar de um esforço adicional para manter a documentação alinhada com as mudanças do produto.
  Modelo

Pontos de melhoria - Solução 1

...

• ✔ Nessa documentação estamos conseguimos separar os envios conforme os micros serviços
• ✔ Demonstrar estrutura do PDVSync e seu funcionamento
• ✔ Processos
  • Descida de dados
  • Subida de dados
  • Processo Online
  • Consultas específicas LojaLoteRetorno (GET)
  • Integração de nova Loja
  • Entre outros
• ✔ Troubleshooting
• ✔ Instalação do Sync

• Incluir referências de link da documentação do PDV, onde a integração pode ser utilizada. Isto auxilia ao desenvolvedor a identificar melhor a necessidade dos campos a serem utilizados e melhor entendimento da API. 
• Melhoria na estrutura de como está o layout da documentação atualmente:

  Pontos de Melhoria

  • Necessidade de atrelar essa doc na documentação do PDV para ter de referência
  • Melhorar algumas informações em ordem de prioridade
    • Precisamos realmente de tantas abas na interface principal do produto?
    • Dificuldade de instruir o usuario com tantas informações logo de cara
      • Baixa
      • Envio
      • Online
  • Ajustes no modelo da doc das API's
    
    • Adicionar campos do PDV?Adicionar as informações referentes a v3 versões de forma clara
    • centralizar Centralizar todos os tipos de Dados existentes em apenas um lugar
    • Melhor descrição das API's, para que serve e a sua relação entre elas
      • Exemplo: ProcessoOnline com fluxos dependentes que não são claros NotaEntrada + NotaSaida

  ...

  
  

  Solução 2 - Unificando a documentação: PDVSync com PDV

  • Uma ideia de unificar as documentações, visando em facilitar aos desenvolvedores externos uma consulta unica, segue exemplo atual de uma documentação unificada: Produto.
  • A documentação é separada nas seguintes abas:
    • Descrição dos campos e regras:  Exclusiva para detalhes de campos e regras referente as tabelas do banco PDV.
    • Como integrar: Sessão PDVSync, contém os seguintes dados referente a API especifica:
      • Métodos POST ou GET (Até o momento mais ou unicamente utilizados no PDV)
      • Payloads detalhados com seus tipos (Tabelas com tipos de campos, limites de caracteres, versões, etc...)
      • Detalhe do retorno esperado para sucesso (200 ok) e erro (400 Bad Request) 

  
  

  • Modelo 2 →
  • Image Added

  
  

  • ✅ Vantagens:
    
    • ✔ Experiência unificada e facilidade no entendimento de como os dados serão integrados no PDV– Usuários do produto encontram a documentação no mesmo local, sem precisar buscar em fontes externas.
    • ✔ Maior alinhamento com a evolução do produto – Mudanças na API acompanham "automaticamente" as mudanças no produto.
    • ✔ Facilidade de acesso para clientes – Se a API for utilizada por clientes do próprio produto, o acesso integrado simplifica a adoção.
    • ✔ Melhor suporte e integração – Pode estar conectada a fóruns, FAQs e suporte técnico dentro do mesmo ecossistema.

  
  

  • ❌ Desvantagens:
    • ✖ Pode dificultar a adoção por terceiros – Se a API for aberta, desenvolvedores externos podem ter dificuldade em encontrá-la.
    • ✖ Menos flexibilidade na organização da documentação – Pode ser difícil criar uma documentação modular e expansível dentro da estrutura do produto.
    • ✖ Risco de desatualização – Caso o foco esteja no produto principal, a documentação da API pode ficar desatualizada.
    • ✖ Estrutura pré-definida com base na documentação do PDV - Uma documentação pensada no negócio em si ao invés de API
      • Um exemplo nesse caso seria produto que é divido em varios itens na rotina do PDV, sendo que no envio do dado é apenas um payload
        • Image Added

  
  

  Pontos de melhoria - Solução 2

  • Estrutura separado pelos tipos de dados, sendo que o PDVSync é separado por microsserviços
  • Em cada tipo de dados existe uma quantidade enorme de informações do PDV na primeira aba + as informações da API, pode ser tornar confuso para o usuário
    • Necessidade de dar foco para a API e foco para o PDV quando o usuario for procurar informações especificas
  • Ausência de processo de instalação do Sync
  • Ausência de processo Troubleshooting
  • Fluxos de subida de forma separada
  • Em cada fluxo precisa adicionar a informação do microsserviço, pois atualmente temos apenas o endPoint o que pode se tornar confuso na hora de montar uma requisição
  • Estudo de como implementar o processo online

  
  

  Modelo da Doc de API geral 

  • Independente da escolha dos modelos 1 e 2, estes dados são essenciais
  • Toda documentação das API's subida, descida e online deve conter os seguintes dados:
  • Estrutura das pastas dentro da doc
    • MicrosServico
      •  ProcessoXPTO
        • GET/endpoint/api/pdvsyncserver/retaguarda/v2/processoonlinecredito
        • POST/endpoint/api/pdvsyncserver/retaguarda/v2/processoonlinecredito
    • Exemplo:Image Added

  
  

  O dadoXPTO deve poderá ter a seguintes informações:

  Deck of Cards
  id dk1
  Card label Como integrar Apenas nos casos que necessitam de parametros na requisição: Parametro Descrição Tipo Obrigatório Observação idInquilino Identificador do inquilino String Sim idRetaguardaLoja Identificador da loja da retaguarda String Sim cpfCnpj CPF / CNPJ String Sim Parâmetro do tipo Header ------------------------------------------------------------------------------------------------------------------------------ Retornos Este método é responsável pela criação de uma regra X Endpoint: /api/retaguarda/v3/dadosdinamicos/down/59/{versão} caso outras versoes estejam sendo utilizadas incluir v2 v1 Método: Post Autenticação: Bearer token Permissão: Retaguarda Microserviço: PDVSync.Core.Preco Este endpoint recebe uma lista de X, permitindo vários em uma mesma requisição. (Com base nas novas atividades melhorar a descrição, envia x dado para tal função) Aviso Para que a baixa da Y e X criado ocorra no PDV Omni é necessário realizar a abertura de um lote do tipo XXXX = YYYYY É necessário que o inquilino tenha o parametro XXXX - YYYY cadastrado no controle. Campo destinado a observações detalhes de atenção, pode variar de api para api Pré-requisitos: Preenchimento correto no METADATA do inquilino. Endpoint LimiteCredito: Exemplo.: /api/limitecreditodetalhe O parâmetros desta requisição são enviado no header, abaixo estão listados os parâmetros Deck of Cards id versoes2 Card label V3.1 Requisição Section Column width 50% Exemplo de body da requisição [     {         "dataHoraVigenciaFinal": "2021-06-21T14:43:18.665Z",         "dataHoraVigenciaInicial": "2021-06-21T14:43:18.665Z",         "idInquilino": "string",         "idProprietario": "string",         "idRetaguarda": "string",     } ] Column width 50% Definições dos campos do body Campo Tipo Descrição Obrigatório Observações idInquilino string Identificador do inquilino Sim idProprietario string Identificador do proprietário Sim idRetaguarda string Identificador do grupo na retaguarda Sim Tamanho máximo: 100 caracteres dataHoraVigenciaInicial datetime Data Inicial da vigência da regra Sim dataHoraVigenciaFinal datetime Data Final da vigência da regra Sim Retorno Deck of Cards id retornos Card label 200 - Ok Column width 50% Exemplo de body de retorno {     "data": null,     "errors": null,     "message": null,     "numberOfRecords": 8,     "success": true,     "totalTime": 2061 } Column width 50% Definições dos campos do retorno Campo Tipo Descrição data Objeto Retorno dos dados caso tenha errors Objeto Objeto contendo todos os erros encontrados. message String Descrição do erro numberOfRecords Int Número de arquivos processados success Bool Status da requisição totalTime Int Tempo total Card label 400 - Bad Request Column width 50% Exemplo de body de retorno {     "data": null,     "errors": {         "0": {             "IdRetaguarda": [                 ""             ]         }     },     "message": null,     "numberOfRecords": 9,     "success": false,     "totalTime": 4077 } Column width 50% Definições dos campos do retorno Campo Tipo Descrição data Objeto Retorno dos dados caso tenha errors Objeto Objeto contendo todos os erros encontrados. Cada propriedade desse objeto é o índice do grupo enviado que está com erro. message String Descrição do erro numberOfRecords Int Número de arquivos processados success Bool Status da requisição totalTime Int Tempo total

  1️⃣ Modelo da Doc da API 1: Apenas os dados da API

  Este formato foca exclusivamente nos campos da API, sem mencionar sua relação com o produto.

  Campo	Tipo	Obrigatório	Observações	Descrição
  id	int	Sim		Identificador único do usuário
  name	string	Sim		Nome do usuário
  email	string	Sim		Endereço de e-mail do usuário
  created_at	string	Não		Data de criação do usuário (ISO 8601)

  
  

  • ✅ Vantagens Modelo 1:
    • ✔ Mais objetiva e técnica – Evita informações desnecessárias para desenvolvedores que só precisam da API.
    • ✔ Fácil manutenção – Não precisa ser alterada caso a interface do produto mude.
    • ✔ Facilidade para integradores externos – Desenvolvedores que não usam o produto podem entender os dados sem precisar de contexto extra.
  • ❌ Desvantagens Modelo 1:
    • ✖ Desconexão com o produto – Quem usa o produto pode não saber como esses dados se refletem na interface.
    • ✖ Pouca usabilidade para equipes internas – Se um analista de suporte ou um gerente de produto precisar entender os dados da API, pode ter dificuldades.
      
      

  
  

  2️⃣ Modelo da Doc da API 2: Relacionando os dados da API com o produto

  ...

  Campo	Tipo	Obrigatório	Descrição	Observações	Onde aparece no produto (no nosso caso os campos do PDV)
  id	int	Sim	Identificador único do usuário		ID exibido na tela de detalhes do usuário
  name	string	Sim	Nome do usuário		Tabela: Nome - Campo - nome_usuario
  email	string	Sim	Endereço de e-mail do usuário		E-mail mostrado no perfil do usuário e nas notificações
  created_at	string	Não	Data de criação do usuário (ISO 8601)		Data de registro visível na aba "Histórico" do painel de administração

  
  

  ✅ Vantagens Modelo 2:

  • ✔ Maior clareza para usuários do produto – Ajuda a entender como os dados da API afetam a interface.
  • ✔ Melhor suporte para equipes internas – Suporte técnico, gerentes de produto e QA podem relacionar os dados da API com o que veem no sistema.
  • ✔ Facilita a integração com o front-end – Desenvolvedores que trabalham na interface do produto sabem exatamente onde cada campo é usado. (No nosso caso o banco de dados do PDV)
    
    

  ❌ Desvantagens Modelo 2:

  • ✖ Pode ficar mais complexa e extensa – Mais informações significam mais detalhes para manter e atualizar.
  • ✖ Maior chance de desatualização – Se o produto mudar, a documentação pode ficar obsoleta rapidamente.
  • ✖ Menos útil para integradores externos – Quem não usa o produto pode achar irrelevante a relação dos campos com a interface

  ...

  Solução 2 - Unificando a documentação do PDVSync

  • ✅ Vantagens:
    ✔ Experiência unificada – Usuários do produto encontram a documentação no mesmo local, sem precisar buscar em fontes externas.
  • ✔ Maior alinhamento com a evolução do produto – Mudanças na API acompanham "automaticamente" as mudanças no produto.
  • ✔ Facilidade de acesso para clientes – Se a API for utilizada por clientes do próprio produto, o acesso integrado simplifica a adoção.
  • ✔ Melhor suporte e integração – Pode estar conectada a fóruns, FAQs e suporte técnico dentro do mesmo ecossistema.
  ❌ Desvantagens:
  • ✖ Pode dificultar a adoção por terceiros – Se a API for aberta, desenvolvedores externos podem ter dificuldade em encontrá-la.
  • ✖ Menos flexibilidade na organização da documentação – Pode ser difícil criar uma documentação modular e expansível dentro da estrutura do produto.
  • ✖ Risco de desatualização – Caso o foco esteja no produto principal, a documentação da API pode ficar desatualizada.
  ✖ Estrutura pré-definida com base na documentação do PDV - Uma documentação pensada no negócio em si ao invés de API