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ó:
- grava o pedido no caso de compliance;
- 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)
- Abrir a tela de Compliance.
- Abrir o detalhe KYC do estabelecimento.
- Clicar em Solicitar informação (rodapé do modal).
- O botão fica desabilitado enquanto o screening está
EM_ANALISE.
- O botão fica desabilitado enquanto o screening está
- Preencher a justificativa (obrigatória). Esse texto é o que o EC vai ler.
- 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:
| Campo | Valor |
|---|---|
status | AGUARDANDO_INFORMACAO |
decision_reason | texto digitado pelo analista |
decided_by | ID do usuário que pediu |
decided_at | data/hora do pedido |
Histórico: compliance_eventos com evento = screening_decision e contexto_json.reason.
Não altera:
estabelecimentos_locais.statuscompliance_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.phpbackend/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 (hiddenpor padrão)#estInformacaoSolicitadaTitle— título fixo#estInformacaoSolicitadaTexto—informacao_solicitada.texto#estInformacaoSolicitadaMeta—Solicitado em+ data empt-BR
A função global window.renderInformacaoSolicitadaCompliance(payload):
- tenta
payload.informacao_solicitada.texto; - se não vier aninhado, aceita fallback
screening_status/decision_reason/decided_at; - se não houver pedido ativo, esconde o banner.
Quem chama depois de preencher o modal:
assets/js/pages/estabelecimentos/estabelecimentos-lista.jsassets/js/pages/estabelecimentos/estabelecimentos-lista-remotos.jsassets/js/pages/compliance/compliance-page.js
Arquivos
| Arquivo | Papel |
|---|---|
frontend/pages/compliance/index.php | Modal de justificativa (#modalKycDecisao) |
assets/js/pages/compliance/compliance-page.js | Botão, abrirModalDecisaoKyc(), confirmarDecisaoKyc() |
backend/api/compliance/decidir.php | Endpoint POST |
backend/src/services/compliance/compliance_screening_service.php | backend_compliance_screening_decide() — grava decisão |
backend/src/services/compliance/compliance_service.php | backend_compliance_requested_information() — monta o campo |
backend/src/services/estabelecimentos/establishment_service.php | Inclui o campo no detalhe do EC |
components/popup_detalhes_estabelecimento.php | HTML/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):
| Campo | Papel |
|---|---|
estabelecimento_id | EC |
screening_case_id | Caso KYC |
user_id | Autor (nullable para sistema) |
autor_papel | COMPLIANCE, ESTABELECIMENTO ou SISTEMA |
mensagem | Texto |
is_apontamento | Marca 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
- Pegar um EC com caso KYC não em
EM_ANALISE. - Solicitar informação com um texto conhecido.
- Conferir no banco:
compliance_cases.status = AGUARDANDO_INFORMACAOdecision_reasonigual ao textodecided_atpreenchido
- Abrir Detalhes do estabelecimento e ver o banner no topo, acima das abas.
- 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_INFORMACAOnã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 incluirpopup_detalhes_estabelecimento.php, a função de render não existe.