Diretrizes para a Documentação de Implementação

AoEstas criardiretrizes outêm revisarcomo finalidade (propósito) padronizar a criação e a revisão de documentos técnicos de integração e implementação de sistemas. O objetivo é garantir que a documentação deseja implementação,clara, sigaprecisa estase diretrizesútil para garantirdesenvolvedores, clareza, precisãoanalistas e utilidadeparceiros para o implementador de sistemas:técnicos.

1. Linguagem Direta e Técnica (Contextualizada)

   • Objetivo: Utilizar termos técnicos de forma precisa, evitando ambiguidades e mantendo a linguagem concisa.
   • Aplicação: Empregue jargões técnicos relevantes (ex: API Key, endpoint, CSV, ERP, PDV) e explique-os brevemente se houver chance de variação de interpretação. Evite linguagem excessivamente coloquial ou formal em excesso.
   • Exemplo: "A integração automatizada se dá via API, onde a ECOS coleta as informações do Ilimitar."

2. Foco em Processos e Fluxos de Dados

   • Objetivo: Detalhar o caminho que os dados percorrem e as interações entre os sistemas.
   • Aplicação: Descreva claramente quem inicia a comunicação, quais dados são trocados, em que formato, e qual a frequência (ex: "consultas a cada 5 minutos ou de hora em hora" ).
   • Exemplo: "A ECOS realiza consultas ao endpoint do Ilimitar a cada 5 minutos ou de hora em hora, utilizando parâmetros como CNPJ, data de emissão e páginação, para obter informações de vendas realizadas com cartão."

3. Passos Detalhados para Configuração

   • Objetivo: Fornecer um guia claro e replicável para todas as etapas de configuração.
   • Aplicação: Apresente os passos de forma numerada e sequencial. Inclua ações específicas, cliques em botões, campos a preencher e valores esperados.
   • Exemplo:
     • "1. Gere a API Key do ILLI."
     • "2. Adicione a biblioteca na base do cliente."
     • "3. Insira a API Key para autenticação."

4. Identificação Explícita de Parâmetros e Credenciais

   • Objetivo: Informar quais dados são necessários para a autenticação e para as requisições.
   • Aplicação: Liste os parâmetros de entrada (ex: CNPJ, data de emissão, paginação ) e as credenciais (usuário, senha, API Key ) de forma clara.
   • Exemplo: "A ECOS utiliza um usuário e senha para acessar o endpoint 'get vendas'."

5. Gerenciamento da Integração (Controle de Acesso)

   • Objetivo: Orientar sobre como ativar, desativar ou controlar o acesso à integração.
   • Aplicação: Descreva os métodos para revogar ou gerenciar o acesso (ex: "gerar um novo PIN, redefinir a chave API ou desativar o usuário no Ilimitar" ).
   • Exemplo: "Para interromper a integração, basta gerar um novo PIN, redefinir a chave API ou desativar o usuário no Ilimitar, o que automaticamente revoga o acesso da ECOS."

6. Esclarecimento de Entregas e Limitações/Escopo

   • Objetivo: Definir claramente o que a integração faz e o que não faz, ou quais dados são compartilhados.
   • Aplicação: Especifique os tipos de dados que são transferidos (ex: "apenas informações de vendas por cartão são compartilhadas" ), e as funcionalidades que a integração abrange.
   • Exemplo: "Mauricio Francelino ressaltou que apenas informações de vendas por cartão são compartilhadas."

7. Pré-requisitos e Dependências Técnicas

   • Objetivo: Listar todos os requisitos técnicos para que a implementação seja bem-sucedida.
   • Aplicação: Inclua menções a bibliotecas necessárias ("biblioteca ativa" ), compatibilidade com APIs REST e JSON, e formatos de arquivo (CSV, OFX ).
   • Exemplo: "Para a integração automatizada, é necessário que a biblioteca esteja ativa e o CNPJ do cliente seja informado à ECOS, que já possui o endpoint do Ilimitar."

8. Relevância e Benefício Final (Contexto para o Implementador)

   • Objetivo: Mostrar o valor da implementação para o negócio, motivando o implementador a entender o impacto do seu trabalho.
   • Aplicação: Conecte as funcionalidades técnicas aos benefícios financeiros e operacionais (ex: "automatizar e centralizar a conciliação de vendas", "identificar divergências nas taxas aplicadas e nos valores recebidos" ).
   • Exemplo: "A integração entre o PDV ILLI e a plataforma Equals tem como objetivo principal automatizar e centralizar a conciliação de vendas, proporcionando aos usuários uma visão clara e completa de seus recebimentos.