# 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 style="width:100%;height:201px;"><thead><tr style="height:30.125px;"><th style="width:25.2431%;height:30.125px;">Identificador Universal Único</th><th style="width:26.9817%;height:30.125px;">Classe</th><th style="width:47.6165%;height:30.125px;">Função</th></tr></thead><tbody><tr style="height:46.9167px;"><td style="width:25.2431%;height:46.9167px;">`981bfb94-afe7-4956-8ecd-4ecbc3b45246`</td><td style="width:26.9817%;height:46.9167px;">`api_integracao_credsystem`</td><td style="width:47.6165%;height:46.9167px;">Cliente de Transferência Representacional de Estado/Autorização Aberta Credsystem</td></tr><tr style="height:46.9167px;"><td style="width:25.2431%;height:46.9167px;">`88e14c87-331c-485b-95f8-8f63d76d446d`</td><td style="width:26.9817%;height:46.9167px;">`api_integracao_credsystem_pagamento_total`</td><td style="width:47.6165%;height:46.9167px;">Portal, totem, Ponto de Venda, banco integrador</td></tr><tr style="height:46.9167px;"><td style="width:25.2431%;height:46.9167px;">`857e21c5-857e21c5-203f-4943-b60d-9258bf0ebd7e`</td><td style="width:26.9817%;height:46.9167px;">`credsystem_gestor_configuracoes`</td><td style="width:47.6165%;height:46.9167px;">Config caixa/impressora por usuário</td></tr><tr style="height:30.125px;"><td style="width:25.2431%;height:30.125px;">`f3d67c71-a1f9-4709-a81f-de0a4bb1f6e6`</td><td style="width:26.9817%;height:30.125px;">`configCredsystem`</td><td style="width:47.6165%;height:30.125px;">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>

# Documentação [Via BASE/GESTOR]

Guia simples para configurar e usar no dia a dia.

<div class="wrap" id="bkmrk-neste-documento1.-co"><div class="toc">**Neste documento**</div><div class="toc">1. [Instalação dos Apps](#bkmrk-1.-configurar-a-inte)  
2. [Configurar a integração](#bkmrk-2.-configurar-a-inte)  
3. [Configurar o totem (Visual)](#bkmrk-2b-config-totem)  
4. [Impressora no Gestor](#bkmrk-2.-impressora-no-ges)</div></div>
###   
Versão: 1.2.0 (Bibliotecas/Módulos)  
  
Configuração de infraestrutura NGINX

  
Antes de iniciar a configuração da integração, é necessário abrir um chamado para a equipe de **DevOps** solicitando a configuração do **Nginx** da loja/ambiente onde a integração será utilizada. Essa configuração é indispensável para permitir a comunicação correta entre o ILLI e os serviços da Credsystem. Como referência para o escopo da solicitação, utilize o chamado **SIC-14670**, adaptando as informações conforme o ambiente e a loja que será configurada. Somente após a conclusão desse chamado prossiga com as etapas de configuração da integração.  
Modelo do chamado: [https://illimitar.atlassian.net/browse/SIC-14670](https://illimitar.atlassian.net/browse/SIC-14670)

### Caso os módulos da Credsystem não apareçam no portal  


Neste caso, deve ser aberto um chamado para atualizar o portal para a equipe do NOC  
É preciso entender para aonde o portal está sendo apontado para ser gerado a atualização no Portainer   
Seguir esse Jira de exemplo: [https://illimitar.atlassian.net/browse/NOC-42](https://illimitar.atlassian.net/browse/NOC-42)

\----------------------------------------------------------------------------------------------------------------------------------

## 1. Instalação dos Apps

Na sua base acesse a IlliStore, precisamos instalar os 3 Apps e conferir se as bibliotecas,funções de acesso e módulos de acesso, abaixo foram importadas.  
Obs: Apesar de no print estar com # no nome, a busca deve ser feita com @, conforme lista abaixo.  
  
**Apps:**  
@I-SNP-337  
@I-SNP-337M  
@I-SNP-337MM

[![foto.png](https://kb.illimitar.pro/uploads/images/gallery/2026-09/scaled-1680-/foto.png)](https://kb.illimitar.pro/uploads/images/gallery/2026-09/foto.png)

[![app.png](https://kb.illimitar.pro/uploads/images/gallery/2026-07/scaled-1680-/app.png)](https://kb.illimitar.pro/uploads/images/gallery/2026-07/app.png)

[![app1.png](https://kb.illimitar.pro/uploads/images/gallery/2026-07/scaled-1680-/app1.png)](https://kb.illimitar.pro/uploads/images/gallery/2026-07/app1.png)

**Bibliotecas instaladas:**  
\* 981bfb94-afe7-4956-8ecd-4ecbc3b45246  
\* 88e14c87-331c-485b-95f8-8f63d76d446d  
\* 857e21c5-203f-4943-b60d-9258bf0ebd7e  
\* f3d67c71-a1f9-4709-a81f-de0a4bb1f6e6  
  
**Funções de acesso:**  
\* Credsystem (Desfazer)  
\* Credsystem (Limite)  
\* Credsystem (PIX)  
\* Credsystem (Dinheiro)  
  
**Módulos de Acesso** \* CONFIGURAÇÃO GERAL  
\* CONFIGURAÇÃO TOTEM IMPRESSORA  
\* CREDSYSTEM (PIX)  
  
O Usuário que tiver acesso ao PDV e ao TOTEM deverá ter acesso ao Gestor e aos módulos da Credsystem  
Caso não tenha, pode dar erro de: Usuário não autenticado

\----------------------------------------------------------------------------------------------------------------------------------

## 2. Configurar a integração

A configuração da Credsystem deve ser feita via GESTOR.  
No módulo "CREDSYSTEM" &gt; **CONFIGURAÇÃO GERAL**. Nela há dois blocos principais:  
 \* **Configurações (Gerais)** (credenciais, URLs da API e outros)  
 \* **Configurações (Totem)** (aparência e timeouts e outros).

Em **Configurações (Gerais)**, insira as credenciais da Credsystem **por entidade**.  
Sempre selecione a **Entidade** correta antes de editar ou salvar — cada loja possui sua própria configuração.

<div class="wrap" id="bkmrk-tela-de-configura%C3%A7%C3%A3o"><figure class="print"><figcaption>Tela de configuração — Configurações (Gerais)  
[![Configurações Gerais — credenciais OAuth e URLs](https://kb.illimitar.pro/uploads/images/gallery/2026-07/scaled-1680-/9kE001.png)](https://kb.illimitar.pro/uploads/images/gallery/2026-07/9kE001.png)</figcaption></figure></div>**Passo a passo — Configurações (Gerais)**

<div class="wrap" id="bkmrk-escolha-a-entidade-%28">1. Expanda **Configurações (Gerais)**.
2. Escolha a **Entidade** (loja) que será configurada.
3. Em **Acesso da loja**, preencha **Usuário** e **Senha**.
4. Em **Credenciais OAuth**, preencha **Client ID**, **Client Secret** e **Scope**.
5. Em **URLs dos serviços**, confira as 3 URLs (homologação ou produção, conforme o ambiente).
6. Em **Parâmetros ILLI**, preencha **Bandeira** e os IDs do ILLI (forma de pagamento, natureza receita e natureza despesa).
7. Clique em **Salvar configuração**.

</div>### O que cada campo significa

<div class="wrap" id="bkmrk-entidade-loja-que-es"><table style="width:98.4524%;"><tbody><tr><th style="width:40.1244%;">Entidade</th><td style="width:59.7201%;">Loja que está sendo configurada.

</td></tr><tr><th style="width:40.1244%;">Usuário</th><td style="width:59.7201%;">Usuário da loja

</td></tr><tr><th style="width:40.1244%;">Senha</th><td style="width:59.7201%;">Senha da loja

</td></tr><tr><th style="width:40.1244%;">Client ID</th><td style="width:59.7201%;">Usuário técnico da API.</td></tr><tr><th style="width:40.1244%;">Client Secret</th><td style="width:59.7201%;">Senha técnica da API.</td></tr><tr><th style="width:40.1244%;">Scope</th><td style="width:59.7201%;">Permissão do token.</td></tr><tr><th style="width:40.1244%;">URL Base Arrecadação</th><td style="width:59.7201%;">Endereço para pagamentos e títulos.</td></tr><tr><th style="width:40.1244%;">URL Base Venda Loja</th><td style="width:59.7201%;">Endereço para limite e planos.</td></tr><tr><th style="width:40.1244%;">URL OAuth</th><td style="width:59.7201%;">Endereço para gerar o token.</td></tr><tr><th style="width:40.1244%;">Bandeira</th><td style="width:59.7201%;">Em geral `OBJETIVA`.</td></tr><tr><th style="width:40.1244%;">ID forma de pagamento</th><td style="width:59.7201%;">Código da forma Credsystem no ILLI.</td></tr><tr><th style="width:40.1244%;">ID natureza receita</th><td style="width:59.7201%;">Natureza do recebimento.</td></tr><tr><th style="width:40.1244%;">ID natureza despesa</th><td style="width:59.7201%;">Natureza do estorno/desfazimento.</td></tr></tbody></table>

</div>  
Configuração de exemplo para HML (Ambiente de Homologação)  
{  
"idEntidade": "2",  
"usuario": "31089",  
"senha": "3164",  
"clientId": "ff7dc433ef86403089be6654694f034b",  
"clientSecret": "idcscs-e35fbaf0-bc15-42d7-a3d8-b3e7aefa70bd",  
"scope": "OBJETIVA-HML-8b3d3093-0869-4479-9bc2-9f56998214de",  
"urlBaseArrecadacao": "[https://apihml.credsystem.com.br/arrecadacao-lojista/api/v2/](https://apihml.credsystem.com.br/arrecadacao-lojista/api/v2/)",  
"urlBaseVendaLoja": "[https://apihml.credsystem.com.br/venda-loja/api/v1/](https://apihml.credsystem.com.br/venda-loja/api/v1/)",  
"urlOauth": "[https://idcs-0fe1bec59571471484a8896c1a0d7a62.identity.oraclecloud.com/oauth2/v1/token](https://idcs-0fe1bec59571471484a8896c1a0d7a62.identity.oraclecloud.com/oauth2/v1/token)",  
"bandeira": "OBJETIVA",  
"idFormaPagamento": "1",  
"idNaturezaLancamento": "78",  
"idNaturezaDespesa": "79"  
}

\----------------------------------------------------------------------------------------------------------------------------------

## 3. Configurar o totem (Visual)

Na mesma tela, expanda **Configurações (Totem)** para ajustar tempos de uso e a aparência do totem Credsystem PIX.  
As alterações de imagem/cor são aplicadas após salvar e, em geral, após recarregar a página do totem.

O bloco do totem está organizado em:

- **Configurações gerais** — retorno por inatividade e revelação do CPF
- **Tela Principal** — imagem, cor e pulsar da tela inicial
- **Telas Internas** — imagem e cor das etapas de CPF, pagamento e sucesso

### 3.1 Configurações gerais do totem

#### Retorno por inatividade

Define por quanto tempo o totem aguarda sem toque ou tecla nas telas internas (CPF, pagamento e sucesso) antes de voltar automaticamente para a tela inicial.

- Campo: **Tempo sem atividade** (em segundos)
- Intervalo permitido: **1 a 3600** segundos
- Padrão: **30 segundos**
- Clique em **Salvar tempo** para gravar

<figure class="print" id="bkmrk-fig-inatividade">[![Retorno por inatividade](https://kb.illimitar.pro/uploads/images/gallery/2026-07/scaled-1680-/002.png)](https://kb.illimitar.pro/uploads/images/gallery/2026-07/002.png)</figure>#### Revelação do CPF

Define por quanto tempo o CPF fica legível após o cliente tocar no ícone de olho na tela de digitação.  
Toque de novo no olho oculta de imediato.

- Campo: **Tempo com CPF revelado** (em segundos)
- Intervalo permitido: **1 a 60** segundos
- Padrão: **3 segundos**
- Clique em **Salvar tempo** para gravar

<figure class="print" id="bkmrk-fig-cpf">[![Revelação do CPF](https://kb.illimitar.pro/uploads/images/gallery/2026-07/scaled-1680-/003.png)](https://kb.illimitar.pro/uploads/images/gallery/2026-07/003.png)</figure>### 3.2 Tela Principal

Configura a tela de atração (tela inicial) do totem: imagem de fundo, cor de fundo e indicador pulsante.  
**Imagem e cor são mutuamente exclusivas:** se houver imagem configurada, a cor fica indisponível até a imagem ser removida.

#### Imagem de fundo da tela inicial

Envie a imagem da tela de atração do totem. Sem arquivo, permanece o layout padrão. Com imagem, ela substitui fundo e textos iniciais.

- Formatos: **JPG, PNG, WEBP ou GIF**
- Tamanho máximo: **8 MB**
- Tamanho recomendado: **970 px (largura) × 1705 px (altura)**
- Use **Escolher imagem** para selecionar o arquivo e **Enviar** para salvar
- Use **Remover imagem** para voltar ao layout padrão / permitir definir a cor de fundo

<figure class="print" id="bkmrk-fig-img-inicial">[![Imagem de fundo da tela inicial](https://kb.illimitar.pro/uploads/images/gallery/2026-07/scaled-1680-/004.png)](https://kb.illimitar.pro/uploads/images/gallery/2026-07/004.png)</figure>#### Cor de fundo da tela inicial

Escolha a cor de fundo quando não há imagem configurada. Se houver imagem de fundo selecionada, a tela exibe o aviso de que a cor está indisponível — remova a imagem para poder definir a cor.

- Presets: Credsystem, Azul escuro, Verde, Vinho, Grafite e Personalizada
- A pré-visualização mostra como a tela inicial fica com a cor escolhida
- Clique em **Salvar cor** para gravar

<figure class="print" id="bkmrk-fig-cor-inicial">[![Cor de fundo da tela inicial](https://kb.illimitar.pro/uploads/images/gallery/2026-07/scaled-1680-/005.png)](https://kb.illimitar.pro/uploads/images/gallery/2026-07/005.png)</figure>#### Pulsar

Escolha a posição do indicador pulsante na grade 3×3 e personalize o texto exibido abaixo dele na tela inicial do totem.

- **Exibir pulsar**: liga ou desliga o indicador
- **Texto do pulsar / Mensagem**: até **60 caracteres** (padrão: “Toque em qualquer lugar”)
- **Posição na tela**: grade 3×3 (ex.: Inferior centro)
- Use a pré-visualização como referência aproximada
- Clique em **Salvar pulsar** para gravar

<figure class="print" id="bkmrk-fig-pulsar">[![Configuração do Pulsar](https://kb.illimitar.pro/uploads/images/gallery/2026-07/scaled-1680-/006.png)](https://kb.illimitar.pro/uploads/images/gallery/2026-07/006.png)</figure>### 3.3 Telas Internas

Configura o fundo das etapas após a tela inicial (CPF, pagamento e sucesso). Assim como na tela principal, imagem e cor são alternativas: sem imagem, usa-se a cor escolhida (ou o layout padrão).

#### Imagem de fundo das telas internas

Envie a imagem de fundo das etapas internas. Sem arquivo, permanece o layout padrão (ou a cor escolhida abaixo).

- Formatos: **JPG, PNG, WEBP ou GIF**
- Tamanho máximo: **8 MB**
- Tamanho recomendado: **970 px (largura) × 1705 px (altura)**
- Use **Escolher imagem** e depois **Enviar**

<figure class="print" id="bkmrk-fig-img-internas">[![Imagem de fundo das telas internas](https://kb.illimitar.pro/uploads/images/gallery/2026-07/scaled-1680-/007.png)](https://kb.illimitar.pro/uploads/images/gallery/2026-07/007.png)</figure>#### Cor de fundo das telas internas

Escolha a cor de fundo quando não há imagem configurada nas telas internas. A cor é salva no servidor e aplicada após recarregar a página.

- Presets: Credsystem, Azul escuro, Verde, Vinho, Grafite e Personalizada
- A pré-visualização mostra um mockup das telas internas com a cor escolhida
- Clique em **Salvar cor** para gravar

<figure class="print" id="bkmrk-fig-cor-internas">[![Cor de fundo das telas internas](https://kb.illimitar.pro/uploads/images/gallery/2026-07/scaled-1680-/008.png)](https://kb.illimitar.pro/uploads/images/gallery/2026-07/008.png)</figure><div class="wrap" id="bkmrk--10"></div><div class="wrap" id="bkmrk--11"></div><div class="wrap" id="bkmrk--12"></div>## 4. Impressora no Gestor

Para o comprovante sair no caixa, configure a impressora do operador no Gestor.  
[![gestorConfig.png](https://kb.illimitar.pro/uploads/images/gallery/2026-07/scaled-1680-/gestorconfig.png)](https://kb.illimitar.pro/uploads/images/gallery/2026-07/gestorconfig.png)

<div class="wrap" id="bkmrk-tipo-de-impressora-b"><table><tbody><tr><th>Tipo de impressora</th><td>Bluetooth, USB, Rede, GPOS, Clover… ou Nenhum.</td></tr><tr><th>Nome do dispositivo</th><td>Nome da impressora.</td></tr><tr><th>MAC (Bluetooth)</th><td>Endereço da impressora Bluetooth.</td></tr><tr><th>IP e Porta (Rede)</th><td>Usados no tipo Rede (porta comum: 9100).</td></tr><tr><th>Colunas</th><td>Largura do cupom (ex.: 48).</td></tr></tbody></table>

</div>Salve e faça um teste de impressão.

Credsystem × ILLI · Guia do usuário

# Documentação [Via PDV]

<main class="wrap" id="bkmrk-1.-como-acessar-os-m"><section id="bkmrk-1.-como-acessar-os-m-1">## 1. Como acessar os módulos

Todos os módulos Credsystem ficam no menu do PDV, em **Outras funções**.

1. Abra o **PDV** (tela do caixa).
2. Abra o **Menu**.
3. Em **Outras funções**, escolha o módulo desejado:

#### Credsystem (Dinheiro)

Receber pagamento em dinheiro.  
<span class="atalho">ALT+SHIFT+A</span>

#### Credsystem (PIX)

Receber pagamento via PIX.  
<span class="atalho">ALT+SHIFT+B</span>

#### Credsystem (Limite)

Consultar limite e situação do cartão.  
<span class="atalho">ALT+SHIFT+C</span>

#### Credsystem (Desfazer)

Estornar um pagamento já feito.

<figure class="shot">![Menu Outras funções com os quatro módulos Credsystem](https://kb.illimitar.pro/uploads/images/gallery/2026-07/embedded-image-f2hlqqns.png)<figcaption>Menu Outras funções com os quatro módulos Credsystem</figcaption></figure><div class="dica">**Dica:** você também pode usar os atalhos de teclado mostrados no menu para abrir o módulo mais rápido.</div></section><section id="bkmrk-2-credsystem-%28dinhei">## <span class="num">2</span> Credsystem (Dinheiro)

Use este módulo para receber o pagamento de títulos Credsystem em **dinheiro**.

### Passo a passo

1. No menu, abra **Credsystem (Dinheiro)**.
2. Na tela **Consulta por CPF**, digite o CPF do cliente (somente números). A máscara é aplicada automaticamente.
3. Pressione **Enter** ou clique em **Consultar**.

<figure class="shot">![Tela inicial: consulta por CPF — Credsystem (Dinheiro)](https://kb.illimitar.pro/uploads/images/gallery/2026-07/embedded-image-ayl5skyc.png)<figcaption>  
</figcaption></figure><figure class="shot">![CPF preenchido, pronto para consultar](https://kb.illimitar.pro/uploads/images/gallery/2026-07/embedded-image-si6u0mhe.png)<figcaption>  
</figcaption></figure>4. Confira os **dados do cliente** (nome, CPF e aniversário).
5. Veja o título em aberto (extrato, valor, encargos).
6. Em **Ação**, escolha quanto receber: 
    - **Total sem Seguro** — valor total;
    - **Mínimo** — quando disponível;
    - **Outro Valor** — digite o valor desejado.
7. Clique em **Receber**.
8. Na janela **Confirmar recebimento**, confira o CPF e o valor e clique em **Confirmar recebimento**.

<figure class="shot">![Confirmação do recebimento em dinheiro](https://kb.illimitar.pro/uploads/images/gallery/2026-07/embedded-image-hw5v4ncs.png)<figcaption>  
</figcaption></figure>9. Após o sucesso, o sistema pergunta: *“O comprovante de pagamento foi impresso corretamente?”*
10. Confira o papel da impressora. Se estiver ok, clique em **Sim**. Se não, clique em **Não** para registrar a ocorrência e gerar nova via.
11. Use **Nova Consulta** para atender outro cliente.

<figure class="shot">![Pergunta sobre a impressão do comprovante após o pagamento](https://kb.illimitar.pro/uploads/images/gallery/2026-07/embedded-image-majuqflx.png)<figcaption>Pergunta sobre a impressão do comprovante após o pagamento</figcaption></figure><div class="ok">Quando o recebimento concluir, a tela mostra a mensagem de sucesso e o toast “Pagamento concluído”.</div></section><section id="bkmrk-3-credsystem-%28pix%29-u">## <span class="num">3</span> Credsystem (PIX)

Use este módulo para o cliente pagar títulos Credsystem via **PIX** (QR Code ou copia e cola).

### Passo a passo

1. No menu, abra **Credsystem (PIX)**.
2. Informe o **CPF do cliente** (somente números) e clique em **Consultar** (ou Enter).

<figure class="shot">![Consulta por CPF — Credsystem (PIX)](https://kb.illimitar.pro/uploads/images/gallery/2026-07/embedded-image-qbu6jtjq.png)<figcaption>Consulta por CPF — Credsystem (PIX)</figcaption></figure>3. Confira os dados do cliente e o título em aberto.
4. Escolha o valor a receber (total, mínimo ou outro valor) e clique em **Receber**.
5. Na tela **Forma de recebimento**, escolha **PIX**.

<figure class="shot">[![Captura de Tela 2026-08-05 às 14.43.55.png](https://kb.illimitar.pro/uploads/images/gallery/2026-08/scaled-1680-/captura-de-tela-2026-08-05-as-14-43-55.png)](https://kb.illimitar.pro/uploads/images/gallery/2026-08/captura-de-tela-2026-08-05-as-14-43-55.png)  
<figcaption>  
</figcaption></figure>6. Na tela **Pagamento via PIX**: 
    - Peça ao cliente para **escanear o QR Code**; ou
    - Clique em **Copiar** e envie o código **PIX copia e cola**.
7. Aguarde a mensagem *“Aguardando confirmação do pagamento na Credsystem…”* até a confirmação automática.

<figure class="shot">![Tela com QR Code e código PIX copia e cola](https://kb.illimitar.pro/uploads/images/gallery/2026-07/embedded-image-7jkbonw5.png)<figcaption>  
</figcaption></figure><div class="aviso">**Importante:** depois que o PIX é pago, **não há estorno por este canal**. O valor fica na Conta Credsystem. Confira o valor antes de o cliente pagar. Qualquer correção depende do procedimento combinado com a Credsystem.</div><div class="dica">O valor do PIX é contabilizado na Credsystem — **não gera receita no fluxo local** do caixa.</div></section><section id="bkmrk-4-credsystem-%28limite">## <span class="num">4</span> Credsystem (Limite)

Use este módulo para consultar o **limite disponível** e a **situação do cartão** do cliente.

### Passo a passo

1. No menu, abra **Credsystem (Limite)**.
2. Digite o **CPF do cliente** (somente números).
3. Pressione **Enter** ou clique no botão **Limite**.
4. As informações abrem em uma nova página.

<figure class="shot">![Consulta de limite por CPF](https://kb.illimitar.pro/uploads/images/gallery/2026-07/embedded-image-xu8suma7.png)<figcaption>Consulta de limite por CPF</figcaption></figure>### O que aparece no resultado

- **Documento** e **Nome do cliente**
- **Número do cartão**
- **Limite disponível para compras**
- **Vencimento do extrato**
- **Situação do cartão**
- **Cartão seguro** (Sim/Não)
- **Limite extra disponível** (quando houver plano extra)

<figure class="shot">![Resultado da consulta de limite e situação do cartão](https://kb.illimitar.pro/uploads/images/gallery/2026-07/embedded-image-8xhmv5l4.png)<figcaption>Resultado da consulta de limite e situação do cartão</figcaption></figure>### Simular parcelas

1. No quadro **Simular Parcelas**, informe o **valor da compra**.
2. Clique em **Simular parcelas** para ver as opções.
3. Para voltar à busca, use **Voltar à consulta**.

</section><section id="bkmrk-5-credsystem-%28desfaz">## <span class="num">5</span> Credsystem (Desfazer)

Use este módulo para **estornar** um pagamento já registrado na Credsystem.  
<span style="color:rgb(224,62,45);">**Apenas pagamentos com menos de 24h podem ser desfeitos**</span>

### Passo a passo

1. No menu, abra **Credsystem (Desfazer)**.
2. Informe o **CPF do cliente** e clique em **Consultar** (ou Enter).

<figure class="shot">![Consulta por CPF — Credsystem (Desfazer)](https://kb.illimitar.pro/uploads/images/gallery/2026-07/embedded-image-e21jduii.png)<figcaption>Consulta por CPF — Credsystem (Desfazer)</figcaption></figure>3. Confira os **dados do cliente**.
4. Na lista **Pagamentos registrados**, localize o pagamento desejado (data/hora, autorização, valor, forma e situação).
5. Clique em **Estornar** na linha do pagamento.

<figure class="shot">![Lista de pagamentos com o botão Estornar](https://kb.illimitar.pro/uploads/images/gallery/2026-07/embedded-image-gc0fkdzr.png)<figcaption>Lista de pagamentos com o botão Estornar</figcaption></figure>6. Na janela **Confirmar desfazimento**, confira autorização, estabelecimento, identificador e valor.
7. Clique em **Confirmar desfazimento** (botão vermelho) para solicitar o estorno à Credsystem.

<figure class="shot">![Confirmação do desfazimento / estorno](https://kb.illimitar.pro/uploads/images/gallery/2026-07/embedded-image-no5ssosw.png)<figcaption>Confirmação do desfazimento / estorno</figcaption></figure>8. Quando o estorno concluir, confira se o **comprovante de estorno** saiu corretamente na impressora.
9. Responda **Sim** ou **Não**. Em “Não”, o sistema registra a ocorrência e envia nova via.
10. Use **Nova consulta** para outro CPF.

<figure class="shot">![Confirmação da impressão do comprovante de estorno](https://kb.illimitar.pro/uploads/images/gallery/2026-07/embedded-image-b6obsaal.png)<figcaption>Confirmação da impressão do comprovante de estorno</figcaption></figure><div class="aviso">O estorno é uma ação definitiva junto à Credsystem. Confira sempre autorização e valor antes de confirmar.</div></section><section id="bkmrk-6-dicas-gerais-para-">## <span class="num">6</span> Dicas gerais para o caixa

<table><thead><tr><th>Situação</th><th>O que fazer</th></tr></thead><tbody><tr><td>Digitar CPF</td><td>Use só números. A máscara (000.000.000-00) é aplicada sozinha.</td></tr><tr><td>CPF inválido</td><td>O Enter / botão só envia quando o CPF estiver completo e válido.</td></tr><tr><td>Comprovante não saiu</td><td>Responda **Não** na pergunta de impressão para gerar nova via.</td></tr><tr><td>PIX pago errado</td><td>Não dá para estornar pelo canal PIX do PDV. Siga o procedimento com a Credsystem.</td></tr><tr><td>Trocar de cliente</td><td>Use o botão **Nova consulta**.</td></tr><tr><td>Fechar o módulo</td><td>Clique no **X** no canto superior direito da janela.</td></tr></tbody></table>

<div class="dica">**Resumo do caminho:** PDV → Menu → Outras funções → Credsystem (Dinheiro / PIX / Limite / Desfazer).</div></section></main>