CREDSYSTEM (PDV+TOTEM) Integração Credsystem — Introdução 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. Í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 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: Portal no computador — o operador atende o cliente no balcão. Totem de Pagamento Instantâneo — o cliente paga sozinho na tela de autoatendimento. 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. 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 Cadastro de Pessoa Física Número de identificação do cliente. É usado para buscar a fatura dele. Extrato / Fatura Conta que o cliente precisa pagar. Pode ter valor total, valor mínimo ou parcelas. Entidade / Loja Cada unidade de negócio cadastrada no ILLI. Cada loja tem sua própria configuração. Caixa O ponto de venda onde o operador trabalha. O pagamento pode gerar uma entrada de dinheiro no caixa. Pré-autorização Passo em que a Credsystem reserva o pagamento antes de confirmar de vez. É como "segurar" o valor. Efetivação Confirmação final do pagamento na Credsystem. Estorno / Desfazimento Cancelar um pagamento que já foi feito. Só é permitido em alguns casos e dentro de um prazo. Pagamento Instantâneo Forma de pagamento instantânea pelo celular, usando Código de Resposta Rápida. Totem Tela de autoatendimento na loja, onde o cliente paga sozinho pelo Pagamento Instantâneo. Integrador Banco de dados auxiliar que guarda histórico de clientes, pagamentos e avaliações do totem. Ponto de Venda Sistema de ponto de venda do ILLI. Registra entradas e saídas de dinheiro no caixa. 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: Identificador Universal Único Classe Função 981bfb94-afe7-4956-8ecd-4ecbc3b45246 api_integracao_credsystem Cliente de Transferência Representacional de Estado/Autorização Aberta Credsystem 88e14c87-331c-485b-95f8-8f63d76d446d api_integracao_credsystem_pagamento_total Portal, totem, Ponto de Venda, banco integrador 857e21c5-857e21c5-203f-4943-b60d-9258bf0ebd7e credsystem_gestor_configuracoes Config caixa/impressora por usuário f3d67c71-a1f9-4709-a81f-de0a4bb1f6e6 configCredsystem Tela legada (substituída pela Quasar em 981bfb94) 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. Arquitetura — Como os módulos se conectam 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. 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. 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. Detalhes para Tecnologia da Informação Camadas Camada Módulo Responsabilidade Apresentação 88e14c87/visual.html Vue 3 — portal operador Apresentação /v1/credsystem-pix Interface do Usuário do Totem de Pagamento Instantâneo (fora de bibliotecas/) Apresentação 981bfb94/visual.html Quasar — configuração por entidade Negócio 88e14c87/controle.php Orquestração, Ponto de Venda, integrador, auditoria Integração 981bfb94/controle.php Autorização Aberta versão 2 + Guzzle → Interface de Programação de Aplicações Credsystem Configuração mobile 857e21c5/controle.php configuracao_usuario 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 Instalação e Banco de Dados Antes de usar o sistema, é preciso instalar os módulos e criar as tabelas que guardam clientes, pagamentos e avaliações do totem. 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. Figura 3 — Ordem das migrações do instalador (88e14c87): v1 cria o banco; v2, v3 e v4 criam as tabelas. 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 Versão Ação v1 CREATE DATABASE IF NOT EXISTS {banco}_integrador v2 Cria tabela cred_cliente (Notação de Objetos JavaScript: cpf, nome, codigoCliente, diaMesNascimento) v3 Cria tabela cred_pagamento ( cpf, entidade, usuário, caixa, valor Notação de Objetos JavaScript, tipo, situação) v4 Cria tabela cred_satisfacao ( cpf, nota 1–5) Schema cred_pagamento Coluna Tipo Descrição cpf_cliente varchar(14) Cadastro de Pessoa Física sem formatação id_entidade int Loja/entidade id_usuario int Operador id_caixa int Caixa do Ponto de Venda valor Notação de Objetos JavaScript Detalhes do pagamento pagamento varchar DINHEIRO ou PIX situacao varchar EFETIVADO ou ESTORNADO Outros módulos 981bfb94 — instalador vazio (sem migrações). 857e21c5 — usa tabela existente configuracao_usuario. Ordem recomendada de instalação Instalar 981bfb94 (Interface de Programação de Aplicações Credsystem) Instalar 88e14c87 (executar v1 → v4) Instalar 857e21c5 (gestor) Configurar entidade (capítulo 04) Configuração por Loja / Entidade 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. 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: Selecionar a loja (entidade) no menu. Usuário e senha fornecidos pela Credsystem. Endereços das Interfaces de Programação de Aplicações (links de conexão — a equipe de Tecnologia da Informação recebe da Credsystem). Forma de pagamento e natureza — para o caixa registrar corretamente a entrada de dinheiro. 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. Figura 4 — A configuração é salva por entidade e lida por todos os módulos que operam pagamentos. 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 Campo Descrição idEntidade ID da entidade/loja usuario Usuário Credsystem senha Senha Credsystem (não expor em logs) urlArrecadacao 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) urlLimite Endereço Uniforme de Recurso Interface de Programação de Aplicações limite/venda bandeira Bandeira do cartão (ex.: OBJETIVA) idFormaPagamento ID forma de pagamento no Ponto de Venda para receita idNaturezaLancamento Natureza contábil da receita idNaturezaDespesa Natureza contábil da despesa (estorno) 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. Portal do Operador — Uso no Balcão O portal é a tela que o operador usa no computador para consultar a fatura do cliente, receber pagamentos e imprimir comprovantes. Em linguagem simples O operador abre o portal no navegador e segue estes passos: Digitar o Cadastro de Pessoa Física do cliente e clicar em consultar. Ver os extratos (faturas) que aparecem na tela — valor total, mínimo, vencimento. Escolher o que pagar — pode ser o valor total, o mínimo ou outro valor permitido. Confirmar o pagamento — o sistema pede confirmação antes de cobrar. Imprimir o comprovante — se a impressora estiver configurada. 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). Figura 5 — Passo a passo do operador no portal de pagamento. 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 Endpoint Função consultarTitulos Busca faturas na Credsystem; salva cliente em cred_cliente consultarLimiteSituacao Simula limite e planos de parcelamento contratarPlanoLimite Contrata plano na Interface de Programação de Aplicações venda-loja pagamentoTotal Pagamento convencional (dinheiro/cartão) preAutorizacaoPix Gera Código de Resposta Rápida Pagamento Instantâneo consultarStatusPixPagamento Polling status de Pagamento Instantâneo confirmarRecebimentoPix Confirma Pagamento Instantâneo concluído listarPagamentosCredsystemIntegrador Lista pagamentos estornáveis desfazerPagamento Estorno na Credsystem + despesa no Ponto de Venda registrarControleImpressao Auditoria — impressão correta registrarControleImpressaoIncorreta Auditoria — impressão com erro 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" } Fluxo de Pagamento — Dinheiro e Cartão 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. Em linguagem simples O pagamento no balcão funciona assim: Buscar a fatura — o sistema consulta na Credsystem o que o cliente deve. Reservar o valor (pré-autorização) — a Credsystem "segura" o valor antes de confirmar. Confirmar o pagamento (efetivação) — a Credsystem registra que o dinheiro foi recebido. Verificar se deu certo (sonda) — o sistema confere se a Credsystem confirmou tudo. Registrar no caixa — o valor entra como receita no Ponto de Venda da loja. 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). Figura 6 — Fluxo completo do pagamento convencional: quatro etapas na Credsystem, depois gravação local e lançamento no Ponto de Venda. 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) # Etapa Endpoint de Transferência Representacional de Estado Campo etapa em erro 1 Consultar títulos GET consulta-titulo consultarTitulos 2 Pré-autorização POST pre-autorizacao preAutorizar 3 Efetivação POST efetivacao efetivar 4 Sonda efetivação GET efetivacao/sonda sondaEfetivacao Pós-sucesso em 88e14c87 salvarCredsystemPagamento() → INSERT em cred_pagamento (tipo DINHEIRO, situação EFETIVADO) registrarControleAcaoPagamentoCredsystem() → log tipo credsystem-recebimento-pagamento 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 Fluxo de Pagamento Instantâneo e Totem de Autoatendimento 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. Em linguagem simples No balcão (com operador) O operador consulta o Cadastro de Pessoa Física e escolhe pagar com Pagamento Instantâneo. Aparece um Código de Resposta Rápida na tela. O cliente escaneia com o aplicativo do banco e paga. O sistema fica verificando se o pagamento chegou (a cada poucos segundos). Quando confirmado, aparece a mensagem de sucesso. No totem (autoatendimento) O cliente toca na tela do totem na loja. O totem abre a página de pagamento instantâneo ( /v1/credsystem-pix). O cliente digita o Cadastro de Pessoa Física, vê o Código de Resposta Rápida e paga pelo celular. 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). 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. 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 Método 88e14c87 Interface de Programação de Aplicações 981bfb94 Endpoint Credsystem preAutorizacaoPix preAutorizacaoPix() POST pre-autorizacao/pix consultarStatusPixPagamento consultarStatusPreAutorizacaoPix() GET pre-autorizacao/sonda/status-pix confirmarRecebimentoPix — Salva em cred_pagamento (tipo Pagamento Instantâneo); sem registrarReceita 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 Parcelamento e Consulta de Limite 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. Em linguagem simples Às vezes o cliente não quer pagar tudo de uma vez. O sistema permite: Consultar o limite — ver quanto o cliente pode parcelar no cartão. Simular planos — ver opções de parcelas (quantas vezes, valor de cada parcela). 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. Figura 8 — Consulta de limite retorna planos; contratação confirma o parcelamento na Interface de Programação de Aplicações venda-loja. Detalhes para Tecnologia da Informação Endpoints Método 88e14c87 Método 981bfb94 Interface de Programação de Aplicações Credsystem consultarLimiteSituacao consultarLimiteSituacao() GET venda-loja/…/limite-situacao (header cpf) contratarPlanoLimite contratarPlanoVenda() POST venda-loja/…/venda 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) Estorno e Regras de Desfazimento Em alguns casos, o operador pode cancelar um pagamento já feito — mas existem regras de prazo e tipo de pagamento que precisam ser respeitadas. Em linguagem simples Se o operador cometeu um erro ou o cliente desistiu, é possível desfazer o pagamento — mas com estas regras: Regra Explicação Prazo de 24 horas Só dá para desfazer pagamentos feitos nas últimas 24 horas. Pagamento Instantâneo não pode Pagamentos feitos por Pagamento Instantâneo não aparecem na lista de desfazimento. Só pagamentos confirmados Apenas pagamentos com situação "efetivado" (confirmado). Registra saída no caixa O estorno gera uma despesa no Ponto de Venda (dinheiro "sai" do caixa). Passos para o operador: Consultar o Cadastro de Pessoa Física do cliente. Abrir a lista de pagamentos que podem ser desfeitos. Escolher o pagamento e confirmar o desfazimento. O sistema cancela na Credsystem e registra a despesa no caixa. Figura 9 — Estorno: lista filtrada → desfazimento na Credsystem → atualização local → despesa no Ponto de Venda. 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() Valida prazo e existência do registro em cred_pagamento Chama api_integracao_credsystem::desfazer() → desfazimento Atualiza cred_pagamento.situacao para ESTORNADO registrarDespesa() → vendarapida::sangriasuprimento (DESPESA, usa idNaturezaDespesa) 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. Gestor Mobile — Caixa e Impressora O aplicativo gestor no celular permite que cada funcionário configure qual caixa e qual impressora vai usar no dia a dia. 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. Figura 10 — O aplicativo gestor salva e carrega configurações por usuário na tabela configuracao_usuario. 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 Método Descrição salvarConfiguracaoCaixa Persiste configuração de caixa carregarConfiguracaoCaixa Carrega caixa + mescla impressora salvarConfiguracaoImpressora Persiste configuração de impressora carregarConfiguracaoImpressora Carrega só impressora Armazenamento descricao Conteúdo gestor_configuracao_caixa Notação de Objetos JavaScript legível (não Codificação Base 64) gestor_configuracao_impresora Notação de Objetos JavaScript com tipo e parâmetros da impressora 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 Referência Técnica para equipe de Tecnologia da Informação Tabelas de endpoints, rotas, auditoria, integrações externas e dependências — material de consulta rápida para equipes de tecnologia. 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. Mapa de módulos e rotas Identificador Universal Único Classe Rota base 981bfb94-afe7-4956-8ecd-4ecbc3b45246 api_integracao_credsystem /bibliotecas/981bfb94-…/api_integracao_credsystem 88e14c87-331c-485b-95f8-8f63d76d446d api_integracao_credsystem_pagamento_total /bibliotecas/88e14c87-…/api_integracao_credsystem_pagamento_total 857e21c5-203f-4943-b60d-9258bf0ebd7e credsystem_gestor_configuracoes /bibliotecas/857e21c5-…/credsystem_gestor_configuracoes Integrações externas Sistema Protocolo Endereço Uniforme de Recurso (homologação) Autorização Aberta Oracle IDCS POST client_credentials https://idcs-…identity.oraclecloud.com/oauth2/v1/token Credsystem Arrecadação Transferência Representacional de Estado versão 2 https://apihml.credsystem.com.br/arrecadacao-lojista/api/v2/ Credsystem Venda-loja Transferência Representacional de Estado versão 1 https://apihml.credsystem.com.br/venda-loja/api/v1/ ILLI Ponto de Venda Pré-processador de Hipertexto interno vendarapida::sangriasuprimento Totem de Pagamento Instantâneo Interface do Usuário redirecionamento do Protocolo de Transferência de Hipertexto /v1/credsystem-pix 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) Método Pré-processador de Hipertexto Protocolo de Transferência de Hipertexto Endpoint Credsystem consultarTitulos GET consulta-titulo preAutorizar POST pre-autorizacao preAutorizarPix POST pre-autorizacao/pix consultarStatusPreAutorizacao GET pre-autorizacao/sonda/status consultarStatusPreAutorizacaoPix GET pre-autorizacao/sonda/status-pix efetivar POST efetivacao consultarSondaEfetivacao GET efetivacao/sonda desfazer POST/GET desfazimento consultarFaturas GET faturas consultarExtrato GET faturas/extrato/{cod}/vencimento/{data} consultarTransacoes GET faturas/extrato/…/transacoes consultarLimiteSituacao GET limite-situacao (cabeçalho cpf) contratarPlanoVenda POST venda pagamento — Orquestra: títulos → pré-autorização → efetivação → sonda pagamentoPix — Orquestra fluxo Pagamento Instantâneo com verificação periódica de status getConfiguracaoCredsystem — Lê configuracao_entidade salvarConfiguracaoCredsystem — Grava api_config_credsystem Endpoints — Pagamento Total (88e14c87) Método Pré-processador de Hipertexto Efeito colateral consultarTitulos Interface de Programação de Aplicações + INSERT cred_cliente consultarLimiteSituacao Delega 981bfb94 contratarPlanoLimite Delega 981bfb94 pagamentoTotal Interface de Programação de Aplicações + cred_pagamento + receita no Ponto de Venda + auditoria preAutorizacaoPix Interface de Programação de Aplicações + auditoria de Pagamento Instantâneo consultarStatusPixPagamento Delega 981bfb94 confirmarRecebimentoPix cred_pagamento (Pagamento Instantâneo) — sem receita no Ponto de Venda desfazerPagamento Interface de Programação de Aplicações desfazer + ESTORNADO + despesa no Ponto de Venda listarPagamentosCredsystemIntegrador SELECT cred_pagamento (filtros 24h, não-Pagamento Instantâneo) registrarControleImpressao Auditoria impressão correta registrarControleImpressaoIncorreta Auditoria impressão incorreta registrarSatisfacaoTotem INSERT cred_satisfacao autenticacaoTotem Protocolo de Transferência de Hipertexto código 302 → /v1/credsystem-pix obter/salvar/limpar/exibirFundoTotemAtracao Criar, Ler, Atualizar e Excluir imagem totem Banco de dados Tabela / Chave Módulo Uso configuracao_entidade.api_config_credsystem 981bfb94 Configuração por loja (Codificação Base 64) configuracao_usuario.gestor_configuracao_caixa 857e21c5 Caixa por usuário configuracao_usuario.gestor_configuracao_impresora 857e21c5 Impressora por usuário configuracao.credsystem_pix_fundo_totem_atracao 88e14c87 Imagem fundo totem {banco}_integrador.cred_cliente 88e14c87 Dados cliente (Notação de Objetos JavaScript) {banco}_integrador.cred_pagamento 88e14c87 Histórico pagamentos {banco}_integrador.cred_satisfacao 88e14c87 índice de satisfação do totem (1–5) Auditoria (controle) Método controle() em 88e14c87 registra eventos com campo tipo: tipo Quando credsystem-recebimento-pagamento Pagamento convencional efetivado credsystem-pix-pre-autorizacao Código de Resposta Rápida Pagamento Instantâneo gerado credsystem-recebimento-pix Pagamento Instantâneo confirmado credsystem-estorno-pagamento Desfazimento realizado credsystem-comprovante-impressao Comprovante impresso corretamente credsystem-comprovante-impressao-incorreta Erro na impressão Regras de negócio (constantes) Regra Valor Arquivo Prazo estorno 24 horas 88e14c87/controle.php — PRAZO_DESFAZIMENTO_HORAS Pagamento Instantâneo estornável Não Filtro Linguagem de Consulta Estruturada pagamento <> 'PIX' Pagamento Instantâneo gera receita no Ponto de Venda Não confirmarRecebimentoPix sem registrarReceita Estorno automático em falha Default true estornarEmFalha em pagamento() Consulta repetida de Pagamento Instantâneo pendente Protocolo de Transferência de Hipertexto código 202 consultarStatusPreAutorizacaoPix 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 Arquivo Linhas aprox. Conteúdo bibliotecas/981bfb94-…/controle.php ~1700 Cliente de Transferência Representacional de Estado Credsystem completo bibliotecas/88e14c87-…/controle.php ~1710 Orquestração pagamento, Ponto de Venda, totem bibliotecas/88e14c87-…/visual.html ~2000 Portal Vue 3 bibliotecas/88e14c87-…/instalador.php ~110 Migrações v1–v4 bibliotecas/981bfb94-…/visual.html — Config Quasar bibliotecas/857e21c5-…/controle.php ~460 Configuração do gestor Figura 11 — Mapa resumido de módulos e dependências externas ao diretório bibliotecas/. Documentação [Via BASE/GESTOR] Guia simples para configurar e usar no dia a dia. Neste documento 1. Instalação dos Apps 2. Configurar a integração 3. Configurar o totem (Visual) 4. Impressora no Gestor 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 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 ---------------------------------------------------------------------------------------------------------------------------------- 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 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" > 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. Tela de configuração — Configurações (Gerais) Passo a passo — Configurações (Gerais) Expanda Configurações (Gerais). Escolha a Entidade (loja) que será configurada. Em Acesso da loja, preencha Usuário e Senha. Em Credenciais OAuth, preencha Client ID, Client Secret e Scope. Em URLs dos serviços, confira as 3 URLs (homologação ou produção, conforme o ambiente). Em Parâmetros ILLI, preencha Bandeira e os IDs do ILLI (forma de pagamento, natureza receita e natureza despesa). Clique em Salvar configuração. O que cada campo significa Entidade Loja que está sendo configurada. Usuário Usuário da loja Senha Senha da loja Client ID Usuário técnico da API. Client Secret Senha técnica da API. Scope Permissão do token. URL Base Arrecadação Endereço para pagamentos e títulos. URL Base Venda Loja Endereço para limite e planos. URL OAuth Endereço para gerar o token. Bandeira Em geral OBJETIVA. ID forma de pagamento Código da forma Credsystem no ILLI. ID natureza receita Natureza do recebimento. ID natureza despesa Natureza do estorno/desfazimento. 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/", "urlBaseVendaLoja": "https://apihml.credsystem.com.br/venda-loja/api/v1/", "urlOauth": "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 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 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 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 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 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 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 4. Impressora no Gestor Para o comprovante sair no caixa, configure a impressora do operador no Gestor. Tipo de impressora Bluetooth, USB, Rede, GPOS, Clover… ou Nenhum. Nome do dispositivo Nome da impressora. MAC (Bluetooth) Endereço da impressora Bluetooth. IP e Porta (Rede) Usados no tipo Rede (porta comum: 9100). Colunas Largura do cupom (ex.: 48). Salve e faça um teste de impressão. Credsystem × ILLI · Guia do usuário Documentação [Via PDV] 1. Como acessar os módulos Todos os módulos Credsystem ficam no menu do PDV, em Outras funções. Abra o PDV (tela do caixa). Abra o Menu. Em Outras funções, escolha o módulo desejado: Credsystem (Dinheiro) Receber pagamento em dinheiro. ALT+SHIFT+A Credsystem (PIX) Receber pagamento via PIX. ALT+SHIFT+B Credsystem (Limite) Consultar limite e situação do cartão. ALT+SHIFT+C Credsystem (Desfazer) Estornar um pagamento já feito. Menu Outras funções com os quatro módulos Credsystem Dica: você também pode usar os atalhos de teclado mostrados no menu para abrir o módulo mais rápido. 2 Credsystem (Dinheiro) Use este módulo para receber o pagamento de títulos Credsystem em dinheiro. Passo a passo No menu, abra Credsystem (Dinheiro). Na tela Consulta por CPF, digite o CPF do cliente (somente números). A máscara é aplicada automaticamente. Pressione Enter ou clique em Consultar. Confira os dados do cliente (nome, CPF e aniversário). Veja o título em aberto (extrato, valor, encargos). Em Ação, escolha quanto receber: Total sem Seguro — valor total; Mínimo — quando disponível; Outro Valor — digite o valor desejado. Clique em Receber. Na janela Confirmar recebimento, confira o CPF e o valor e clique em Confirmar recebimento. Após o sucesso, o sistema pergunta: “O comprovante de pagamento foi impresso corretamente?” 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. Use Nova Consulta para atender outro cliente. Pergunta sobre a impressão do comprovante após o pagamento Quando o recebimento concluir, a tela mostra a mensagem de sucesso e o toast “Pagamento concluído”. 3 Credsystem (PIX) Use este módulo para o cliente pagar títulos Credsystem via PIX (QR Code ou copia e cola). Passo a passo No menu, abra Credsystem (PIX). Informe o CPF do cliente (somente números) e clique em Consultar (ou Enter). Consulta por CPF — Credsystem (PIX) Confira os dados do cliente e o título em aberto. Escolha o valor a receber (total, mínimo ou outro valor) e clique em Receber. Na tela Forma de recebimento, escolha PIX. 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. Aguarde a mensagem “Aguardando confirmação do pagamento na Credsystem…” até a confirmação automática. 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. O valor do PIX é contabilizado na Credsystem — não gera receita no fluxo local do caixa. 4 Credsystem (Limite) Use este módulo para consultar o limite disponível e a situação do cartão do cliente. Passo a passo No menu, abra Credsystem (Limite). Digite o CPF do cliente (somente números). Pressione Enter ou clique no botão Limite. As informações abrem em uma nova página. Consulta de limite por CPF 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) Resultado da consulta de limite e situação do cartão Simular parcelas No quadro Simular Parcelas, informe o valor da compra. Clique em Simular parcelas para ver as opções. Para voltar à busca, use Voltar à consulta. 5 Credsystem (Desfazer) Use este módulo para estornar um pagamento já registrado na Credsystem. Apenas pagamentos com menos de 24h podem ser desfeitos Passo a passo No menu, abra Credsystem (Desfazer). Informe o CPF do cliente e clique em Consultar (ou Enter). Consulta por CPF — Credsystem (Desfazer) Confira os dados do cliente. Na lista Pagamentos registrados, localize o pagamento desejado (data/hora, autorização, valor, forma e situação). Clique em Estornar na linha do pagamento. Lista de pagamentos com o botão Estornar Na janela Confirmar desfazimento, confira autorização, estabelecimento, identificador e valor. Clique em Confirmar desfazimento (botão vermelho) para solicitar o estorno à Credsystem. Confirmação do desfazimento / estorno Quando o estorno concluir, confira se o comprovante de estorno saiu corretamente na impressora. Responda Sim ou Não. Em “Não”, o sistema registra a ocorrência e envia nova via. Use Nova consulta para outro CPF. Confirmação da impressão do comprovante de estorno O estorno é uma ação definitiva junto à Credsystem. Confira sempre autorização e valor antes de confirmar. 6 Dicas gerais para o caixa Situação O que fazer Digitar CPF Use só números. A máscara (000.000.000-00) é aplicada sozinha. CPF inválido O Enter / botão só envia quando o CPF estiver completo e válido. Comprovante não saiu Responda Não na pergunta de impressão para gerar nova via. PIX pago errado Não dá para estornar pelo canal PIX do PDV. Siga o procedimento com a Credsystem. Trocar de cliente Use o botão Nova consulta. Fechar o módulo Clique no X no canto superior direito da janela. Resumo do caminho: PDV → Menu → Outras funções → Credsystem (Dinheiro / PIX / Limite / Desfazer).