# 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:

<div class="_tableContainer_16hzy_1" id="bkmrk-par%C3%A2metro-tipo-descr"><div class="_tableWrapper_16hzy_14 group flex w-fit flex-col-reverse" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)" data-end="2000" data-start="1560"><thead data-end="1632" data-start="1560"><tr data-end="1632" data-start="1560"><th data-col-size="sm" data-end="1580" data-start="1560">Parâmetro</th><th data-col-size="sm" data-end="1590" data-start="1580">Tipo</th><th data-col-size="md" data-end="1632" data-start="1590">Descrição</th></tr></thead><tbody data-end="2000" data-start="1706"><tr data-end="1778" data-start="1706"><td data-col-size="sm" data-end="1726" data-start="1706">`cnpj`</td><td data-col-size="sm" data-end="1736" data-start="1726">string</td><td data-col-size="md" data-end="1778" data-start="1736">CNPJ da loja que será consultada</td></tr><tr data-end="1851" data-start="1779"><td data-col-size="sm" data-end="1799" data-start="1779">`data`</td><td data-col-size="sm" data-end="1809" data-start="1799">string</td><td data-col-size="md" data-end="1851" data-start="1809">Data da venda (formato: yyyy-MM-dd)</td></tr><tr data-end="1924" data-start="1852"><td data-col-size="sm" data-end="1872" data-start="1852">`page`</td><td data-col-size="sm" data-end="1882" data-start="1872">int</td><td data-col-size="md" data-end="1924" data-start="1882">Página de resultados</td></tr><tr data-end="2000" data-start="1925"><td data-col-size="sm" data-end="1945" data-start="1925">`formaPagamento`</td><td data-col-size="sm" data-end="1955" data-start="1945">string</td><td data-col-size="md" data-end="2000" data-start="1955">Filtro opcional (ex: “Cartão de Crédito”)</td></tr></tbody></table>

</div></div><div class="_tableContainer_16hzy_1" id="bkmrk--3"><div class="_tableWrapper_16hzy_14 group flex w-fit flex-col-reverse" tabindex="-1">  
</div>---

</div>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

<div class="_tableContainer_16hzy_1" id="bkmrk-c%C3%B3digo-motivo-401-ap"><div class="_tableWrapper_16hzy_14 group flex w-fit flex-col-reverse" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)" data-end="3330" data-start="3043"><thead data-end="3090" data-start="3043"><tr data-end="3090" data-start="3043"><th data-col-size="sm" data-end="3052" data-start="3043">Código</th><th data-col-size="sm" data-end="3090" data-start="3052">Motivo</th></tr></thead><tbody data-end="3330" data-start="3139"><tr data-end="3186" data-start="3139"><td data-col-size="sm" data-end="3148" data-start="3139">401</td><td data-col-size="sm" data-end="3186" data-start="3148">API Key inválida ou expirada</td></tr><tr data-end="3234" data-start="3187"><td data-col-size="sm" data-end="3196" data-start="3187">403</td><td data-col-size="sm" data-end="3234" data-start="3196">CNPJ não autorizado</td></tr><tr data-end="3282" data-start="3235"><td data-col-size="sm" data-end="3244" data-start="3235">404</td><td data-col-size="sm" data-end="3282" data-start="3244">Nenhuma venda encontrada</td></tr><tr data-end="3330" data-start="3283"><td data-col-size="sm" data-end="3292" data-start="3283">500</td><td data-col-size="sm" data-end="3330" data-start="3292">Erro interno no Ilimitar</td></tr></tbody></table>

</div></div>---

##### 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