Painel de operação

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 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.