# Painel de operação

<https://unifokal.com/docs/painel-de-operacao>

## Painel de operação

Três telas do painel respondem ao que quem opera a integração pergunta todo dia: onde as sessões param, o que a integração chamou e quanto a conta pode gastar. Elas ficam no grupo **Operação** do menu, ao lado de Verificações e Sessões, e nenhuma delas tem rota na superfície da chave secreta: são telas de painel, lidas com a sessão de um membro.

**Funil.** A escada da jornada por ambiente e, se quiser, por flow: sessão criada, titular abriu a verificação, captura enviada, decisão emitida, aprovada. Para cada etapa você vê quantas sessões chegaram, quantas pararam ali e o tempo mediano de quem parou, além das decisões por dia na mesma janela. A escada é cumulativa (cada etapa é menor ou igual à anterior) e as cinco contagens de parados somam o total de sessões, provado por teste de propriedade no servidor. A janela padrão é de 14 dias e o máximo é 90. Os números vêm de uma consulta agregada, então valem para uma conta de qualquer tamanho: não há recorte de amostra. O gráfico da página inicial do painel lê a mesma série.

**Requisições.** O registro do que a sua integração chamou nos últimos 30 dias, com filtro por identificador, por chave ou membro e por período. Cada linha traz o `request_id` (o mesmo `x-request-id` que a resposta devolve, e que você pode enviar), a credencial usada, o método, a rota, o status, a duração e o código de erro do envelope. **Nunca o corpo, os cabeçalhos ou a query string**: a tabela não tem coluna onde isso caberia, e a rota gravada é o padrão (`/v1/verifications/:id`), nunca o caminho com o identificador do recurso. É a diferença deliberada contra o histórico que guarda a carga inteira: um registro com CPF dentro seria um segundo banco de dado pessoal. Para correlacionar uma chamada no suporte, cite o `request_id`.

**Orçamento.** O teto diário de gasto, por ambiente, para a organização e, se quiser, por chave. O sandbox não fatura e não tem orçamento. O teto nasce desligado; ligar é ato do proprietário da conta, com o código do aplicativo autenticador. A tela mostra o gasto do dia, avisa ao passar de 80% do teto e diz o que está agendado. **Diminuir vale na hora. Aumentar, ou desligar, passa a valer na virada do dia, às 00:00 UTC**: uma sessão de painel indevida não consegue gastar o orçamento de hoje. O teto de uma chave só aperta o da organização, nunca o afrouxa. Zero suspende o escopo. O gasto por chave conta as operações cobradas das sessões que a chave criou, inclusive quando a decisão da verificação sai depois: a sessão guarda a chave que a criou, a renovação herda essa chave e o link hospedado passa adiante a chave que o emitiu.

**Teto de operações.** No mesmo registro do orçamento, você pode limitar também quantas operações cobradas saem por dia, para a organização ou para uma chave. A contagem é a mesma do gasto: cada operação cobrada conta uma vez. O teto de operações segue a mesma regra de prazo (baixar vale na hora, subir ou apagar vale na virada do dia) e o mesmo aviso ao passar de 80%. Ao alcançá-lo, a criação de sessão responde `429 volume_cap_reached`, com o mesmo `Retry-After` até 00:00 UTC.

Quando o orçamento do dia acaba, a criação de sessão passa a responder `429 spend_cap_reached`, com o cabeçalho `Retry-After` em segundos até 00:00 UTC, quando o contador vira. Nada é cobrado nessa recusa. Quem nunca configurou um orçamento nunca recebe este código.

**O que o orçamento faz, exatamente.** Ele é uma porta de admissão: barra o que vem depois de o gasto do dia alcançar o teto. Uma verificação já admitida segue até o fim e é cobrada quando o fluxo termina, como sempre. Na prática, o total do dia pode passar do teto pelo que estava em andamento no instante em que ele foi alcançado. Se o seu controle precisa ser exato ao centavo, trate o orçamento como o freio e o `429 spend_cap_reached` como o sinal de parar de abrir sessões.

```
HTTP/1.1 429 Too Many Requests
Retry-After: 18342

{
  "error": "spend_cap_reached",
  "message": "The daily spend budget configured for this organization is exhausted. It resets at 00:00 UTC, or raise it in the dashboard (a raise takes effect the next day)."
}

# Trate como pausa, não como retentativa: espere o Retry-After ou suba o teto no painel
# (a subida vale no dia seguinte). O código é estável; a mensagem pode mudar.
```

**Simular política.** Na tela **Motor**, você testa um ajuste do flow sobre as verificações que já foram decididas, antes de mudar de verdade: aceitar ou não pessoa politicamente exposta, tolerar ou não o impedimento de apostas e tirar um módulo do flow. A simulação usa a evidência guardada e a mesma decisão do produto: **não cobra, não consulta nenhuma fonte e não abre foto**. O resultado diz quantas verificações mudariam de desfecho e em que direção (mais rígido, mais permissivo ou outro tipo de mudança), com a taxa sobre as que puderam ser refeitas, e sempre mostra ao lado quantas ficaram fora da conta e por quê. Ajustes que exigiriam rodar um módulo de novo aparecem desligados, com o motivo. Uma simulação por vez por ambiente, e a janela vai até 90 dias, dentro dos últimos 180.

## Lista de permissão

A lista de permissão reduz o desafio da prova de vida para titulares que a sua empresa já conhece. Ela vale nos flows com a fricção **adaptativa** ligada: no modo fixo, todo titular recebe o desafio completo, com ou sem permissão. E ela vale só para o próprio titular, no contexto em que ele já foi verificado: fora dele, o desafio é o de sempre.

**O que ela nunca dispensa.** A verificação de identidade continua inteira. Rosto, documento, prova de vida, os módulos do flow, a situação cadastral, sanções e pessoas politicamente expostas decidem exatamente como decidiriam sem a permissão, e a cobrança é a mesma. A [lista de bloqueio](https://unifokal.com/docs/ambientes#blocklist) sempre vence: uma referência bloqueada não recebe permissão, e um titular permitido que for bloqueado depois é barrado como qualquer outro.

**De onde ela nasce.** De uma verificação **aprovada**, aberta no painel em Verificações ou em Sessões. A chave da permissão é o `reference_id` que o seu servidor envia ao criar a sessão: o titular nunca escolhe a própria referência. Verificação sem referência, ou que não passou por prova de vida, não origina permissão.

**Quem concede.** Proprietário ou administrador com a **capacidade própria** de conceder, que só o proprietário da conta dá, inclusive para si mesmo, na tela de Segurança. Toda concessão pede o código do aplicativo autenticador. Revogar não pede código e vale a partir da próxima prova de vida do titular. Não existe rota da chave secreta para a lista: conceder exige uma pessoa, a capacidade e o segundo fator.

**Por quanto tempo, e onde.** 7, 30 ou 90 dias, ou até o fim do prazo de guarda da evidência da verificação de origem, nunca mais do que 180 dias depois dela. A permissão vence sozinha. Ela vale na conta inteira (todos os flows do ambiente) ou só no flow da verificação de origem, e sandbox e produção têm listas separadas.

**Trilha.** Cada concessão, revogação, vencimento e apagamento fica registrado com quem fez e quando, com o motivo em código e sem dado do titular, e a tela mostra quantas vezes cada permissão foi usada. Um pedido de exclusão do titular encerra a permissão dele.

## Consulta em lote por planilha

Na tela de consulta avulsa, a aba **Em lote** recebe um arquivo CSV e roda uma consulta avulsa por linha, no mesmo tipo de consulta e com a mesma finalidade para o arquivo inteiro. Cada linha é exatamente a consulta avulsa de um documento: o mesmo preço, a mesma finalidade registrada com o nome de quem enviou, os mesmos limites diários e a mesma regra de o dado sair uma vez. O lote não cria verificação e não consulta a sua lista de bloqueio, como a consulta avulsa.

**Formato.** Texto em UTF-8, separado por vírgula ou por ponto e vírgula, com o cabeçalho `reference_id,document` e um documento por linha. O `reference_id` é a sua referência (de 1 a 64 caracteres entre letras, dígitos, ponto, hífen, sublinhado e dois pontos) e não pode se repetir no arquivo. O `document` é um CPF ou um CNPJ, com ou sem pontuação, conforme o tipo de consulta. Um arquivo com qualquer linha inválida é recusado inteiro, com o número da linha, antes de qualquer cobrança.

```
reference_id,document
cliente-001,529.982.247-25
cliente-002,111.444.777-35
```

**Limites.** O arquivo sobe direto para o armazenamento, com teto de 5 MB e de 5.000 linhas. Em produção, o que vale no dia são os limites da consulta avulsa: o arquivo só entra se couber inteiro no que resta do dia para você e para a conta (o limite por membro hoje é de 100 consultas por dia). Senão, o envio é recusado com o mesmo código da consulta avulsa, `lookup_daily_cap`, `lookup_member_daily_cap` ou `lookup_distinct_daily_cap`, e a mensagem diz quanto resta. O saldo precisa cobrir todas as linhas, senão o envio recebe `insufficient_credit`. Há um lote em andamento por ambiente de cada vez, e o envio pede o segundo fator de quem envia.

**Durante.** As linhas rodam em segundo plano. Se o orçamento diário da conta, um limite diário ou o saldo acabar no meio, o lote pausa com o motivo na tela e continua sozinho quando puder. Se quem enviou sair da conta ou perder o papel, o lote pausa e só sai por cancelamento. O mesmo arquivo enviado de novo em 24 horas devolve o lote que já existe, e cada linha é cobrada uma vez.

**O que volta.** Um CSV com uma linha por linha do arquivo, na ordem do arquivo: as colunas `line_no`, `reference_id`, `status`, `lookup_query_id`, `found` e `error_code`, seguidas dos campos que a fonte devolveu. O `lookup_query_id` é o mesmo do extrato de créditos, então cada linha cobrada concilia pela mesma chave da consulta avulsa. O resultado sai por um link de 5 minutos, uma vez, para owner ou admin; uma nova emissão é só do owner, com o motivo registrado. A entrada e o resultado são apagados 7 dias depois do fim do lote.

## Permissões próprias

Algumas ações do painel não pertencem a um papel inteiro: são permissões que o proprietário da conta concede a uma pessoa específica da equipe. Elas ficam na tela **Organização**, no bloco **Permissões próprias**, logo abaixo da equipe, e só o proprietário vê esse bloco.

**Gerenciar lista de permissão.** Cria e edita a lista de pessoas liberadas das regras de bloqueio. O proprietário tem pelo papel; um administrador só tem se o proprietário conceder.

**Gerenciar política de decisão.** Ativa a política e os limiares do motor de decisão. O proprietário tem pelo papel; um administrador só tem se o proprietário conceder.

As duas só podem ser concedidas a quem tem o papel **Administrador** e está ativo na organização. Desenvolvedor e leitura não recebem, e a tentativa é recusada. Se o administrador deixar de ser administrador ou sair da organização, a concessão perde o efeito na hora, sem precisar revogar.

**Quem concede e como.** Só o proprietário concede e revoga, e cada concessão e cada revogação pedem o segundo fator dele (o código do aplicativo autenticador, um código de recuperação ou a passkey). Uma sessão do painel sequestrada não basta para entregar uma permissão. Chave de API nunca concede nem revoga: são ações só do painel. Cada concessão guarda quem concedeu e quando, e a tela mostra a data.

**A revogação vale na hora.** A permissão é conferida a cada ação da pessoa, sem cache: a próxima tentativa dela depois da revogação já é recusada, mesmo com a sessão aberta.

**Gerenciar casos de PLD.** Dá acesso ao livro e aos casos de prevenção à lavagem de dinheiro. Proprietário e administrador já têm pelo papel. A concessão dela a outros membros, como um analista de PLD com papel de desenvolvedor ou de leitura, **ainda não está aberta**: por enquanto o painel não oferece o controle.