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

Visão Técnica Geral

A integração permite que a plataforma ECOS (Equals) consulte o sistema ILLI para obter dados de vendas por cartão, com objetivo de realizar conciliação automática entre:

• Sistema de vendas (ILLI)

• Adquirentes (ex: Cielo, Rede, Stone)

• Bancos (valores recebidos)

A integração ocorre via API REST JSON e segue o modelo de pull: o ECOS consulta o Ilimitar com base em um CNPJ autorizado.

---

Arquitetura da Integração

[EQUALS] <--pull-- [ILLI API REST]
       |
  Exibe conciliação por:
  - Loja
  - Bandeira
  - Comprovante
  - Taxas

• A comunicação ocorre por HTTPS

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

---

Autenticação

• Acesso à API Ilimitar exige:

  • Usuário técnico criado no sistema

  • API Key associada ao usuário

Exemplo de 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 acesso:

• Gere um novo PIN

• Redefina a chave API

• Desative o usuário

---

Requisições (EQUALS → Ilimitar)

Endpoint principal 

GET /api/v1/vendas

Parâmetros disponíveis:

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 EQUALS realiza requisições periódicas:

  • A cada 5 minutos (modo intenso)

  • Ou 1x por hora (modo normal)

---

Regras de negócio

• A EQUALS apenas lê os dados: o ilimitar não envia nada proativo.

• A plataforma realiza:

  • Conciliação de taxas (previstas x aplicadas)

  • Validação de bandeiras

  • Geração de relatórios por loja/data

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

• A conciliação parcelada considera taxas individuais por parcela e taxas de antecipação

---

Tratamento de Erros

---

Considerações Técnicas

• A API segue padrão RESTful com respostas em JSON

• Deve-se evitar flood: chamadas com intervalo inferior a 5 minutos podem ser bloqueadas

• O sistema ECOS pode exibir:

  • % conciliado

  • total de vendas

  • discrepâncias e inconsistências