API Dashboard — o painel de controle da API

Credenciais, webhooks, cotas, logs ao vivo, métricas e um explorador de API — tudo dentro do app SignDocs, sem abrir chamado.

⚠️ Quem vê o painel

• Conta Pessoa Jurídica (com CNPJ) e plano Enterprise. Pessoa Física não tem acesso à API.
• Ative pelo navegador ou pelo Android — no iOS o card Enterprise não aparece, por regra da App Store. O app iOS está publicado e funciona normalmente para assinar; apenas a contratação do Enterprise não é exibida nele.
• Papel MASTER → 14 abas. Papel DEVELOPER → 11 abas (sem Segurança, Equipe e LGPD).

Como chegar lá

Depois de ativar as credenciais, o painel fica acessível por dois caminhos dentro de app.signdocs.com.br:

• o card API Dashboard na tela inicial;
• o menu de Perfil (avatar) → Abrir API Dashboard.

A primeira tela lista os tenants a que você tem acesso, com o papel, o status e o ambiente de cada um. Ao abrir um tenant, você cai no workspace de abas descrito abaixo.

A barra superior: ambiente e paleta de comandos

Dois controles valem para o painel inteiro:

• HML / PROD — um seletor que troca o ambiente. Todas as abas são recarregadas contra a base do ambiente escolhido, então cotas, logs, credenciais e webhooks nunca se misturam entre sandbox e produção.
• Paleta de comandos (Ctrl+K) — busca por comando para pular direto para uma aba, atualizar a aba atual, copiar a Base URL do ambiente ou alternar entre HML e PROD.

1. Visão Geral

A tela de abertura do tenant. Reúne, em cartões:

• Requisições Hoje, Taxa de Erro (24h), Latência Média (24h), Entrega de Webhook (24h), Credenciais Ativas e Webhooks Ativos, cada um com um veredito de Saudável ou Acima do normal;
• Cota de Uso — barras de consumo mensal e diário;
• Erros Recentes — os últimos erros, ou a confirmação de que não houve nenhum;
• Primeiros Passos — uma lista de verificação de onboarding com barra de progresso, que some sozinha quando você conclui todos os itens.

Um aviso no topo indica se você está em Modo Sandbox ou Modo Produção. Em sandbox, as transações não produzem evidências reais.

2. Credenciais

Onde as credenciais nascem, mudam de estado e morrem.

Ao criar, você escolhe:

• um nome opcional, para saber depois qual sistema usa cada credencial;
• o método de autenticação — Client Secret ou Private Key JWT (com JWKS por URI ou inline, validado na hora);
• o ambiente — Sandbox ou Production;
• os escopos. A lista vem do servidor, então nunca fica desatualizada em relação ao que a API aceita.

Cada credencial aparece como um cartão com clientId selecionável, data de criação, data do último uso, status (Ativa, Pausada ou Revogada), ambiente, método de autenticação, aviso de expiração e os escopos concedidos.

O expansor Dados da integração reúne, com botão de copiar, tudo que sua aplicação precisa: tenantId, client_id, Base URL, Token URL, escopos concedidos e um bloco cURL pronto para obter um token. O client_secret não aparece ali: ele é guardado apenas como hash e não pode ser recuperado — nem por nós.

O botão Analytics de cada cartão abre as métricas daquela credencial isolada, em janelas de 24h, 7 ou 30 dias, com os endpoints mais chamados por ela. É o caminho mais rápido para descobrir qual integração está gerando erro ou consumindo cota.

Pausar, Rotacionar ou Revogar — qual usar

Ação	O que acontece	Quando usar
Pausar	As chamadas com a credencial passam a responder 503 e nenhum token novo é emitido. Leva até 60 segundos para valer em todas as instâncias. O clientId e o secret continuam os mesmos.	Parar uma integração suspeita ou barulhenta sem mexer na configuração de ninguém. Reativar não exige mudança na aplicação.
Rotacionar	Um novo secret é gerado na hora e exibido uma única vez. O secret anterior continua válido por mais 24 horas.	Troca periódica, ou secret perdido. A janela de 24 h existe para você atualizar o cofre e reiniciar as aplicações sem interrupção.
Revogar	Invalida a credencial. Não pode ser desfeito.	Vazamento confirmado, ou desligamento definitivo de uma integração.

Para credenciais que usam Private Key JWT, o botão de rotação dá lugar a Atualizar JWKS, que troca a URI ou o conteúdo inline do conjunto de chaves.

💡 Pausar age sobre uma credencial. Para derrubar o tenant inteiro de uma vez, use os kill switches da aba Segurança.

Quem pode mexer em produção

Criar ou alterar credenciais de produção exige papel MASTER. Quem tem papel DEVELOPER continua com autonomia total sobre as credenciais de sandbox — cria, pausa, rotaciona e revoga sem depender de ninguém.

3. Webhooks

Cadastre endpoints HTTPS e escolha quais eventos quer receber. Os 20 eventos disponíveis:

Grupo	Eventos
Transação	TRANSACTION.CREATED TRANSACTION.COMPLETED TRANSACTION.CANCELLED TRANSACTION.FAILED TRANSACTION.EXPIRED TRANSACTION.FALLBACK TRANSACTION.DEADLINE_APPROACHING
Sessão	SIGNING_SESSION.CREATED SIGNING_SESSION.COMPLETED SIGNING_SESSION.CANCELLED SIGNING_SESSION.EXPIRED
Envelope	ENVELOPE.CREATED ENVELOPE.ALL_SIGNED ENVELOPE.CANCELLED ENVELOPE.EXPIRED
Etapa	STEP.PURPOSE_DISCLOSURE_SENT
Cadastro biométrico	ENROLLMENT.EXPIRING ENROLLMENT.EXPIRED
Operacional	QUOTA.WARNING API.DEPRECATION_NOTICE

Todos os 20 têm produtor no código. Os três eventos STEP.* por etapa (STARTED, COMPLETED, FAILED) foram retirados em setembro de 2026: estavam na lista havia um ano sem nunca terem sido emitidos.

Cada webhook pode ser ativado ou desativado sem ser apagado, e tem o secret de assinatura rotacionável — nesse caso o secret anterior é invalidado imediatamente, então atualize a verificação de assinatura antes de rotacionar.

O botão Ver Entregas abre o histórico recente com o status e a latência de cada tentativa, e um botão Reenviar por entrega. É o caminho normal para investigar "o evento não chegou": você vê se a entrega saiu, com que resposta, e a reenvia sem precisar reproduzir a transação.

Painel ou API?

As duas superfícies não são idênticas — vale saber o que só existe de cada lado.

Recurso	Painel	API
Criar, listar, ativar/desativar e excluir webhook	✅	✅
Rotacionar o secret de assinatura	✅	✅
Histórico de entregas com latência	✅	—
Reenviar uma entrega real	✅	—
Disparar um payload de teste	—	✅ POST /v1/webhooks/{webhookId}/test

Ou seja: para provar que seu endpoint responde, use o disparo de teste pela API (veja o guia de webhooks). Para entender por que um evento real falhou, use o histórico e o reenvio no painel.

4. Uso

O consumo do tenant, por dimensão, em barras mensais e diárias: Documentos, Transações, Click, OTP, Biometria, Assinatura e SERPRO. Um filtro alterna entre Todos, Sandbox e Production.

Dois cartões merecem atenção:

• Previsão de Uso — projeta o fechamento do mês com base no ritmo atual e avisa quando a projeção passa da cota contratada. É o único lugar onde você descobre que vai estourar a cota antes de estourar.
• Uso Excedente (Overage) — mostra quanto já foi consumido além do plano base. O excedente é faturado manualmente no fim do mês, então acompanhar aqui evita surpresa.

📌 Rate limit e cota são coisas diferentes: o limite de requisições por segundo está descrito em Rate Limiting; a cota é mensal e diária e vive nesta aba. Não há endpoint público de consulta de cota — o consumo é acompanhado pelo painel ou pelo evento QUOTA.WARNING.

5. Auditoria

Busca de transações por período e por status (Concluído, Pendente, Falhou, Expirado), com paginação. Para cada transação você tem Baixar Evidência, que gera uma URL assinada de download do pacote probatório.

A lista inteira pode ser exportada em JSON ou CSV — útil para juntar a um processo, responder a auditoria interna ou reconciliar com o seu próprio sistema.

6. Transações

A lista operacional das transações, paginada e filtrável, com o progresso das etapas e a indicação de evidência disponível. Ao expandir uma transação você vê signatário, política aplicada, hash do documento, data de expiração, etapas, número de tentativas, início, fim e o evidenceId quando já existe.

Os status possíveis são Criado, Documento Enviado, Assinando, Concluído, Falhou e Cancelado.

7. API Logs

O visualizador de requisições das últimas 24 horas, com contagem total e detalhe por linha.

• Live Tail (3s) — liga e desliga; enquanto ligado, novas requisições aparecem sozinhas a cada 3 segundos.
• Filtros por método HTTP, por faixa de status (2xx OK, 4xx Erro, 5xx Server) e por modo (sandbox ou produção).
• Detalhe por requisição, em um painel lateral.
• Exportar JSON e Exportar CSV.

O dicionário de erros

Esta é a função mais subestimada do painel. Para os códigos 400, 401, 403, 404, 409, 422, 429, 500, 502 e 503, o log traz — ao lado da requisição que falhou — um título, uma explicação em português e uma linha de "como corrigir". Um 429, por exemplo, sugere backoff exponencial e aponta a aba Uso para conferir as cotas.

Na prática, isso resolve a maior parte das dúvidas de integração sem abrir chamado. O catálogo completo e formal dos erros continua em Referência de Erros.

8. Analytics

Métricas agregadas em janelas de 1 hora, 24 horas, 7 dias ou 30 dias, com opção de filtrar por credencial.

Os indicadores de topo são Requisições, Taxa de Erro, Latência Média e latência p95. Abaixo vêm os gráficos:

• Volume de Requisições ao longo do período;
• Latência com as séries p50, p95 e p99;
• Entregas de Webhook;
• Distribuição por Status;
• Top Endpoints — a tabela dos endpoints mais chamados.

9. Docs e API Explorer

Uma referência da API embutida no painel, com filtro por tag, parâmetros e respostas por endpoint, e a Base URL do ambiente copiável em um clique.

Duas ferramentas moram aqui:

• Experimentar (API Explorer) — escolha uma credencial ativa, autentique por secret ou por JWT, preencha os parâmetros de corpo, query, path ou header e envie a requisição. A resposta que volta é real: status, headers, corpo e a latência em milissegundos, tudo copiável. É o caminho mais curto entre ler a documentação e ver a chamada funcionando.
• Snippets de código — cada endpoint gera exemplo pronto em cURL, Python, Node.js, Java, PHP, Go e C#, com variantes separadas para autenticação por client_secret e por private_key_jwt.

Há ainda um cartão Assinatura Expressa — Comece aqui, que monta o snippet conforme você alterna entre signatário único e envelope, ordem paralela ou sequencial, quantidade de signatários e perfil de assinatura (Click, Click + OTP, Biometria, Biometria + OTP, Certificado Digital, Biometria SERPRO e SERPRO com fallback). Ele aponta para as receitas de Assinatura Expressa quando você quer o exemplo completo.

10. Status

Saúde dos componentes — database, api e webhooks — com atualização automática a cada 30 segundos e um botão de verificação manual. Cada componente aparece como Operacional ou Degradado, com um aviso no topo quando há degradação. Os compromissos formais de disponibilidade estão no SLA.

11. Atividade

Uma linha do tempo dos eventos do tenant, com horário relativo e filtro por tipo: chamadas de API, erros de API, webhooks entregues, webhooks falhados e criação de credenciais. Serve para responder rápido a "o que mudou aqui nas últimas horas".

12. Segurança

Disponível para o papel MASTER. Reúne os controles que você quer ter à mão em um incidente.

• Kill switches — desligam o tenant inteiro, ou seletivamente biometria, OTP e liveness hospedado. A mudança leva até 60 segundos para valer em todas as instâncias, e o switch de tenant afeta sandbox e produção ao mesmo tempo. Para parar apenas uma integração, pause a credencial na aba Credenciais.
• Feature flags — política personalizada, liveness hospedado, biometria obrigatória, fallback de OTP, imagem de referência por transação, extração de documento e conformidade NT65.
• Cotas — as cotas de produção aparecem em bloco somente leitura, porque são as contratadas; as de sandbox são editáveis.
• Configuração biométrica — limiar de confiança, número máximo de tentativas e tempo de espera entre elas.
• Limite de excedente — capacidade extra além do plano base, por método.
• mTLS — envio e remoção do certificado CA. Esta seção só aparece quando o mTLS está habilitado no seu plano.
• Alertas — liga/desliga, destinatários por e-mail e limiar de alerta de cota.

Cotas de produção, feature flags e limite de excedente são definidos pelo seu plano e aparecem em modo leitura. Para alterá-los, fale com o time comercial da SignDocs.

13. Equipe

Disponível para o papel MASTER. Convide pessoas por e-mail e atribua um dos dois papéis:

Papel	Alcance
Master	Acesso total, incluindo credenciais de produção, segurança, equipe e LGPD.
Desenvolvedor	Credenciais (sandbox), webhooks, uso e auditoria.

Membros podem ser ativados, desativados ou removidos, e a tela mostra os totais por papel. Há uma trava: não é possível remover o último Master do tenant.

14. LGPD

Disponível para o papel MASTER. Um registro das solicitações de titulares de dados, com fluxo de tratamento — não apenas uma caixa de e-mail.

Cada solicitação tem um tipo (Acesso, Exclusão, Portabilidade, Retificação ou Objeção), o identificador do titular (CPF ou e-mail), nome, descrição e observações. O status percorre Pendente, Aprovado, Negado, Processando, Concluído ou Falhou, e o registro guarda quem criou, quem processou, a resolução e a data de conclusão. Solicitações em estado terminal ficam travadas contra edição.

Na prática, é a trilha que demonstra atendimento ao titular dentro do prazo — a evidência que uma auditoria de LGPD costuma pedir.

Matriz de permissões

Aba	DEVELOPER	MASTER
Visão Geral	✅	✅
Credenciais	✅ sandbox	✅
Webhooks	✅	✅
Uso	✅	✅
Auditoria	✅	✅
Transações	✅	✅
API Logs	✅	✅
Analytics	✅	✅
Docs e API Explorer	✅	✅
Status	✅	✅
Atividade	✅	✅
Segurança	—	✅ (cotas e flags em leitura)
Equipe	—	✅
LGPD	—	✅

O que o painel não faz

Para evitar expectativa errada:

• Não dispara payload de teste de webhook. Ele reenvia entregas reais. O disparo de teste é chamada de API — veja a tabela de paridade acima.
• Não tem restrição de acesso por IP. Os controles de acesso disponíveis são escopos por credencial, pausa de credencial, kill switches e mTLS, quando habilitado no plano.
• Não recupera o client_secret. Ele é guardado apenas como hash. Perdeu, rotacione.
• Não expõe cota por API. Consumo e projeção são do painel; para reagir programaticamente, assine o evento QUOTA.WARNING.
• Não substitui a especificação. A referência normativa continua sendo o OpenAPI publicado em docs.signdocs.com.br.

Próximos passos

• Guia de Início Rápido — do zero ao documento assinado, incluindo a ativação das credenciais.
• Integração com Webhooks — assinatura HMAC, reentrega e o disparo de teste pela API.
• Rate Limiting — limites por segundo, cabeçalhos e política de retentativa.
• Rotação de Chaves e Segredos — a política por trás dos botões de rotação.
• Referência de Erros — o catálogo formal, no formato RFC 7807.