Histórico da Página

...

• ✅ 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.
  • ✔ 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.
  • ✖ Estrutura pré-definida com base na documentação do PDV - Uma documentação pensada no negócio em si ao invés de API
• Modelo 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

...

• Necessidade de atrelar essa doc na documentação do PDV para ter de referência
• Melhorar algumas informações em ordem de prioridade
• Ajustes no modelo da doc das API's
  • Adicionar campos do PDV?
  • Adicionar as informações referentes a v3 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

1️⃣ Exemplo 1: Apenas os dados da API

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

✅ Vantagens:

✔ 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:

✖ 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:

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

❌ Desvantagens:

✖ 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