Ir para o conteúdo principal

Diretrizes para a Documentação Orientada ao Desenvolvedor

Ao criar ou revisar a documentação para o desenvolvedor, siga estas diretrizes para garantir clareza técnica, precisão e todos os detalhes necessários para a implementação:

  1. Visão Geral Técnica e Arquitetural:

    • Propósito: Fornecer um entendimento de alto nível sobre a arquitetura da integração, seus componentes e o fluxo de dados principal.
    • Aplicação: Inclua 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ção e conciliação desses dados com adquirentes e bancos."

  2. Endpoints e Métodos Detalhados (API Reference):

    • Propósito: Fornecer todas as informações necessárias para que o desenvolvedor possa construir e testar requisições.
    • Aplicação: Liste os endpoints disponíveis (ex: /getvendas), os métodos HTTP (GET, POST), os parâmetros de requisição (CNPJ, data de emissão, paginação),  e exemplos 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): Data da emissão das vendas.
        • pagina (integer, opcional): Número da página para paginação de resultados.
      • Exemplo de Resposta (JSON): {"vendas": [{"id": "...", "valor": "...", "formaPagamento": "cartao", ...}]}

  3. Autenticação e Autorização:

    • Propósito: Explicar como a comunicação é segura e como 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."

  4. Modelagem de Dados e Campos:

    • Propósito: Descrever a estrutura dos dados que serão enviados e recebidos, garantindo a correta interpretação.
    • Aplicação: Para cada tipo de dado (vendas, taxas, recebimentos), detalhe os campos esperados (nome do campo, tipo de dado, 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."

  5. Tratamento de Erros e Códigos de Status:

    • Propósito: Guiar o desenvolvedor sobre como lidar com falhas na comunicação e identificar problemas.
    • Aplicação: Liste os possíveis códigos de status 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"}."

  6. Frequência e Limites de Requisição:

    • Propósito: Informar o desenvolvedor sobre as limitações de uso da API para evitar bloqueios ou sobrecarga do sistema.
    • Aplicação: Mencione a frequência de requisições permitida (ex: "a cada 5 minutos ou de hora em hora") e se há 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."

  7. Pré-requisitos Técnicos e Dependências:

    • Propósito: Listar 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 REST e JSON, e se há necessidade de instalação de algum SDK ou framework.
    • Exemplo: "Para a integração automatizada, é necessário que a biblioteca do Ilimitar esteja ativa na base do cliente e que haja compatibilidade com APIs REST e JSON."

  8. Links para Documentação de Referência e Suporte Técnico:

    • Propósito: Fornecer acesso rápido a informações complementares e canais de ajuda especializados.
    • Aplicação: Inclua links diretos para a documentação técnica da API 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 suporte técnico, entre em contato com a equipe de desenvolvimento."
Voltar ao topo