Ir para o conteúdo principal

Manual Técnico – Integração ILLI + Equals (via API ECOS)

1. Visão Geral Técnica e Arquitetural

  • Objetivo: Proporcionar um entendimento de alto nível da arquitetura da integração, seus componentes principais e o fluxo de dados. Isso é fundamental para o desenvolvedor contextualizar seu trabalho e compreender o sistema como um todo.
  • Aplicação Prática:
    • Diagramas: Inclua diagramas de fluxo de dados que ilustrem a interação entre os sistemas.
    • Tecnologias: Mencione as tecnologias envolvidas (ex: REST, JSON, ESB, etc.).
    • Papel dos Sistemas: Detalhe o papel de cada sistema na integração (PDV ILLI, Equals, Ilimitar). Explique que o Ilimitar atua como a fonte primária de dados de vendas e a ECOS como a coletora e conciliadora.
  • 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 banco.

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

  • Objetivo: Fornecer todas as informações necessárias para que o desenvolvedor possa construir e testar requisições de forma autônoma e eficiente.
  • Aplicação Prática:
    • Listagem: Liste os endpoints disponíveis (ex: /getvendas).
    • Métodos HTTP: Especifique os métodos HTTP (GET, POST) para cada endpoint.
    • Parâmetros de Requisição: Descreva os parâmetros de requisição (ex: cnpj, dataEmissao, pagina), incluindo tipo de dado e se são obrigatórios/opcionais.
    • Payloads: Forneça 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

  • Objetivo: Explicar detalhadamente como a comunicação é segura e como o desenvolvedor deve se autenticar para acessar os recursos da API.
  • Aplicação Prática:
    • Mecanismos: Detalhe os mecanismos de autenticação (ex: via API Key, usuário e senha).
    • Obtenção e Gerenciamento: Inclua instruções sobre como obter e gerenciar as credenciais.
    • Revogação de Acesso: Forneça instruções para revogar o 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

  • Objetivo: Descrever a estrutura detalhada dos dados que serão enviados e recebidos pela API, garantindo a correta interpretação e uso por parte do desenvolvedor.
  • Aplicação Prática:
    • Estrutura: Para cada tipo de dado (vendas, taxas, recebimentos), detalhe os campos esperados.
    • Especificações: Inclua nome do campo, tipo de dado, formato e se é obrigatório/opcional.
    • Granularidade: 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 

  • Objetivo: Guiar o desenvolvedor sobre como lidar com possíveis falhas na comunicação da API e como identificar problemas através dos códigos de status e mensagens de erro.
  • Aplicação Prática:
    • Códigos HTTP: Liste os possíveis códigos de status HTTP (200 OK, 400 Bad Request, 401 Unauthorized, 500 Internal Server Error).
    • Corpos de Erro: Descreva 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 

  • Objetivo: Informar o desenvolvedor sobre as limitações de uso da API para evitar bloqueios, sobrecarga do sistema e garantir a estabilidade da integração.
  • Aplicação Prática:
    • Frequência Permitida: Mencione a frequência de requisições permitida (ex: "a cada 5 minutos ou de hora em hora").
    • Limites de Dados: Especifique se há limites de dados por requisição ou por período (ex: "Limite de 20 dias por período em relatórios CSV").
  • Exemplo: "A ECOS realiza consultas ao endpoint do Ilimitar a cada 5 minutos ou de hora em hora para obter informações de vendas. Há um limite de 20 dias por período em relatórios CSV."

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

  • Objetivo: Listar todas as condições técnicas que precisam ser atendidas no ambiente de desenvolvimento ou produção para que a integração funcione corretamente.
  • Aplicação Prática:
    • Bibliotecas: Informe sobre a necessidade de bibliotecas específicas ativas na base do cliente.
    • Compatibilidade: Mencione a compatibilidade com APIs REST e JSON.
    • SDKs/Frameworks: Indique se há necessidade de instalação de algum SDK ou framework específico.
  • 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."
  • Objetivo: Fornecer ao desenvolvedor acesso rápido a informações complementares e canais de ajuda especializados para solucionar dúvidas e problemas.
  • Aplicação Prática:
    • Links Diretos: Inclua links diretos para a documentação técnica da API do ILLI e da Equals.
    • Canais de Suporte: Forneça contatos ou canais de suporte específicos 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