> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unifokal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Painel de operação

> O funil por etapa e por flow, o registro de requisições sem corpo, o orçamento diário de gasto com o spend_cap_reached, a consulta em lote, a simulação de política, a lista de permissão e o ponto de atendimento.

## 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 sugere um valor a partir do seu gasto dos últimos 29 dias; o teto só liga quando o proprietário salva. 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, tirar um módulo do flow e, em produção, trocar o país esperado. Com o país esperado, a simulação recalcula o sinal de país do IP nas verificações que guardaram o país. A simulação anda na ordem em que as verificações da conta aconteceram: quando uma verificação alterada pode mudar o resultado de outra, pela mesma referência, pelo mesmo aparelho, pela mesma rede ou pelo mesmo documento, a outra fica fora da conta, com o motivo, e o resultado mostra quantas dependem de uma verificação alterada e cada direção como um intervalo. A simulação não muda o que as pessoas fazem: as tentativas seguintes, as revisões e os bloqueios manuais acontecem como aconteceram, salvo nas verificações que ficam fora da conta. No sandbox esse ajuste aparece desligado, porque lá a verificação de IP e o antifraude são simulados pelo final do documento. Os dois bloqueios automáticos do flow, por ataque e pelo retorno do cliente, também entram, ligados e sozinhos: a simulação refaz na ordem as verificações da conta no ambiente, marca como bloqueadas as que encontrariam o documento na lista e mostra quantas entradas nasceriam, quantas verificações seriam barradas no flow e nos outros flows e quantas ficaram fora da conta, com o motivo. 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. Sua equipe roda uma simulação por vez em cada ambiente, e a janela vai até 90 dias, dentro dos últimos 180. Simulações feitas pela UNIFOKAL no seu histórico, como a que roda sozinha quando o perfil do motor que você escolheu é recalibrado, aparecem na lista com essa marca e não ocupam a vez da sua equipe nem contam no limite diário dela.

**Perfis do motor e níveis dos gates.** Na mesma tela, você escolhe o rigor do motor de decisão para o seu negócio e o rigor dos gates de proteção de conta e transacional. São três nomes, na mesma ordem, do mais rigoroso ao que mais converte: **Conservador**, **Equilibrado** e **Conversão**. O Conservador é o padrão dos gates; sem escolha, o motor segue a política padrão da UNIFOKAL. Veja o efeito no seu histórico antes de ligar, e observe em sombra sem mudar nenhuma decisão. Voltar ao padrão vale em até 30 segundos, e nenhuma troca muda uma decisão já tomada. Cada troca pede o segundo fator do proprietário da conta, ou de um administrador com a permissão Gerenciar política de decisão.

**Amostra de auditoria dos aprovados.** Na mesma tela, você liga, por ambiente, a amostra de auditoria: uma parte das verificações aprovadas automaticamente é sorteada para a sua equipe conferir depois. Ser sorteada não muda o desfecho, o webhook nem a tela de quem se verificou. As sorteadas aparecem em **Verificações**, no filtro **Amostra de auditoria**, que abre nas pendentes, das mais antigas para as mais novas. A sua equipe confirma a legítima, ou recusa ou bloqueia a fraude com o tipo de abuso; a recusa e o bloqueio seguem o caminho de sempre, com o webhook da nova decisão. O painel mostra até quanto de fraude passou pela aprovação automática, com 95% de confiança, contando a fraude que a sua equipe identificou na conferência, e o fechamento do último trimestre, que é o número para relatório. A tela sugere uma fração, e a fração é sempre escolha sua: nada liga nem muda sozinho. Ligar, trocar ou desligar a fração pede o segundo fator do proprietário da conta, ou de um administrador com a permissão Gerenciar política de decisão. Nada é cobrado pelo sorteio nem pela conferência.

## 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://docs.unifokal.com/ambientes.md#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.

## Ponto de atendimento

Um ponto de atendimento é um local da sua empresa, como uma loja, um quiosque ou um correspondente, onde as pessoas se verificam presencialmente, com ou sem atendente, no mesmo aparelho ou na mesma rede. Fora de um ponto declarado, muitas identidades no mesmo aparelho ou na mesma rede é sinal de fraude e manda a verificação para revisão. No ponto, é a natureza do local, e a declaração diz isso ao motor, sob a responsabilidade da sua empresa.

**O efeito.** Depois da declaração, a concentração de identidades no mesmo aparelho ou na mesma rede do local deixa de mandar sozinha toda verificação do ponto para revisão: nos primeiros dias todas continuam indo, depois, conforme o volume do ponto cresce, só uma parte, e o volume do ponto segue acompanhado. Um volume de identidades fora do comum para o próprio ponto manda a verificação para revisão com esse motivo.

**O que ele nunca dispensa.** A prova de identidade, a lista de bloqueio, a prova de vida e a busca de rosto duplicado decidem exatamente como decidiriam fora do ponto, e a cobrança é a mesma.

**De onde ele nasce.** De uma verificação **aprovada** feita no local, aberta no painel em Verificações, com a ação **Declarar este local como ponto de atendimento**. Você diz onde o atendimento aconteceu, no aparelho que enviou ou no computador que mostrou o QR, e o painel nunca pede nem mostra o endereço de rede: ele vem da própria verificação. Escolha o alcance (a conta inteira ou só o flow da verificação), o tipo (com atendente ou totem sem atendente) e um rótulo curto do local, sem nome de pessoa. A declaração vale só para a rede que a sua empresa controla no local, nunca para a rede de convidados, e os aparelhos de captura precisam estar nessa rede. Nem toda verificação pode originar um ponto, e nem toda rede pode ser declarada: o painel recusa sem detalhar o motivo.

**Quem declara.** O proprietário da conta, ou um administrador com a permissão própria **Gerenciar pontos de atendimento**, que só o proprietário concede. Declarar e renovar pedem o código do aplicativo autenticador, e todo proprietário da conta recebe um e-mail a cada declaração. Revogar não pede código e vale na hora. Não existe rota da chave secreta para o ponto: declarar exige uma pessoa, a permissão e o segundo fator. Sandbox e produção têm pontos separados.

**Por quanto tempo.** A declaração vale por um mês e pode ser renovada, em lote, quando houve verificação aprovada no ponto no último mês. Sem renovação, ela vence sozinha.

**Suspensão.** Um ponto pode ser suspenso automaticamente, e os proprietários recebem um e-mail. Suspenso, ele deixa de valer: as verificações do local voltam ao tratamento normal, e para voltar a valer é preciso uma declaração nova.

**Acompanhamento e trilha.** Em Configurações, na tela de Segurança, cada ponto mostra o estado, o vencimento, quem declarou e quando, e o volume do último mês: verificações, aprovadas, em revisão, negadas, picos e fraudes confirmadas. Cada declaração, renovação, revogação, suspensão e vencimento fica registrado com quem fez e quando. A verificação que chegou de um ponto mostra, no detalhe e na fila de revisão, o rótulo do ponto.

## 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, sem começar por hífen), não pode se repetir no arquivo e nunca é o documento da linha, nem outro dado pessoal: use o id do titular no seu sistema. 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. O arquivo enviado é apagado logo depois de o lote ser aceito ou recusado (se o envio não for concluído, em até 8 dias), e o resultado, 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.

**Gerenciar pontos de atendimento.** Declara, renova e revoga os pontos de atendimento da conta. O proprietário tem pelo papel; um administrador só tem se o proprietário conceder.

As três 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.