# Equals # Manual de Implantação – Integração ILLI + Equals (Conciliação de Recebíveis) ##### Visão Geral A integração entre o PDV **ILLI** e a plataforma **Equals** (via ECOS) tem como objetivo centralizar e automatizar a **conciliação de vendas realizadas com cartão**, facilitando o controle de recebimentos e a identificação de **taxas incorretas ou valores divergentes**. > Duas formas de integração são possíveis: - **Manual** (via importação de arquivos CSV) - **Automatizada** (via API REST da Ilimitar) --- ##### **1. Pré-requisitos para Implantação** Manual - Acesso ao **Gestor Ilimitar** - Geração de relatório CSV por período (máx. 20 dias) - Acesso à plataforma Equals Automatizada - Biblioteca Equals integrada ao sistema Ilimitar - API ativa no Ilimitar (chave de acesso) - CNPJ do cliente informado à Equals - Autorização via API Key + usuário no sistema --- ##### **2. Formas de Integração** ##### Manual (via CSV) - No **Gestor Ilimitar**, selecione: - Período de até 20 dias - Entidade (loja) - Exporte o relatório ZIP contendo os arquivos CSV por dia - Acesse a **Equals** e importe os arquivos **Vantagens**: ✔️ Rápida de implantar ❌ Necessita de ações manuais recorrentes --- ##### Automatizada (via API Ilimitar) - **Biblioteca ativa** no cliente - Equals consulta o endpoint `GET /vendas` da Ilimitar via: - **CNPJ** - **Data de emissão** - **Paginação** - Requisições são feitas a cada **5 minutos** ou **hora em hora** **Vantagens**: ✔️ Tempo real ou próximo ✔️ Sem ação manual ❌ Requer autenticação e biblioteca instalada --- ##### **3. Autenticação e Controle de Acesso** - A API do Ilimitar exige autenticação por **API Key + usuário**. - Para revogar o acesso: - Gere um novo PIN - Redefina a API Key - Desative o usuário **Exemplo de usuário configurado:** Usuário: `Icor` Chave: `XXXXXXXXXXXXXXXXXXXXX` --- ##### **4. Dados Enviados / Sincronizados** A Equals (ECOS) coleta os seguintes dados via API ou CSV:

Informação	Detalhes
Valor bruto da venda	Inclui taxas
Forma de pagamento	Crédito, débito, Pix etc.
Número do comprovante	NSU da venda
Data/hora da transação	Timestamp
Dados do cliente	Nome e CPF (quando disponível)
Taxas e bandeiras aplicadas	Inclui taxa por parcela, antecipação etc.

---

##### **5. Funcionalidades da Equals** - **Conciliação automática** entre: - Vendas do PDV - Dados das adquirentes - Repasse bancário - **Interface Equals** exibe: - Percentual conciliado - Total de vendas no período - Cronograma de recebimento (parcelas) - Taxas aplicadas por adquirente - Alertas de divergência (ex: antecipação indevida) --- ##### **6. Regras Técnicas para Integração Automatizada**

Parâmetro	Tipo	Observação
`CNPJ`	String	Deve ser da loja a ser conciliada
`DataEmissao`	Date	Usado para filtrar as vendas
`Page`	Integer	Paginação de resultados
`FormaPagamento`	String	Apenas vendas com cartão são consultadas
`Intervalo`	Horário	Requisições a cada 5 ou 60 min

--- ##### **7. Instalação da Integração Automatizada** - Solicite ativação da **biblioteca Equals** no Ilimitar - Crie um usuário técnico e gere a **chave API** - Informe o **CNPJ** à Equals - A Equals iniciará a leitura via API --- ##### **8. Aspectos Comerciais** - **Integração manual**: pode ser disponibilizada **sem custo** - **Integração automática**: pode envolver **modelo comercial adicional** # 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 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:

Parâmetro	Tipo	Descrição
`cnpj`	string	CNPJ da loja que será consultada
`data`	string	Data da venda (formato: yyyy-MM-dd)
`page`	int	Página de resultados
`formaPagamento`	string	Filtro opcional (ex: “Cartão 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 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

Código	Motivo
401	API Key inválida ou expirada
403	CNPJ não autorizado
404	Nenhuma venda encontrada
500	Erro interno no Ilimitar

--- ##### 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 # Overview Integração Equals ##### Visão Geral A integração entre o PDV ILLI e a plataforma Equals tem como objetivo principal **automatizar e centralizar a conciliação de vendas**, proporcionando aos usuários uma visão clara e completa de seus recebimentos. Através da sincronização de dados em tempo real, a integração facilitará a identificação de divergências nas taxas aplicadas e nos valores recebidos, agilizando a gestão financeira e otimizando o controle sobre as vendas realizadas. **A integração permitirá:** - Consolidar as informações de vendas do PDV ILLI com os dados da plataforma Equals. - Automatizar a conciliação de pagamentos, eliminando processos manuais e reduzindo erros. - Obter previsões precisas de valores e datas de recebimento. - Melhorar a gestão financeira, proporcionando maior controle e visibilidade sobre as vendas. ##### Objetivo do Produto Desenvolver uma solução de integração completa e eficiente entre o PDV ILLI e a plataforma Equals, que automatize a conciliação de vendas, simplifique a gestão financeira e promova uma experiência mais prática e organizada para os usuários. ##### Público-Alvo - Gerentes financeiros que buscam maior controle e visibilidade sobre os recebimentos. - Administradores de lojas que utilizam o Equals como ferramenta de gestão financeira. --- ##### Apresentação Comercial ##### [Acesse a apresentação completa aqui](https://gamma.app/docs/OK-Gestao-de-Recebiveis-Completa-com-ILLI-x-Equals-6ok0gui7bkdhgu1) ##### Documentações de APIs - API ILLI: [link para a documentação da API ILLI](https://documenter.getpostman.com/view/7431991/2s9Y5bQMG8) - API Equals: [link para a documentação da API Equals](https://apiequals.docs.apiary.io/) ##### Funcionalidades Principais ##### Importação de Dados de Vendas - Envio automático dos dados de vendas do PDV ILLI para a plataforma Equals, incluindo: - Valor bruto da venda - Forma de pagamento (cartão de crédito, débito, Pix, etc.) - Data e hora da venda - Número do comprovante - Detalhes do cliente - Informações sobre taxas e impostos ##### Conciliação Automática - Comparação dos dados de vendas do PDV ILLI com os dados da Equals, identificando: - Divergências de valores - Taxas incorretas - Pagamentos não reconhecidos ##### Integração com Módulos Equals - Integração com os diferentes módulos da plataforma Equals, como: - Contas a receber - Fluxo de caixa - Relatórios financeiros - Automação de tarefas financeiras, como registro de pagamentos e geração de relatórios. ##### Instalação e Configuração 1. Baixe a biblioteca de integração: [link para download](https://loja.pdv.moda/produtoDetalhe/413) 2. Adicione a biblioteca na base do cliente. 3. Certifique-se da compatibilidade com APIs REST e JSON. ##### Obtenção e Fornecimento da API Key 1. Gere a API Key do ILLI. 2. Forneça a API Key ao cliente. ##### Configuração no Portal Equals 1. Acesse o portal Equals. 2. Insira a API Key para autenticação. ##### Equipe Envolvida - Desenvolvedores: Maurício Francelino - Stakeholders: Hermílio Alves, Edson Barros, Maurício Francelino