Ir para o conteúdo principal

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

1.

Visão Geral Técnica eGeral
Arquitetural
  • Objetivo: Proporcionar um entendimento de alto nível da arquitetura da

    A integração, seus componentes principais e o fluxopermite deque dados.a Issoplataforma éECOS fundamental(Equals) para o desenvolvedor contextualizar seu trabalho e compreenderconsulte o sistema como um todo.

  • Aplicação Prática:ILLI
      para
    • 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 deobter dados de vendas epor acartão, ECOScom comoobjetivo ade coletorarealizar econciliação conciliadora.automática entre:

      • Sistema de vendas (ILLI)

      • Adquirentes (ex: Cielo, Rede, Stone)

      • Bancos (valores recebidos)

    • Exemplo: "

      A integração se dáocorre via API,API ondeREST aJSON e segue o modelo de pull: o ECOS coletaconsulta informações do Ilimitar. Oo Ilimitar atuacom comobase aem fonteum primáriaCNPJ deautorizado.

      dados

       de

      vendas,
      enquanto

       a

      Arquitetura da Integração
      [ECOS realiza(Equals)] a<--pull-- requisição[ILLI eAPI REST]
       |
  Exibe conciliação dessespor:
  dados- comLoja
  adquirentes- eBandeira
  banco.- 
      Comprovante
  - Taxas

      • A comunicação ocorre por HTTPS

      • Requisições são feitas de 5 em 5 minutos ou a cada hora

       

      2.

       Endpoints

      e Métodos Detalhados (API Reference)

      Autenticação
      • Objetivo: Fornecer

        Acesso todasà asAPI informaçõesIlimitar necessárias para que o desenvolvedor possa construir e testar requisições de forma autônoma e eficiente.

      • Aplicação Prática:exige:

        • Listagem: Liste

          Usuário ostécnico endpointscriado disponíveisno (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.
        sistema

      • Exemplo:

          API

        • Endpoint: GET /api/vendasKey
          • associada
        • Parâmetrosao deusuário

          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", ...}]}

      Exemplo

      3.de Autenticaçãheaders:

      GET /api/v1/vendas?cnpj=12345678000100&data=2025-06-01&page=1
Host: api.illimitar.com.br
Authorization: Bearer <API_KEY>
Content-Type: application/json

      Para revogar o e Autorização

      acesso:

      • Objetivo: Explicar

        Gere detalhadamenteum comonovo PIN

      • Redefina a comunicaçãochave éAPI

        segura
        • e
      • como

        Desative o desenvolvedorusuário

        deve
        • se
      autenticar

       para

      acessar
      os

       recursos

      Requisições (ECOS → Ilimitar)

      Endpoint principal 

      GET /api/v1/vendas
      Parâmetros disponíveis:
      ParâmetroTipoDescrição
      cnpjstringCNPJ da API.loja
    • Aplicaçãque será consultada
      • datastringData da venda (formato: yyyy-MM-dd)
      pageintPágina de resultados
      formaPagamentostringFiltro opcional (ex: “Cartão Prática:de Crédito”)

       

       

      Exemplo de resposta (JSON)

      {
  "total": 2,
  "pagina": 1,
  "vendas": [
    {
      "numeroComprovante": "NSU00123",
      "valorBruto": 120.00,
      "dataHora": "2025-06-01T14:00:00",
      "formaPagamento": "Cartão Crédito",
      "parcelas": 2,
      "bandeira": "Mastercard",
      "taxa": 4.25,
      "valorLiquido": 114.90,
      "cliente": {
        "nome": "João Silva",
        "cpf": "12345678900"
      }
    }
  ]
}

       

       

      Frequência de consulta

      • O ECOS realiza Mecanismos:requisições periódicas:

        • A cada 5 minutos Detalhe(modo intenso)

        • Ou 1x por hora (modo normal)

       

       

      Regras de negócio

      • A ECOS apenas lê os mecanismosdados: de autenticação (ex:Ilimitar vianão APIenvia Key,nada usuárioproativo.

        e senha).
      • Obtenção e

        A Gerenciamento:plataforma Incluarealiza:

        instruções sobre como obter e gerenciar as credenciais.
        • Revogaç

          Conciliação de Acesso:taxas Forneça(previstas instruçõesx paraaplicadas)

          revogar

        • Validação acessode (gerarbandeiras

          novo
          • PIN,
        • redefinir

          Geração chave,de desativarrelatórios usuário).por loja/data

      • Todas as vendas consideradas são Exemplo:exclusivamente com cartão

        "

      • A autenticaçconciliação éparcelada realizadaconsidera viataxas individuais por parcela e taxas de antecipação

       

       
      Tratamento de Erros

      4.

      Modelagem
      CódigoMotivo
      401API 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 PINinválida ou desativarexpirada
      403CNPJ não usuárioautorizado
      404Nenhuma venda encontrada
      500Erro interno no Ilimitar."Ilimitar
      de
      Dados
      e

       Campos

       

      Considerações Técnicas

      • A API segue padrão Objetivo:RESTful Descrevercom respostas em JSON

      • Deve-se evitar flood: chamadas com intervalo inferior a estrutura5 detalhadaminutos dospodem dadosser quebloqueadas

        serão enviados e recebidos pela API, garantindo a correta interpretação e uso por parte do desenvolvedor.
      • Aplicação Prática:

        O sistema ECOS pode exibir:

        • Estrutura: Para

          % cadaconciliado

          tipo

        • total de dadovendas

          (vendas, taxas, recebimentos), detalhe os campos esperados.
        • Especificações: Inclua nome do campo, tipo de dado, formato

          discrepâncias e seinconsistências

          é 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