Manual Técnico – Integração AlterVision + Ilimitar (via API + Biblioteca)

Visão Técnica Geral

A AlterVision realiza a contagem de fluxo de pessoas (entradas e saídas) por meio de câmeras instaladas nas lojas. Esses dados são cruzados com os dados de vendas por loja e período, obtidos via API da Ilimitar, para gerar a taxa de conversão, que é exibida no painel da AlterVision.

A integração é baseada em:

• Coleta de dados da câmera → fluxo

• Requisições API → vendas

• Cálculo da taxa de conversão no back-end da AlterVision

---

Autenticação

A API da Ilimitar exige autenticação via usuário e senha com permissão de “Gestor”.

Formato da requisição:

POST /api/auth/login
Content-Type: application/json

{
  "usuario": "altervision.api",
  "senha": "********"
}

Resposta esperada:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5..."
}

Esse token será usado no header das próximas requisições:

Authorization: Bearer <token>

---

Instalação da Biblioteca

A biblioteca supademo é responsável por habilitar a comunicação com a API do Ilimitar de forma estruturada.

Requisitos:

• Python ≥ 3.8

• Dependências: requests, pydantic, datetime

• Acesso HTTPS ao domínio da Ilimitar

Instalação:

pip install supademo

Inicialização no código:

from supademo import IlimitarAPI

api = IlimitarAPI(usuario='altervision.api', senha='*******')
vendas = api.obter_vendas(cnpj='12345678000100', data='2025-06-05')

GET /api/v1/vendas

Consulta de vendas realizadas por loja e data.

Parâmetros obrigatórios:

Parâmetro	Tipo	Descrição
cnpj	string	CNPJ da loja
data	string	Data de vendas (YYYY-MM-DD)
paginacao	int	Número da página (default 1)

Exemplo de requisição:

GET /api/v1/vendas?cnpj=12345678000100&data=2025-06-05
Authorization: Bearer <token>
Content-Type: application/json

Resposta esperada:

[
  {
    "numeroComprovante": "A001",
    "valorBruto": 150.00,
    "dataHora": "2025-06-05T10:00:00",
    "formaPagamento": "Cartão",
    "bandeira": "Visa",
    "parcelas": 2
  }
]

---

Frequência e Sincronização

• A AlterVision executa a consulta de dados de vendas:

  • Em tempo real ou a cada 5/15 minutos

  • Sempre referenciada por data e loja

• Os dados de fluxo são combinados com o número de vendas para calcular:

taxa_conversao = vendas_realizadas / pessoas_que_entraram

Retorno e Exibição

Todos os dados são utilizados internamente pela AlterVision para alimentar:

• Painéis por loja

• Relatórios de conversão diária

• Comparativos de loja, horário, feriados, promoções etc.

---

Tratamento de Erros