Diretrizes para Manuais de Implantação

Estas diretrizesPúblico-alvo:

têm

• Usuários técnicos (analistas, gerentes de TI, implantadores)

• Profissionais que configuram, ativam e operam a integração

• Podem ou não ter conhecimento técnico aprofundado

---

 

Objetivo

• Explicar como finalidadeativar, (propósito)configurar padronizare utilizar a criaçãintegração

• Fornecer uma visão clara dos benefícios, passos e apré-requisitos

  revisão
de
• documentos

  Instruir técnicossem delinguagem integraçãotécnica eexcessiva

  implementação
de

sistemas.

 O

objetivo

---

é

 garantir

que

Estrutura a documentação seja clara, precisa e útil para desenvolvedores, analistas e parceiros técnicos.

Recomendada

1. LinguagemCapa Direta+ e Técnica (Contextualizada)Título

   • Objetivo: Utilizar

     Exemplo: termos técnicosManual 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çãImplantação de– interpretação. Evite linguagem excessivamente coloquial ou formal em excesso.
   • Exemplo: "A integraçãIntegração automatizadaILLI se+ dá via API, onde a ECOS coleta as informações do Ilimitar."
   F360

2. FocoAdicione 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ãversão e paginação,data parase obter informações de vendas realizadas com cartão."

3. Passos Detalhados para Configuraçãonecessário

   • 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çã📍 Visão Explícita de Parâmetros e CredenciaisGeral

   • Objetivo: Informar

     Descreva quais dados são necessários paraque a autenticaçãintegração efaz

     para as requisições.
   • Aplicação:

     Liste os parâmetrosprincipais de entradabenefícios (ex: CNPJ, data de emissãautomatização, paginaçãoeconomia, )visibilidade)

     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)Pré-requisitos

   • Objetivo: Orientar

     Listar sobrerecursos, comopermissões, ativar,bibliotecas desativare oucredenciais controlarnecessárias

     o acesso à integração.
   • Aplicação: Descreva os métodos para revogar ou gerenciar o acesso (ex: "gerar um novo PIN, redefinir a chave

     Ex: API ouKey, desativarCNPJ ocadastrado, usuáriobiblioteca noinstalada

     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🧩 deEstrutura Entregasda e Limitações/EscopoIntegração

   • Objetivo: Definir

     Se claramentepossível, oinclua queum adiagrama integraçãosimples faz(push/pull, sincronização)

   • Mostre quem envia e oquem querecebe

     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: "Apenas informações de vendas por cartão são compartilhadas."

7. Pré-requisitos⚙️ Etapas de Instalação e Dependências TécnicasConfiguração

   • Objetivo: Listar todos os requisitos técnicos para que

     Passo a implementaçãpasso com numeração sejaclara

     bem-sucedida.
   • Aplicação: Inclua

     Destaque mençõesbotões, a bibliotecas necessárias ("biblioteca ativa" ), compatibilidade com APIs RESTtelas e JSON,URLs equando formatosnecessário

     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🧾 eDados Benefício Final (Contexto para o Implementador)Sincronizados

   • Tabela simples com os tipos de dados envolvidos

   • Ex: valor bruto, data da venda, bandeira, taxa

9. Objetivo🔁 Fluxo de Operação:

   Mostrar

   • Descrever a rotina de funcionamento: o valorque daacontece implementaçãoe paraquando

   • Ex: “a cada hora o negócio,sistema motivandobusca novas vendas”

10. 🧠 Dicas e Boas Práticas

    • Ex: "Não envie o implementadormesmo acupom entenderduas vezes", "Verifique o impactostatus dona seuplataforma trabalho.X"

11. Aplicação👥 Equipe Técnica Envolvida:

    Conecte
    as
    • funcionalidades

      Nome técnicas+ aos benefícios financeiros e operacionais (ex: "automatizar e centralizar a conciliaçãopapel de vendas",cada "identificarresponsável

      divergências
    nas
    taxas aplicadas e nos valores recebidos" ).

12. Exemplo📎 Links Úteis:

    "A
    integraçã

    • Documentação entretécnica, oAPIs, PDVapresentações ILLIcomerciais

      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.

 

---

 

Estilo e Linguagem

• Evite jargões técnicos desnecessários

• Use frases diretas e verbos no imperativo:

  • ✅ "Acesse o painel"

  • ❌ "Caso deseje acessar o painel, clique se quiser"

• Use bullet points e tabelas para clareza

• Destaque termos técnicos entre backticks ou em negrito