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.

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 →
• 

• ✅ 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.

Pontos de melhoria - Solução 1

• 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:
  • 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 as informações referentes a versões de forma clara
  • 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 →
• 

• ✅ 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
      • 

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:

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

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.

• ✅ 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

Aqui, a documentação explica como os campos da API interagem com o produto.

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