Pular para o conteúdo principal

Solicitação de informação pelo compliance

Última revisão: 19/09/2026.

Guia para o desenvolvedor: o que é, como usar, onde grava e como o estabelecimento vê o recado.

Além do banner no detalhe do EC, existe chat de apontamentos (compliance_info_chat, API backend/api/compliance/chat.php, service compliance_chat_service.php). O pedido formal (SOLICITAR_INFORMACAO) continua gravando o caso; o chat é a conversa assíncrona compliance ↔ estabelecimento em cima desse caso.

O que é​

No detalhe KYC, o analista de compliance pode pedir informação extra ao estabelecimento (ex.: conferir ticket médio, faturamento e volume mensal).

O texto não é gerado automaticamente. Quem escreve é o analista, no modal de justificativa. O sistema só:

  1. grava o pedido no caso de compliance;
  2. mostra um banner roxo no modal de detalhes do estabelecimento.

Exemplo do que o EC vê:

  • Título: Informação solicitada pelo compliance
  • Texto: o que o analista digitou
  • Data: Solicitado em dd/mm/aaaa, hh:mm:ss

Como usar (passo a passo)​

  1. Abrir a tela de Compliance.
  2. Abrir o detalhe KYC do estabelecimento.
  3. Clicar em Solicitar informação (rodapé do modal).
    • O botão fica desabilitado enquanto o screening está EM_ANALISE.
  4. Preencher a justificativa (obrigatória). Esse texto é o que o EC vai ler.
  5. Clicar em Confirmar.

O caso passa para status Aguardando informação. O banner aparece na próxima vez que alguém abrir o modal de detalhes daquele EC (lista de estabelecimentos, lista remota ou a própria tela de compliance).

Para sumir o banner, o compliance precisa aprovar ou reprovar o cadastro depois. Pedir informação de novo substitui o texto anterior (é sempre o caso mais recente).

Fluxo técnico​

Analista clica "Solicitar informação"
│
▼
Modal #modalKycDecisao (textarea kycDecisaoReason)
│
▼
POST /backend/api/compliance/decidir.php
{ compliance_id, action: "SOLICITAR_INFORMACAO", reason }
│
▼
backend_compliance_screening_decide()
│
├─ UPDATE compliance_cases
│ status = AGUARDANDO_INFORMACAO
│ decision_reason = reason
│ decided_by = usuário logado
│ decided_at = NOW()
│
└─ INSERT compliance_eventos
evento = screening_decision
contexto_json.reason = reason

Depois, ao abrir o detalhe do EC:

detalhes.php / buscar-estabelecimento.php
│
▼
backend_compliance_requested_information(conn, estabelecimento_id)
│ lê o caso MAIS RECENTE em compliance_cases
│ só retorna se status = AGUARDANDO_INFORMACAO e houver texto
▼
campo informacao_solicitada no JSON
│
▼
window.renderInformacaoSolicitadaCompliance(payload)
│
▼
Banner #estInformacaoSolicitada no topo do #detailsPopup

Onde grava​

Tabela compliance_cases:

CampoValor
statusAGUARDANDO_INFORMACAO
decision_reasontexto digitado pelo analista
decided_byID do usuário que pediu
decided_atdata/hora do pedido

Histórico: compliance_eventos com evento = screening_decision e contexto_json.reason.

Não altera:

  • estabelecimentos_locais.status
  • compliance_estabelecimentos (status de documentos)

Aprovar/reprovar também usa o mesmo endpoint e o mesmo campo decision_reason. Por isso o banner some: o status deixa de ser AGUARDANDO_INFORMACAO.

Contrato no detalhe do EC​

Campo informacao_solicitada (objeto ou null):

{
"texto": "favor verificar preenchimento de ticket medio, faturamento e volume mensal (incompativeis entre si)",
"status": "AGUARDANDO_INFORMACAO",
"solicitado_em": "2026-09-16 13:29:52"
}

APIs que devolvem o campo:

  • backend/api/estabelecimentos/detalhes.php
  • backend/api/compliance/buscar-estabelecimento.php (hydration do compliance)

Regra da query: último registro de compliance_cases daquele estabelecimento_id (ORDER BY id DESC LIMIT 1). Se o status não for AGUARDANDO_INFORMACAO ou o texto estiver vazio, retorna null e o banner fica oculto.

Front: banner​

Markup em components/popup_detalhes_estabelecimento.php:

  • #estInformacaoSolicitada — container (hidden por padrão)
  • #estInformacaoSolicitadaTitle — título fixo
  • #estInformacaoSolicitadaTexto — informacao_solicitada.texto
  • #estInformacaoSolicitadaMeta — Solicitado em + data em pt-BR

A função global window.renderInformacaoSolicitadaCompliance(payload):

  1. tenta payload.informacao_solicitada.texto;
  2. se não vier aninhado, aceita fallback screening_status / decision_reason / decided_at;
  3. se não houver pedido ativo, esconde o banner.

Quem chama depois de preencher o modal:

  • assets/js/pages/estabelecimentos/estabelecimentos-lista.js
  • assets/js/pages/estabelecimentos/estabelecimentos-lista-remotos.js
  • assets/js/pages/compliance/compliance-page.js

Arquivos​

ArquivoPapel
frontend/pages/compliance/index.phpModal de justificativa (#modalKycDecisao)
assets/js/pages/compliance/compliance-page.jsBotão, abrirModalDecisaoKyc(), confirmarDecisaoKyc()
backend/api/compliance/decidir.phpEndpoint POST
backend/src/services/compliance/compliance_screening_service.phpbackend_compliance_screening_decide() — grava decisão
backend/src/services/compliance/compliance_service.phpbackend_compliance_requested_information() — monta o campo
backend/src/services/estabelecimentos/establishment_service.phpInclui o campo no detalhe do EC
components/popup_detalhes_estabelecimento.phpHTML/CSS do banner + renderInformacaoSolicitadaCompliance

Permissões da decisão: qualquer uma entre compliance.approve, compliance.edit, compliance.view (aliases compliance.aprovar, compliance.ver_todos ainda resolvem). Código legado pode citar compliance.rejeitar — não está no catálogo canônico.

Ações aceitas no endpoint: APROVAR, REPROVAR, SOLICITAR_INFORMACAO (justificativa sempre obrigatória).

Chat de apontamentos (set/2026)​

Tabela compliance_info_chat (migration 20260918_compliance_info_chat.php + ensure_schema):

CampoPapel
estabelecimento_idEC
screening_case_idCaso KYC
user_idAutor (nullable para sistema)
autor_papelCOMPLIANCE, ESTABELECIMENTO ou SISTEMA
mensagemTexto
is_apontamentoMarca recado formal vs fala solta

API: GET/POST backend/api/compliance/chat.php (sessão + estabelecimento_id). Operador de compliance precisa de flag compliance.view / edit / approve (super-admin passa).

Arquivos extras: backend/src/services/compliance/compliance_chat_service.php, frontend/pages/compliance/index.php (UI do chat).

Como testar​

  1. Pegar um EC com caso KYC não em EM_ANALISE.
  2. Solicitar informação com um texto conhecido.
  3. Conferir no banco:
    • compliance_cases.status = AGUARDANDO_INFORMACAO
    • decision_reason igual ao texto
    • decided_at preenchido
  4. Abrir Detalhes do estabelecimento e ver o banner no topo, acima das abas.
  5. Aprovar ou reprovar o mesmo caso e reabrir o detalhe: o banner não deve aparecer.

Cuidados​

  • Não há validação automática de ticket médio × faturamento × volume. Se o recado falar disso, foi o analista quem escreveu.
  • Só o caso mais recente conta. Um caso antigo em AGUARDANDO_INFORMACAO não reaparece se já existir outro mais novo.
  • Aprovar/reprovar reutiliza decision_reason. Não misture esse campo com outro recado permanente para o EC.
  • O banner só existe no modal #detailsPopup. Se a tela não incluir popup_detalhes_estabelecimento.php, a função de render não existe.