Diretrizes para Manuais Técnicos de Desenvolvimento

Ao📌 criarPúblico-alvo:

• Desenvolvedores backend

• Equipes de integração

• Arquitetos de sistemas

---

 

Objetivo

• Fornecer informações claras e precisas para implementar ou revisarconsumir a documentaçAPI

• Detalhar endpoints, autenticaçãoo, parapayloads, o desenvolvedor, siga estas diretrizes para garantir clareza técnica, precisãorespostas e todosregras

  os
detalhes

necessários

 para

a

---

implementação:

 

Estrutura Recomendada

1. VisãoCapa Geral+ Técnica e ArquiteturalTítulo:

   • Propósito: Fornecer

     Exemplo: umManual entendimentoTécnico de– alto nível sobre a arquitetura da integraçIntegração, seus componentes e o fluxoILLI de+ dadosEquals principal.(API REST)

   • Aplicação: Inclua

     Incluir diagramas de fluxo de dados, mencione tecnologias envolvidas (REST, JSON, ESB, etc.) e o papel de cada sistema (PDV ILLI, Equals, Ilimitar).  Explique o papel do Ilimitar como fonte de dados e da ECOS como coletora.

   • Exemplo: "A integração se dá via API, onde a ECOS coleta informações do Ilimitar. O Ilimitar atua como a fonte primária de dados de vendas, enquanto a ECOS realiza a requisiçãversão e conciliaçãodata
     desses dados com adquirentes e bancos."

2. Endpoints🧩 eVisão MétodosTécnica Detalhados (API Reference)Geral:

   • Propósito: Fornecer todas as informações necessárias para que

     Explicação desenvolvedorrápida possada construirarquitetura

     e testar requisições.
   • Aplicação: Liste

     Ex: os"A endpoints disponíveis (ex: /getvendas), os métodos HTTP (GET, POST), os parâmetros de requisiçintegração (CNPJ,segue datamodelo depull, emissão,onde paginação),a plataforma eX exemplosconsome de payloads (corpos de requisição e resposta) em formato JSON ou XML, conforme aplicável.
   • Exemplo:
     • Endpoint: GET /api/vendas
     • Parâmetros de Consulta:
       • cnpj (string, obrigatório): CNPJ do cliente para filtragem de vendas.
       • dataEmissao (date, obrigatório): Datadados da emissãoAPI dasIlimitar."
         vendas.
       • pagina (integer, opcional): Número da página para paginação de resultados.

     • Exemplo🔐 Autenticação

       • Descrever método (API Key, OAuth, JWT etc.)

       • Exemplos de Respostacabeçalhos HTTP

     • 🌐 Endpoints Principais

       • Listagem com:

         • Método HTTP (JSON):GET, {"vendas":POST)

           [{"id":
         "...",
         • "valor":

           URL

           "...",
         "formaPagamento":
         • "cartao",

           Parâmetros ...}]}de query e body

         • Headers exigidos

     • Autenticaç📤 Exemplos de Requisição e AutorizaçãoResposta:

       • Propósito: Explicar

         Com comoJSON aindentado

         comunicação
       é
       • segura

         Diferenciar campos obrigatórios e comoopcionais

         o desenvolvedor deve se autenticar.
       • Aplicação: Detalhe os mecanismos de autenticação (ex: via API Key, usuário e senha),  e como obter e gerenciar essas credenciais. Inclua instruções para revogar acesso (gerar novo PIN, redefinir chave, desativar usuário).
       • Exemplo: "A autenticação é realizada via API Key associada a um usuário do sistema Ilimitar.  O usuário e senha são utilizados para acessar o endpoint 'get vendas'.  Para revogar o acesso da ECOS, basta gerar um novo PIN ou desativar o usuário no Ilimitar."

     • Modelagem🧠 Regras de Dados e CamposNegócio:

       • Propósito: Descrever

         Validações

         a estrutura dos dados que serão enviados e recebidos, garantindo a correta interpretação.
       • Aplicação: Para cada tipo

         Limites de dadoenvio

         (vendas,
       taxas,
       • recebimentos),

         Comportamento detalheesperado

         os
       campos
       • esperados (nome do campo, tipo

         Frequência de dado,chamadas

         formato, se é obrigatório/opcional). Explique a granularidade das informações (ex: vendas por cartão).
       • Exemplo: "O endpoint de vendas retorna informações detalhadas sobre transações de cartão, incluindo: valor bruto da venda, forma de pagamento (cartão de crédito, débito, Pix), data e hora da venda, número do comprovante, detalhes do cliente, informações sobre taxas e impostos."

     • 📊 Tratamento de Erros e Códigos de Status:

       • Propósito: Guiar

         Códigos oHTTP desenvolvedore sobreexplicações

       • Campos como lidartraceId, com falhas na comunicação e identificar problemas.

       • Aplicação: Liste os possíveis códigosmensagens de statusfallback
         HTTP (200 OK, 400 Bad Request, 401 Unauthorized, 500 Internal Server Error) e os respectivos corpos de erro que o sistema pode retornar, com mensagens claras.
       • Exemplo: "Em caso de autenticação falha, o sistema retornará um erro 401 Unauthorized com o corpo {"erro": "Chave API inválida"}."

     • 🔄 Frequência e Limites de RequisiçãoAgendamento:

       • Propósito: Informar

         Se ofor desenvolvedorpor sobreconsulta asperiódica, limitaçõesdetalhar deintervalos usoe dacomportamento

         API para evitar bloqueios ou sobrecarga do sistema.
       • Aplicação: Mencione

         Se afor frequência de requisições permitidapush (ex:webhook), "adescrever cada 5 minutos ou de hora em hora")assinatura e seretorno háesperado

         limites de dados por requisição ou por período.
       • Exemplo: "A ECOS realiza consultas ao endpoint do Ilimitar a cada 5 minutos ou de hora em hora para obter informações de vendas.  Limite de 20 dias por período em relatórios CSV."

     • Pré-requisitos🔧 TécnicosControle de Acesso e DependênciasRevogação:

       • Propósito: Listar

         Como todas as condições técnicas que precisam ser atendidas para a integração funcionar.

       • Aplicação: Informe sobre a necessidade de bibliotecas específicas ativas na base do cliente, compatibilidade com APIs RESTativar e JSON,revogar eAPI se há necessidade de instalação de algum SDKKeys, ou framework.
       • Exemplo: "Para adesabilitar integraçãoões
         automatizada, é necessário que a biblioteca do Ilimitar esteja ativa na base do cliente e que haja compatibilidade com APIs REST e JSON."

     • Links para Documentação de📎 Referênciancias

       e
     Suporte Técnico:

• Propósito: Fornecer acesso rápido a informações complementares e canais

  Documentos de ajudaapoio especializados.(ex: Postman Collection, APIary)

• Aplicação: Inclua links diretos para a documentação técnica da API

  Contato do ILLI e da Equals,  além de contatos ou canais de suporte para desenvolvedores.
• Exemplo: "Consulte a documentação completa da API ILLI em [link] e da API Equals em [link].  Para suporteresponsável técnico,cnico
  entre em contato com a equipe de desenvolvimento."

 

---

 

Estilo e Linguagem

• Linguagem técnica, precisa e objetiva

• Utilize exemplos reais e simplificados

• Destaque campos e termos com backticks para código

• Use tabelas para listar campos e validações