# CREDSYSTEM (PDV+TOTEM)

# Integração Credsystem — Introdução

<section class="capitulo" id="bkmrk-este-material-explic">Este material explica como o sistema ILLI se conecta à Credsystem para consultar faturas, receber pagamentos e operar o Totem de Pagamento Instantâneo nas lojas.

<nav class="indice">## Índice dos capítulos

**01 — Introdução** (esta página): o que é o sistema e palavras importantes  
**02 — Arquitetura**: como os módulos se conectam  
**03 — Instalação**: banco de dados e passos de instalação  
**04 — Configuração**: cadastro por loja/entidade  
**05 — Portal do operador**: tela de atendimento no balcão  
**06 — Fluxo de pagamento**: pagamento em dinheiro ou cartão  
**07 — Fluxo de Pagamento Instantâneo e Totem**: pagamento por Código de Resposta Rápida e autoatendimento  
**08 — Parcelamento e limite**: simulação e contratação de planos  
**09 — Estorno e regras**: desfazimento de pagamento  
**10 — Gestor no celular**: configuração de caixa e impressora  
**11 — Referência para Tecnologia da Informação**: endpoints, tabelas e auditoria

</nav><section class="para-todos">## Em linguagem simples

O sistema permite que a loja **consulte a fatura do cliente** pelo Cadastro de Pessoa Física, **receba o pagamento** (dinheiro, cartão ou Pagamento Instantâneo) e **registre tudo** no caixa e no histórico da loja.

Existem três formas principais de uso:

1. **Portal no computador** — o operador atende o cliente no balcão.
2. **Totem de Pagamento Instantâneo** — o cliente paga sozinho na tela de autoatendimento.
3. **Aplicativo Gestor no celular** — configura qual caixa e impressora cada funcionário usa.

Tudo isso conversa com os servidores da **Credsystem** (empresa do cartão/fatura) pela internet, de forma segura.

</section>![Visão geral do sistema](https://kb.illimitar.pro/uploads/images/gallery/2026-06/embedded-image-qtacawxx.png)

*Figura 1 — O ILLI fica no meio: recebe o pedido da loja, fala com a Credsystem e registra no caixa.*

## Glossário — palavras que você vai encontrar

<dl><dt>Cadastro de Pessoa Física</dt><dd>Número de identificação do cliente. É usado para buscar a fatura dele.</dd><dt>Extrato / Fatura</dt><dd>Conta que o cliente precisa pagar. Pode ter valor total, valor mínimo ou parcelas.</dd><dt>Entidade / Loja</dt><dd>Cada unidade de negócio cadastrada no ILLI. Cada loja tem sua própria configuração.</dd><dt>Caixa</dt><dd>O ponto de venda onde o operador trabalha. O pagamento pode gerar uma entrada de dinheiro no caixa.</dd><dt>Pré-autorização</dt><dd>Passo em que a Credsystem *reserva* o pagamento antes de confirmar de vez. É como "segurar" o valor.</dd><dt>Efetivação</dt><dd>Confirmação final do pagamento na Credsystem.</dd><dt>Estorno / Desfazimento</dt><dd>Cancelar um pagamento que já foi feito. Só é permitido em alguns casos e dentro de um prazo.</dd><dt>Pagamento Instantâneo</dt><dd>Forma de pagamento instantânea pelo celular, usando Código de Resposta Rápida.</dd><dt>Totem</dt><dd>Tela de autoatendimento na loja, onde o cliente paga sozinho pelo Pagamento Instantâneo.</dd><dt>Integrador</dt><dd>Banco de dados auxiliar que guarda histórico de clientes, pagamentos e avaliações do totem.</dd><dt>Ponto de Venda</dt><dd>Sistema de ponto de venda do ILLI. Registra entradas e saídas de dinheiro no caixa.</dd></dl><section class="para-ti">## Detalhes para Tecnologia da Informação

O diretório `bibliotecas/` contém 4 módulos independentes escritos em Pré-processador de Hipertexto, cada um identificado por Identificador Universal Único:

<table><thead><tr><th>Identificador Universal Único</th><th>Classe</th><th>Função</th></tr></thead><tbody><tr><td>`981bfb94-…`</td><td>`api_integracao_credsystem`</td><td>Cliente de Transferência Representacional de Estado/Autorização Aberta Credsystem</td></tr><tr><td>`88e14c87-…`</td><td>`api_integracao_credsystem_pagamento_total`</td><td>Portal, totem, Ponto de Venda, banco integrador</td></tr><tr><td>`857e21c5-…`</td><td>`credsystem_gestor_configuracoes`</td><td>Config caixa/impressora por usuário</td></tr><tr><td>`f3d67c71-…`</td><td>`configCredsystem`</td><td>Tela legada (substituída pela Quasar em `981bfb94`)</td></tr></tbody></table>

Dependência compartilhada: `util.php` (`12262a22-30ab-11e9-bb4c-127101af6b0d`).

Documentação focada nos módulos atuais; legado Protocolo Simples de Acesso a Objetos em `v1/credsystem` não é coberto neste livro.

</section></section>

# Arquitetura — Como os módulos se conectam

<section class="capitulo" id="bkmrk-o-sistema-%C3%A9-dividido">O sistema é dividido em peças que trabalham juntas: uma parte fala com a Credsystem, outra atende o operador, outra guarda o histórico e outra configura o celular do gestor.

<section class="para-todos">## Em linguagem simples

Imagine uma loja com três pontos de contato:

- **Computador do balcão** — onde o operador consulta e recebe pagamentos.
- **Totem na entrada** — onde o cliente paga sozinho pelo Pagamento Instantâneo.
- **Celular do gestor** — onde se escolhe caixa e impressora.

Todos esses pontos passam pelo **mesmo sistema central** (ILLI), que por sua vez conversa com a Credsystem na internet e grava tudo no banco de dados da loja.

</section>![Arquitetura dos módulos](https://kb.illimitar.pro/uploads/images/gallery/2026-06/embedded-image-3vkc4cn0.png)

*Figura 2 — Arquitetura: o módulo Pagamento Total (88e14c87) orquestra tudo; a Interface de Programação de Aplicações Credsystem (981bfb94) faz as chamadas externas.*

<section class="para-ti">## Detalhes para Tecnologia da Informação

### Camadas

<table><thead><tr><th>Camada</th><th>Módulo</th><th>Responsabilidade</th></tr></thead><tbody><tr><td>Apresentação</td><td>`88e14c87/visual.html`</td><td>Vue 3 — portal operador</td></tr><tr><td>Apresentação</td><td>`/v1/credsystem-pix`</td><td>Interface do Usuário do Totem de Pagamento Instantâneo (fora de bibliotecas/)</td></tr><tr><td>Apresentação</td><td>`981bfb94/visual.html`</td><td>Quasar — configuração por entidade</td></tr><tr><td>Negócio</td><td>`88e14c87/controle.php`</td><td>Orquestração, Ponto de Venda, integrador, auditoria</td></tr><tr><td>Integração</td><td>`981bfb94/controle.php`</td><td>Autorização Aberta versão 2 + Guzzle → Interface de Programação de Aplicações Credsystem</td></tr><tr><td>Configuração mobile</td><td>`857e21c5/controle.php`</td><td>`configuracao_usuario`</td></tr></tbody></table>

### Dependências entre módulos

- `88e14c87` instancia `new api_integracao_credsystem()` para todas as operações Credsystem.
- `88e14c87` chama `vendarapida::sangriasuprimento` para receita/despesa no Ponto de Venda.
- `857e21c5` e `88e14c87` usam `util.php` (`12262a22`).

### Rotas principais (@Link)

- `/bibliotecas/981bfb94-…/api_integracao_credsystem`
- `/bibliotecas/88e14c87-…/api_integracao_credsystem_pagamento_total`
- `/bibliotecas/857e21c5-…/credsystem_gestor_configuracoes`

</section></section>

# Instalação e Banco de Dados

<section class="capitulo" id="bkmrk-antes-de-usar-o-sist">Antes de usar o sistema, é preciso instalar os módulos e criar as tabelas que guardam clientes, pagamentos e avaliações do totem.

<section class="para-todos">## Em linguagem simples

A equipe de Tecnologia da Informação precisa rodar a **instalação** dos módulos no servidor. Isso cria um "caderno de anotações" digital (banco de dados) onde ficam guardados:

- Os **dados dos clientes** que já consultaram a fatura.
- O **histórico de pagamentos** feitos na loja.
- As **notas de satisfação** que o cliente dá no totem (de 1 a 5).

Sem essa instalação, o portal e o totem não conseguem salvar informações.

</section>![Passos de instalação](https://kb.illimitar.pro/uploads/images/gallery/2026-06/embedded-image-qlkfgjw4.png)

*Figura 3 — Ordem das migrações do instalador (88e14c87): v1 cria o banco; v2, v3 e v4 criam as tabelas.*

<section class="para-ti">## Detalhes para Tecnologia da Informação

### Instalador

Arquivo: `bibliotecas/88e14c87-…/instalador.php`

Rota: `/bibliotecas/88e14c87-…/api_integracao_credsystem_pagamento_total/install`

Dependência: `util.php` (`12262a22-30ab-11e9-bb4c-127101af6b0d`)

### Migrações

<table><thead><tr><th>Versão</th><th>Ação</th></tr></thead><tbody><tr><td>v1</td><td>`CREATE DATABASE IF NOT EXISTS {banco}_integrador`</td></tr><tr><td>v2</td><td>Cria tabela `cred_cliente` (Notação de Objetos JavaScript: `cpf`, `nome`, `codigoCliente`, `diaMesNascimento`)</td></tr><tr><td>v3</td><td>Cria tabela `cred_pagamento` (`cpf`, entidade, usuário, caixa, valor Notação de Objetos JavaScript, tipo, situação)</td></tr><tr><td>v4</td><td>Cria tabela `cred_satisfacao` (`cpf`, nota 1–5)</td></tr></tbody></table>

### Schema cred\_pagamento

<table><thead><tr><th>Coluna</th><th>Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td>`cpf_cliente`</td><td>varchar(14)</td><td>Cadastro de Pessoa Física sem formatação</td></tr><tr><td>`id_entidade`</td><td>int</td><td>Loja/entidade</td></tr><tr><td>`id_usuario`</td><td>int</td><td>Operador</td></tr><tr><td>`id_caixa`</td><td>int</td><td>Caixa do Ponto de Venda</td></tr><tr><td>`valor`</td><td>Notação de Objetos JavaScript</td><td>Detalhes do pagamento</td></tr><tr><td>`pagamento`</td><td>varchar</td><td>`DINHEIRO` ou `PIX`</td></tr><tr><td>`situacao`</td><td>varchar</td><td>`EFETIVADO` ou `ESTORNADO`</td></tr></tbody></table>

### Outros módulos

- `981bfb94` — instalador vazio (sem migrações).
- `857e21c5` — usa tabela existente `configuracao_usuario`.

### Ordem recomendada de instalação

1. Instalar `981bfb94` (Interface de Programação de Aplicações Credsystem)
2. Instalar `88e14c87` (executar v1 → v4)
3. Instalar `857e21c5` (gestor)
4. Configurar entidade (capítulo 04)

</section></section>

# Configuração por Loja / Entidade

<section class="capitulo" id="bkmrk-cada-loja-precisa-te">Cada loja precisa ter seus dados de acesso à Credsystem cadastrados no sistema, incluindo usuário, senha, Endereços Uniformes de Recurso e vínculos com o caixa.

<section class="para-todos">## Em linguagem simples

Antes de consultar faturas ou receber pagamentos, a equipe de Tecnologia da Informação precisa **configurar cada loja** no sistema. É como cadastrar o "login e senha" que a loja usa para falar com a Credsystem.

O que precisa ser preenchido:

1. **Selecionar a loja** (entidade) no menu.
2. **Usuário e senha** fornecidos pela Credsystem.
3. **Endereços das Interfaces de Programação de Aplicações** (links de conexão — a equipe de Tecnologia da Informação recebe da Credsystem).
4. **Forma de pagamento e natureza** — para o caixa registrar corretamente a entrada de dinheiro.
5. **Imagem de fundo do totem** (opcional) — personaliza a tela do autoatendimento por Pagamento Instantâneo.

A tela de configuração atual usa o módulo **Interface de Programação de Aplicações Credsystem** (interface Quasar). Existe uma tela antiga que foi substituída por esta.

</section>![Fluxo de configuração](https://kb.illimitar.pro/uploads/images/gallery/2026-06/embedded-image-jlkcd9ji.png)

*Figura 4 — A configuração é salva por entidade e lida por todos os módulos que operam pagamentos.*

<section class="para-ti">## Detalhes para Tecnologia da Informação

### Armazenamento

- Tabela: `configuracao_entidade`
- Chave (`descricao`): `api_config_credsystem`
- Valor: Notação de Objetos JavaScript codificado em **Codificação Base 64**
- Métodos: `getConfiguracaoCredsystem()` / `salvarConfiguracaoCredsystem()` em `981bfb94/controle.php`

### Campos do Notação de Objetos JavaScript de configuração

<table><thead><tr><th>Campo</th><th>Descrição</th></tr></thead><tbody><tr><td>`idEntidade`</td><td>ID da entidade/loja</td></tr><tr><td>`usuario`</td><td>Usuário Credsystem</td></tr><tr><td>`senha`</td><td>Senha Credsystem (não expor em logs)</td></tr><tr><td>`urlArrecadacao`</td><td>Endereço Uniforme de Recurso base Interface de Programação de Aplicações arrecadação (legado Linguagem de Descrição de Serviços Web; Transferência Representacional de Estado usa Endereços Uniformes de Recurso fixos no código)</td></tr><tr><td>`urlLimite`</td><td>Endereço Uniforme de Recurso Interface de Programação de Aplicações limite/venda</td></tr><tr><td>`bandeira`</td><td>Bandeira do cartão (ex.: OBJETIVA)</td></tr><tr><td>`idFormaPagamento`</td><td>ID forma de pagamento no Ponto de Venda para receita</td></tr><tr><td>`idNaturezaLancamento`</td><td>Natureza contábil da receita</td></tr><tr><td>`idNaturezaDespesa`</td><td>Natureza contábil da despesa (estorno)</td></tr></tbody></table>

### Configuração do Totem

- Chave global: `credsystem_pix_fundo_totem_atracao` (tabela `configuracao`)
- Endpoints: `obterFundoTotemAtracao`, `salvarFundoTotemAtracao`, `limparFundoTotemAtracao`, `exibirFundoTotemAtracao`
- Armazena imagem via `arquivo_imagem_model`

### Tela de configuração

- Canônica: `981bfb94/visual.html` (Quasar/Vue)
- Legada (não usar): `f3d67c71/visual.html` (AngularJS) — mesma chave `api_config_credsystem`

### Autenticação Credsystem (Transferência Representacional de Estado)

O módulo `981bfb94` obtém token Autorização Aberta versão 2 via Oracle IDCS (`client_credentials`). Endereços Uniformes de Recurso de homologação estão definidas no construtor da classe. Para produção, parametrizar Endereços Uniformes de Recurso e credenciais Autorização Aberta fora do código ou via variáveis de ambiente.

</section></section>

# Portal do Operador — Uso no Balcão

<section class="capitulo" id="bkmrk-o-portal-%C3%A9-a-tela-qu">O portal é a tela que o operador usa no computador para consultar a fatura do cliente, receber pagamentos e imprimir comprovantes.

<section class="para-todos">## Em linguagem simples

O operador abre o portal no navegador e segue estes passos:

1. **Digitar o Cadastro de Pessoa Física** do cliente e clicar em consultar.
2. **Ver os extratos** (faturas) que aparecem na tela — valor total, mínimo, vencimento.
3. **Escolher o que pagar** — pode ser o valor total, o mínimo ou outro valor permitido.
4. **Confirmar o pagamento** — o sistema pede confirmação antes de cobrar.
5. **Imprimir o comprovante** — se a impressora estiver configurada.
6. **Desfazer** (se necessário) — só funciona em até 24 horas e não vale para Pagamento Instantâneo.

Se o cliente quiser parcelar, o operador pode consultar o limite e simular planos (ver capítulo 08).

</section>![Fluxo do portal operador](https://kb.illimitar.pro/uploads/images/gallery/2026-06/embedded-image-wgz53sdu.png)

*Figura 5 — Passo a passo do operador no portal de pagamento.*

<section class="para-ti">## Detalhes para Tecnologia da Informação

### Interface

- Arquivo: `88e14c87/visual.html` (Vue 3)
- Rota: `/bibliotecas/88e14c87-…/api_integracao_credsystem_pagamento_total`
- Chamadas JavaScript Assíncrono e XML para `…/api/{metodo}`

### Endpoints usados pelo portal

<table><thead><tr><th>Endpoint</th><th>Função</th></tr></thead><tbody><tr><td>`consultarTitulos`</td><td>Busca faturas na Credsystem; salva cliente em `cred_cliente`</td></tr><tr><td>`consultarLimiteSituacao`</td><td>Simula limite e planos de parcelamento</td></tr><tr><td>`contratarPlanoLimite`</td><td>Contrata plano na Interface de Programação de Aplicações venda-loja</td></tr><tr><td>`pagamentoTotal`</td><td>Pagamento convencional (dinheiro/cartão)</td></tr><tr><td>`preAutorizacaoPix`</td><td>Gera Código de Resposta Rápida Pagamento Instantâneo</td></tr><tr><td>`consultarStatusPixPagamento`</td><td>Polling status de Pagamento Instantâneo</td></tr><tr><td>`confirmarRecebimentoPix`</td><td>Confirma Pagamento Instantâneo concluído</td></tr><tr><td>`listarPagamentosCredsystemIntegrador`</td><td>Lista pagamentos estornáveis</td></tr><tr><td>`desfazerPagamento`</td><td>Estorno na Credsystem + despesa no Ponto de Venda</td></tr><tr><td>`registrarControleImpressao`</td><td>Auditoria — impressão correta</td></tr><tr><td>`registrarControleImpressaoIncorreta`</td><td>Auditoria — impressão com erro</td></tr></tbody></table>

### Sessão do Ponto de Venda

Para lançar receita/despesa no caixa, o payload deve incluir dados de sessão: `token`, `id_conta`, `id_operador`. Sem isso, o pagamento na Credsystem pode ocorrer mas o lançamento no Ponto de Venda falha.

### Payload típico — consultarTitulos

```
{
  "codigoEstabelecimento": "…",
  "cpfCliente": "12345678901"
}
```

</section></section>

# Fluxo de Pagamento — Dinheiro e Cartão

<section class="capitulo" id="bkmrk-quando-o-cliente-pag">Quando o cliente paga a fatura em dinheiro ou cartão no balcão, o sistema passa por quatro etapas na Credsystem antes de registrar o valor no caixa.

<section class="para-todos">## Em linguagem simples

O pagamento no balcão funciona assim:

1. **Buscar a fatura** — o sistema consulta na Credsystem o que o cliente deve.
2. **Reservar o valor** (pré-autorização) — a Credsystem "segura" o valor antes de confirmar.
3. **Confirmar o pagamento** (efetivação) — a Credsystem registra que o dinheiro foi recebido.
4. **Verificar se deu certo** (sonda) — o sistema confere se a Credsystem confirmou tudo.
5. **Registrar no caixa** — o valor entra como receita no Ponto de Venda da loja.
6. **Guardar no histórico** — fica salvo no banco integrador para consultas futuras.

Se algo der errado no meio do caminho, o sistema pode tentar **estornar automaticamente** a reserva (quando configurado).

</section>![Fluxo de pagamento convencional](https://kb.illimitar.pro/uploads/images/gallery/2026-06/embedded-image-bt5ovn23.png)

*Figura 6 — Fluxo completo do pagamento convencional: quatro etapas na Credsystem, depois gravação local e lançamento no Ponto de Venda.*

<section class="para-ti">## Detalhes para Tecnologia da Informação

### Orquestração

- A interface front-end chama `pagamentoTotal()` em `88e14c87/controle.php`
- Que delega para `api_integracao_credsystem::pagamento()` em `981bfb94/controle.php`

### Etapas na Interface de Programação de Aplicações Credsystem (método pagamento)

<table><thead><tr><th>\#</th><th>Etapa</th><th>Endpoint de Transferência Representacional de Estado</th><th>Campo etapa em erro</th></tr></thead><tbody><tr><td>1</td><td>Consultar títulos</td><td>`GET consulta-titulo`</td><td>`consultarTitulos`</td></tr><tr><td>2</td><td>Pré-autorização</td><td>`POST pre-autorizacao`</td><td>`preAutorizar`</td></tr><tr><td>3</td><td>Efetivação</td><td>`POST efetivacao`</td><td>`efetivar`</td></tr><tr><td>4</td><td>Sonda efetivação</td><td>`GET efetivacao/sonda`</td><td>`sondaEfetivacao`</td></tr></tbody></table>

### Pós-sucesso em 88e14c87

1. `salvarCredsystemPagamento()` → INSERT em `cred_pagamento` (tipo `DINHEIRO`, situação `EFETIVADO`)
2. `registrarControleAcaoPagamentoCredsystem()` → log tipo `credsystem-recebimento-pagamento`
3. `registraPagamento()` → `registrarReceita()` → `vendarapida::sangriasuprimento` (RECEITA)

### Parâmetros relevantes

- `valorPagamento` — valor efetivo (mínimo, parcela ou total)
- `estornarEmFalha` — default `true`; chama `desfazer` se efetivação falhar após pré-autorização
- `idFormaPagamento` e `idNaturezaLancamento` — da configuração da entidade

</section></section>

# Fluxo de Pagamento Instantâneo e Totem de Autoatendimento

<section class="capitulo" id="bkmrk-fluxo-de-pagamento-i">O cliente pode pagar a fatura pelo Pagamento Instantâneo usando o Código de Resposta Rápida — seja no balcão com o operador ou sozinho no totem de autoatendimento.

<section class="para-todos">## Em linguagem simples

### No balcão (com operador)

1. O operador consulta o Cadastro de Pessoa Física e escolhe pagar com **Pagamento Instantâneo**.
2. Aparece um **Código de Resposta Rápida** na tela.
3. O cliente escaneia com o aplicativo do banco e paga.
4. O sistema fica **verificando** se o pagamento chegou (a cada poucos segundos).
5. Quando confirmado, aparece a mensagem de sucesso.

### No totem (autoatendimento)

1. O cliente toca na tela do totem na loja.
2. O totem abre a página de pagamento instantâneo (`/v1/credsystem-pix`).
3. O cliente digita o Cadastro de Pessoa Física, vê o Código de Resposta Rápida e paga pelo celular.
4. No final, pode dar uma **nota de 1 a 5** sobre o atendimento.

**Importante:** pagamento por Pagamento Instantâneo *não pode ser desfeito* pelo operador depois (diferente do dinheiro/cartão).

</section>![Fluxo de Pagamento Instantâneo e Totem](https://kb.illimitar.pro/uploads/images/gallery/2026-06/embedded-image-gi8czpkb.png)

*Figura 7 — Totem redireciona para `/v1/credsystem-pix`; fluxo Pagamento Instantâneo usa Código de Resposta Rápida, verificação periódica de status e avaliação opcional.*

<section class="para-ti">## Detalhes para Tecnologia da Informação

### Totem — entrada

- `autenticacaoTotem()` em `88e14c87/controle.php`
- Protocolo de Transferência de Hipertexto código 302 → `/v1/credsystem-pix` (Interface do Usuário fora de `bibliotecas/`)

### Endpoints de Pagamento Instantâneo

<table><thead><tr><th>Método 88e14c87</th><th>Interface de Programação de Aplicações 981bfb94</th><th>Endpoint Credsystem</th></tr></thead><tbody><tr><td>`preAutorizacaoPix`</td><td>`preAutorizacaoPix()`</td><td>`POST pre-autorizacao/pix`</td></tr><tr><td>`consultarStatusPixPagamento`</td><td>`consultarStatusPreAutorizacaoPix()`</td><td>`GET pre-autorizacao/sonda/status-pix`</td></tr><tr><td>`confirmarRecebimentoPix`</td><td>—</td><td>Salva em `cred_pagamento` (tipo Pagamento Instantâneo); sem `registrarReceita`</td></tr></tbody></table>

### Consulta repetida de Pagamento Instantâneo

- Protocolo de Transferência de Hipertexto **202** = pagamento ainda pendente; front deve continuar consultando.
- Protocolo de Transferência de Hipertexto **200** com sucesso = Pagamento Instantâneo confirmado.
- Auditoria: `credsystem-pix-pre-autorizacao`, `credsystem-recebimento-pix`

### Satisfação do totem

- `registrarSatisfacaoTotem()` → INSERT em `cred_satisfacao`
- Campos: `cpf_cliente`, `nota` (1–5)

### Imagem de fundo

- Config global: `credsystem_pix_fundo_totem_atracao`
- Criar, Ler, Atualizar e Excluir via `obter/salvar/limpar/exibirFundoTotemAtracao`

</section></section>

# Parcelamento e Consulta de Limite

<section class="capitulo" id="bkmrk-al%C3%A9m-de-pagar-a-fatu">Além de pagar a fatura, o sistema permite consultar o limite de crédito do cliente e contratar um plano de parcelamento na Credsystem.

<section class="para-todos">## Em linguagem simples

Às vezes o cliente não quer pagar tudo de uma vez. O sistema permite:

1. **Consultar o limite** — ver quanto o cliente pode parcelar no cartão.
2. **Simular planos** — ver opções de parcelas (quantas vezes, valor de cada parcela).
3. **Contratar o plano** — o cliente escolhe e o sistema confirma na Credsystem.

O operador faz isso pelo mesmo portal do balcão, depois de consultar o Cadastro de Pessoa Física do cliente.

É como ir à loja e perguntar: "Posso parcelar essa compra em 3 vezes?" — o sistema responde com as opções disponíveis.

</section>![Fluxo de parcelamento](https://kb.illimitar.pro/uploads/images/gallery/2026-06/embedded-image-zytqjrib.png)

*Figura 8 — Consulta de limite retorna planos; contratação confirma o parcelamento na Interface de Programação de Aplicações venda-loja.*

<section class="para-ti">## Detalhes para Tecnologia da Informação

### Endpoints

<table><thead><tr><th>Método 88e14c87</th><th>Método 981bfb94</th><th>Interface de Programação de Aplicações Credsystem</th></tr></thead><tbody><tr><td>`consultarLimiteSituacao`</td><td>`consultarLimiteSituacao()`</td><td>`GET venda-loja/…/limite-situacao` (header `cpf`)</td></tr><tr><td>`contratarPlanoLimite`</td><td>`contratarPlanoVenda()`</td><td>`POST venda-loja/…/venda`</td></tr></tbody></table>

### Payload — consultarLimiteSituacao

```
{
  "codigoEstabelecimento": "…",
  "cpfCliente": "12345678901",
  "valorCompra": 150.00,
  "isInfoPlanos": true
}
```

### Payload — contratarPlanoLimite (obrigatórios)

- `codigoEstabelecimento`, `cpfCliente`
- `codigoPlano`, `parcelas` (≥ 1)
- `valorCompra`, `valorParcela`
- Opcionais: `numeroCartao`, `tipoParcelamento`, `isComJuros`

### Endereço Uniforme de Recurso base

Interface de Programação de Aplicações de venda-loja: `https://apihml.credsystem.com.br/venda-loja/api/v1/` (homologação, definida em `981bfb94`)

</section></section>

# Estorno e Regras de Desfazimento

<section class="capitulo" id="bkmrk-em-alguns-casos%2C-o-o">Em alguns casos, o operador pode cancelar um pagamento já feito — mas existem regras de prazo e tipo de pagamento que precisam ser respeitadas.

<section class="para-todos">## Em linguagem simples

Se o operador cometeu um erro ou o cliente desistiu, é possível **desfazer o pagamento** — mas com estas regras:

<table><thead><tr><th>Regra</th><th>Explicação</th></tr></thead><tbody><tr><td>**Prazo de 24 horas**</td><td>Só dá para desfazer pagamentos feitos nas últimas 24 horas.</td></tr><tr><td>**Pagamento Instantâneo não pode**</td><td>Pagamentos feitos por Pagamento Instantâneo não aparecem na lista de desfazimento.</td></tr><tr><td>**Só pagamentos confirmados**</td><td>Apenas pagamentos com situação "efetivado" (confirmado).</td></tr><tr><td>**Registra saída no caixa**</td><td>O estorno gera uma despesa no Ponto de Venda (dinheiro "sai" do caixa).</td></tr></tbody></table>

Passos para o operador:

1. Consultar o Cadastro de Pessoa Física do cliente.
2. Abrir a lista de pagamentos que podem ser desfeitos.
3. Escolher o pagamento e confirmar o desfazimento.
4. O sistema cancela na Credsystem e registra a despesa no caixa.

</section>![Fluxo de estorno](https://kb.illimitar.pro/uploads/images/gallery/2026-06/embedded-image-k4gbbf8l.png)

*Figura 9 — Estorno: lista filtrada → desfazimento na Credsystem → atualização local → despesa no Ponto de Venda.*

<section class="para-ti">## Detalhes para Tecnologia da Informação

### Constante de prazo

`PRAZO_DESFAZIMENTO_HORAS = 24` em `88e14c87/controle.php`

### Query de listagem (listarPagamentosCredsystemIntegrador)

- `situacao = 'EFETIVADO'`
- `pagamento <> 'PIX'`
- `data_criacao >= NOW() - 24 HOURS`
- Limite: 2000 registros por Cadastro de Pessoa Física

### desfazerPagamento()

1. Valida prazo e existência do registro em `cred_pagamento`
2. Chama `api_integracao_credsystem::desfazer()` → `desfazimento`
3. Atualiza `cred_pagamento.situacao` para `ESTORNADO`
4. `registrarDespesa()` → `vendarapida::sangriasuprimento` (DESPESA, usa `idNaturezaDespesa`)
5. Auditoria: `credsystem-estorno-pagamento`

### Estorno automático em falha

No fluxo `pagamento()` (981bfb94), se `estornarEmFalha=true` (default) e a efetivação falhar após pré-autorização, o sistema chama `desfazer` automaticamente.

</section></section>

# Gestor Mobile — Caixa e Impressora

<section class="capitulo" id="bkmrk-o-aplicativo-gestor-">O aplicativo gestor no celular permite que cada funcionário configure qual caixa e qual impressora vai usar no dia a dia.

<section class="para-todos">## Em linguagem simples

Cada funcionário da loja pode ter um **caixa diferente** e uma **impressora diferente**. O aplicativo gestor no celular guarda essas preferências para não precisar configurar toda vez.

O que o gestor configura:

- **Caixa** — qual ponto de venda o funcionário vai usar.
- **Impressora** — qual impressora vai imprimir os comprovantes (pode ser Bluetooth, USB, rede, ou nenhuma).

Quando o funcionário abre o aplicativo, o sistema **carrega automaticamente** as configurações salvas da última vez.

</section>![Fluxo gestor mobile](https://kb.illimitar.pro/uploads/images/gallery/2026-06/embedded-image-9vdqvlwu.png)

*Figura 10 — O aplicativo gestor salva e carrega configurações por usuário na tabela configuracao\_usuario.*

<section class="para-ti">## Detalhes para Tecnologia da Informação

### Módulo

- Classe: `credsystem_gestor_configuracoes`
- Identificador Universal Único: `857e21c5-203f-4943-b60d-9258bf0ebd7e`
- Rota: `/bibliotecas/857e21c5-…/credsystem_gestor_configuracoes`

### Endpoints

<table><thead><tr><th>Método</th><th>Descrição</th></tr></thead><tbody><tr><td>`salvarConfiguracaoCaixa`</td><td>Persiste configuração de caixa</td></tr><tr><td>`carregarConfiguracaoCaixa`</td><td>Carrega caixa + mescla impressora</td></tr><tr><td>`salvarConfiguracaoImpressora`</td><td>Persiste configuração de impressora</td></tr><tr><td>`carregarConfiguracaoImpressora`</td><td>Carrega só impressora</td></tr></tbody></table>

### Armazenamento

<table><thead><tr><th>descricao</th><th>Conteúdo</th></tr></thead><tbody><tr><td>`gestor_configuracao_caixa`</td><td>Notação de Objetos JavaScript legível (não Codificação Base 64)</td></tr><tr><td>`gestor_configuracao_impresora`</td><td>Notação de Objetos JavaScript com tipo e parâmetros da impressora</td></tr></tbody></table>

Chave: `id_usuario` (resolvido via formulário/dispositivo). Usa `ON DUPLICATE KEY UPDATE`.

Cache de sessão: `setGlobalSession("USUARIO-{id}", descricao, base64(json))` quando disponível.

### Tipos de impressora suportados

`NENHUM`, `BLUETOOTH`, `USB`, `REDE`, `GPOS`, `CLOVER`, `L400POSITIVO`, `POSGETNET`

</section></section>

# Referência Técnica para equipe de Tecnologia da Informação

<section class="capitulo" id="bkmrk-tabelas-de-endpoints">Tabelas de endpoints, rotas, auditoria, integrações externas e dependências — material de consulta rápida para equipes de tecnologia.

<section class="para-todos">## Em linguagem simples

Esta página é um **dicionário técnico** para a equipe de Tecnologia da Informação Ela lista todas as "portas" do sistema (endpoints), onde os dados ficam guardados e como auditar o que aconteceu.

Se você é operador ou gestor, os capítulos anteriores já têm o que precisa. Esta página é para quem instala, configura e dá suporte ao sistema.

</section><section class="para-ti">## Mapa de módulos e rotas

<table><thead><tr><th>Identificador Universal Único</th><th>Classe</th><th>Rota base</th></tr></thead><tbody><tr><td>`981bfb94-afe7-4956-8ecd-4ecbc3b45246`</td><td>`api_integracao_credsystem`</td><td>`/bibliotecas/981bfb94-…/api_integracao_credsystem`</td></tr><tr><td>`88e14c87-331c-485b-95f8-8f63d76d446d`</td><td>`api_integracao_credsystem_pagamento_total`</td><td>`/bibliotecas/88e14c87-…/api_integracao_credsystem_pagamento_total`</td></tr><tr><td>`857e21c5-203f-4943-b60d-9258bf0ebd7e`</td><td>`credsystem_gestor_configuracoes`</td><td>`/bibliotecas/857e21c5-…/credsystem_gestor_configuracoes`</td></tr></tbody></table>

## Integrações externas

<table><thead><tr><th>Sistema</th><th>Protocolo</th><th>Endereço Uniforme de Recurso (homologação)</th></tr></thead><tbody><tr><td>Autorização Aberta Oracle IDCS</td><td>POST client\_credentials</td><td>`https://idcs-…identity.oraclecloud.com/oauth2/v1/token`</td></tr><tr><td>Credsystem Arrecadação</td><td>Transferência Representacional de Estado versão 2</td><td>`https://apihml.credsystem.com.br/arrecadacao-lojista/api/v2/`</td></tr><tr><td>Credsystem Venda-loja</td><td>Transferência Representacional de Estado versão 1</td><td>`https://apihml.credsystem.com.br/venda-loja/api/v1/`</td></tr><tr><td>ILLI Ponto de Venda</td><td>Pré-processador de Hipertexto interno</td><td>`vendarapida::sangriasuprimento`</td></tr><tr><td>Totem de Pagamento Instantâneo Interface do Usuário</td><td>redirecionamento do Protocolo de Transferência de Hipertexto</td><td>`/v1/credsystem-pix`</td></tr></tbody></table>

*Autorização Aberta client\_id e client\_secret estão no código de 981bfb94 — parametrizar para produção; não expor em documentação.*

## Endpoints — Interface de Programação de Aplicações Credsystem (981bfb94)

<table><thead><tr><th>Método Pré-processador de Hipertexto</th><th>Protocolo de Transferência de Hipertexto</th><th>Endpoint Credsystem</th></tr></thead><tbody><tr><td>`consultarTitulos`</td><td>GET</td><td>`consulta-titulo`</td></tr><tr><td>`preAutorizar`</td><td>POST</td><td>`pre-autorizacao`</td></tr><tr><td>`preAutorizarPix`</td><td>POST</td><td>`pre-autorizacao/pix`</td></tr><tr><td>`consultarStatusPreAutorizacao`</td><td>GET</td><td>`pre-autorizacao/sonda/status`</td></tr><tr><td>`consultarStatusPreAutorizacaoPix`</td><td>GET</td><td>`pre-autorizacao/sonda/status-pix`</td></tr><tr><td>`efetivar`</td><td>POST</td><td>`efetivacao`</td></tr><tr><td>`consultarSondaEfetivacao`</td><td>GET</td><td>`efetivacao/sonda`</td></tr><tr><td>`desfazer`</td><td>POST/GET</td><td>`desfazimento`</td></tr><tr><td>`consultarFaturas`</td><td>GET</td><td>`faturas`</td></tr><tr><td>`consultarExtrato`</td><td>GET</td><td>`faturas/extrato/{cod}/vencimento/{data}`</td></tr><tr><td>`consultarTransacoes`</td><td>GET</td><td>`faturas/extrato/…/transacoes`</td></tr><tr><td>`consultarLimiteSituacao`</td><td>GET</td><td>`limite-situacao` (cabeçalho `cpf`)</td></tr><tr><td>`contratarPlanoVenda`</td><td>POST</td><td>`venda`</td></tr><tr><td>`pagamento`</td><td>—</td><td>Orquestra: títulos → pré-autorização → efetivação → sonda</td></tr><tr><td>`pagamentoPix`</td><td>—</td><td>Orquestra fluxo Pagamento Instantâneo com verificação periódica de status</td></tr><tr><td>`getConfiguracaoCredsystem`</td><td>—</td><td>Lê `configuracao_entidade`</td></tr><tr><td>`salvarConfiguracaoCredsystem`</td><td>—</td><td>Grava `api_config_credsystem`</td></tr></tbody></table>

## Endpoints — Pagamento Total (88e14c87)

<table><thead><tr><th>Método Pré-processador de Hipertexto</th><th>Efeito colateral</th></tr></thead><tbody><tr><td>`consultarTitulos`</td><td>Interface de Programação de Aplicações + INSERT `cred_cliente`</td></tr><tr><td>`consultarLimiteSituacao`</td><td>Delega 981bfb94</td></tr><tr><td>`contratarPlanoLimite`</td><td>Delega 981bfb94</td></tr><tr><td>`pagamentoTotal`</td><td>Interface de Programação de Aplicações + `cred_pagamento` + receita no Ponto de Venda + auditoria</td></tr><tr><td>`preAutorizacaoPix`</td><td>Interface de Programação de Aplicações + auditoria de Pagamento Instantâneo</td></tr><tr><td>`consultarStatusPixPagamento`</td><td>Delega 981bfb94</td></tr><tr><td>`confirmarRecebimentoPix`</td><td>`cred_pagamento` (Pagamento Instantâneo) — sem receita no Ponto de Venda</td></tr><tr><td>`desfazerPagamento`</td><td>Interface de Programação de Aplicações desfazer + `ESTORNADO` + despesa no Ponto de Venda</td></tr><tr><td>`listarPagamentosCredsystemIntegrador`</td><td>SELECT `cred_pagamento` (filtros 24h, não-Pagamento Instantâneo)</td></tr><tr><td>`registrarControleImpressao`</td><td>Auditoria impressão correta</td></tr><tr><td>`registrarControleImpressaoIncorreta`</td><td>Auditoria impressão incorreta</td></tr><tr><td>`registrarSatisfacaoTotem`</td><td>INSERT `cred_satisfacao`</td></tr><tr><td>`autenticacaoTotem`</td><td>Protocolo de Transferência de Hipertexto código 302 → `/v1/credsystem-pix`</td></tr><tr><td>`obter/salvar/limpar/exibirFundoTotemAtracao`</td><td>Criar, Ler, Atualizar e Excluir imagem totem</td></tr></tbody></table>

## Banco de dados

<table><thead><tr><th>Tabela / Chave</th><th>Módulo</th><th>Uso</th></tr></thead><tbody><tr><td>`configuracao_entidade.api_config_credsystem`</td><td>981bfb94</td><td>Configuração por loja (Codificação Base 64)</td></tr><tr><td>`configuracao_usuario.gestor_configuracao_caixa`</td><td>857e21c5</td><td>Caixa por usuário</td></tr><tr><td>`configuracao_usuario.gestor_configuracao_impresora`</td><td>857e21c5</td><td>Impressora por usuário</td></tr><tr><td>`configuracao.credsystem_pix_fundo_totem_atracao`</td><td>88e14c87</td><td>Imagem fundo totem</td></tr><tr><td>`{banco}_integrador.cred_cliente`</td><td>88e14c87</td><td>Dados cliente (Notação de Objetos JavaScript)</td></tr><tr><td>`{banco}_integrador.cred_pagamento`</td><td>88e14c87</td><td>Histórico pagamentos</td></tr><tr><td>`{banco}_integrador.cred_satisfacao`</td><td>88e14c87</td><td>índice de satisfação do totem (1–5)</td></tr></tbody></table>

## Auditoria (controle)

Método `controle()` em 88e14c87 registra eventos com campo `tipo`:

<table><thead><tr><th>tipo</th><th>Quando</th></tr></thead><tbody><tr><td>`credsystem-recebimento-pagamento`</td><td>Pagamento convencional efetivado</td></tr><tr><td>`credsystem-pix-pre-autorizacao`</td><td>Código de Resposta Rápida Pagamento Instantâneo gerado</td></tr><tr><td>`credsystem-recebimento-pix`</td><td>Pagamento Instantâneo confirmado</td></tr><tr><td>`credsystem-estorno-pagamento`</td><td>Desfazimento realizado</td></tr><tr><td>`credsystem-comprovante-impressao`</td><td>Comprovante impresso corretamente</td></tr><tr><td>`credsystem-comprovante-impressao-incorreta`</td><td>Erro na impressão</td></tr></tbody></table>

## Regras de negócio (constantes)

<table><thead><tr><th>Regra</th><th>Valor</th><th>Arquivo</th></tr></thead><tbody><tr><td>Prazo estorno</td><td>24 horas</td><td>`88e14c87/controle.php` — `PRAZO_DESFAZIMENTO_HORAS`</td></tr><tr><td>Pagamento Instantâneo estornável</td><td>Não</td><td>Filtro Linguagem de Consulta Estruturada `pagamento <> 'PIX'`</td></tr><tr><td>Pagamento Instantâneo gera receita no Ponto de Venda</td><td>Não</td><td>`confirmarRecebimentoPix` sem `registrarReceita`</td></tr><tr><td>Estorno automático em falha</td><td>Default true</td><td>`estornarEmFalha` em `pagamento()`</td></tr><tr><td>Consulta repetida de Pagamento Instantâneo pendente</td><td>Protocolo de Transferência de Hipertexto código 202</td><td>`consultarStatusPreAutorizacaoPix`</td></tr></tbody></table>

## Dependências compartilhadas

- `APPPATH/controllers/bibliotecas/12262a22-30ab-11e9-bb4c-127101af6b0d/util.php` — utilitários de banco de dados, entidades e consultas
- `APPPATH/controllers/pdv/vendarapida.php` — sangria/suprimento (receita/despesa)
- `APPPATH/controllers/biblioteca.php` — classe base biblioteca
- Guzzle para Protocolo de Transferência de Hipertexto — usado em `981bfb94` para chamadas de Transferência Representacional de Estado

## Arquivos-fonte principais

<table><thead><tr><th>Arquivo</th><th>Linhas aprox.</th><th>Conteúdo</th></tr></thead><tbody><tr><td>`bibliotecas/981bfb94-…/controle.php`</td><td>~1700</td><td>Cliente de Transferência Representacional de Estado Credsystem completo</td></tr><tr><td>`bibliotecas/88e14c87-…/controle.php`</td><td>~1710</td><td>Orquestração pagamento, Ponto de Venda, totem</td></tr><tr><td>`bibliotecas/88e14c87-…/visual.html`</td><td>~2000</td><td>Portal Vue 3</td></tr><tr><td>`bibliotecas/88e14c87-…/instalador.php`</td><td>~110</td><td>Migrações v1–v4</td></tr><tr><td>`bibliotecas/981bfb94-…/visual.html`</td><td>—</td><td>Config Quasar</td></tr><tr><td>`bibliotecas/857e21c5-…/controle.php`</td><td>~460</td><td>Configuração do gestor</td></tr></tbody></table>

</section>![Resumo dependências](https://kb.illimitar.pro/uploads/images/gallery/2026-06/embedded-image-mm0nklzt.png)

*Figura 11 — Mapa resumido de módulos e dependências externas ao diretório bibliotecas/.*

</section>