O painel de API: credenciais, uso, logs e o dicionário de erros

Boa parte das dúvidas que chegam ao suporte de uma API de assinatura já tem resposta pronta numa tela que o integrador raramente abre. Por que esta chamada deu 409? Quanto da cota eu já consumi? Qual das minhas três credenciais está gerando erro? Este webhook chegou a ser entregue? São perguntas de painel, não de chamado — e o painel de API da SignDocs Brasil responde a todas, incluindo um dicionário que explica cada código de erro em português ao lado da requisição que falhou. Este guia percorre o que existe lá, aba por aba, com atenção ao que costuma passar despercebido.

Duas coisas que valem para o painel inteiro

O seletor de ambiente separa tudo. Trocar entre HML e PROD recarrega todas as abas contra a base daquele ambiente, então cotas, logs, credenciais e webhooks nunca se misturam. Isso evita a confusão clássica de olhar um número de sandbox achando que é produção — vale conferir o seletor antes de tirar qualquer conclusão de um gráfico.

A paleta de comandos (Ctrl+K) pula direto para uma aba, atualiza a atual, copia a Base URL do ambiente ou alterna entre HML e PROD. Copiar a Base URL do ambiente correto é, sozinho, um pequeno seguro contra a categoria de bug mais chata que existe numa integração — apontar para o ambiente errado.

Visão Geral: o veredito em cartões

A tela de abertura reúne 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, o que poupa a interpretação de números absolutos sem linha de base.

Abaixo vêm as barras de Cota de Uso (mensal e diária), os Erros Recentes e uma lista de Primeiros Passos com barra de progresso, que desaparece sozinha quando o onboarding é concluído.

Um aviso no topo indica Modo Sandbox ou Modo Produção. Vale ler com atenção: em sandbox, as transações não produzem evidências reais.

Credenciais: onde elas nascem e morrem

Ao criar uma credencial você escolhe um nome opcional, o método de autenticação (Client Secret ou Private Key JWT, com JWKS por URI ou inline, validado na hora), o ambiente e os escopos — e a lista de escopos vem do servidor, então nunca fica defasada em relação ao que a API realmente aceita.

O nome é opcional e vale a pena preencher. Seis meses depois, "qual sistema usa esta chave?" é uma pergunta difícil sem ele — e difícil de responder é o que atrasa uma rotação de emergência.

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

Cada cartão tem um botão de Analytics que isola as métricas daquela credencial em janelas de 24 horas, 7 ou 30 dias, com os endpoints mais chamados por ela. É o caminho mais curto para responder "qual das minhas integrações está gerando erro" ou "quem está consumindo a cota" — perguntas que, sem isso, viram uma investigação.

Os botões Pausar, Rotacionar e Revogar ficam aqui; o que cada um faz, e a janela de 24 horas da rotação, estão em rotação de credenciais sem downtime. Credenciais com Private Key JWT trocam o botão de rotação por Atualizar JWKS.

Mexer em credenciais de produção exige papel MASTER. Papel DEVELOPER mantém autonomia total sobre as de sandbox.

Webhooks: 20 eventos, e três que deixaram de existir

A aba cadastra endpoints HTTPS e seleciona quais dos 20 eventos receber, agrupados por tema:

Detalhe que evita expectativa errada: os três eventos por etapa — STEP.STARTED, STEP.COMPLETED e STEP.FAILED — foram retirados em setembro de 2026. Estavam na lista havia um ano sem nunca terem sido emitidos, o que é pior do que não existirem: uma integração podia assiná-los e esperar para sempre. Os 20 restantes têm produtor no código.

Cada webhook pode ser ativado ou desativado sem ser apagado — útil para silenciar um endpoint com problema sem perder a configuração. O segredo de assinatura é rotacionável aqui, e nesse caso o anterior é invalidado imediatamente, sem janela de sobreposição; as consequências disso estão no artigo de rotação.

Uso: a única tela que avisa antes

Consumo por dimensão — Documentos, Transações, Click, OTP, Biometria, Assinatura e SERPRO — em barras mensais e diárias, com filtro entre todos, sandbox e produção.

Dois cartões merecem atenção especial:

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

API Logs: o dicionário de erros

Visualizador das requisições das últimas 24 horas, com Live Tail que atualiza a cada 3 segundos, filtros por método HTTP, por faixa de status (2xx, 4xx, 5xx) e por modo, detalhe por requisição em painel lateral, e exportação em JSON ou CSV.

E aqui está a função mais subestimada do painel inteiro: 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 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 formal continua em códigos de erro e tratamento de falhas, mas o dicionário do painel tem uma vantagem que a documentação não tem: ele aparece ao lado da sua requisição real, com os seus parâmetros.

Auditoria, Transações e Analytics

Auditoria busca transações por período e status, com Baixar Evidência por transação (gera uma URL assinada) e exportação da lista inteira em JSON ou CSV — útil para instruir um processo, responder auditoria interna ou reconciliar com o seu sistema. A reconciliação periódica, aliás, é a prática que pega o que o webhook não trouxe, como descrito em o que monitorar numa integração.

Transações é a lista operacional, paginada e filtrável. Expandindo uma, aparecem signatário, política aplicada, hash do documento, expiração, etapas, número de tentativas, início, fim e o evidenceId quando já existe. O número de tentativas é um dado que raramente é olhado e diz muito sobre a experiência real de quem assina.

Analytics agrega em janelas de 1 hora, 24 horas, 7 ou 30 dias, com filtro por credencial: requisições, taxa de erro, latência média e p95 no topo; abaixo, volume ao longo do tempo, latência em p50/p95/p99, entregas de webhook, distribuição por status e os endpoints mais chamados.

Docs e API Explorer: a chamada de verdade

Uma referência da API embutida, com a Base URL do ambiente copiável, e duas ferramentas:

Experimentar (API Explorer) — escolha uma credencial ativa, autentique por segredo ou por JWT, preencha parâmetros de corpo, query, path ou header e envie. A resposta é real: status, cabeçalhos, corpo e latência em milissegundos, tudo copiável. É o caminho mais curto entre ler a documentação e ver a chamada funcionando — e, num diagnóstico, é como separar "a API está recusando" de "o meu código está montando a requisição errada".

Snippets de código — cada endpoint gera exemplo 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.

Um roteiro de diagnóstico pelo painel

1. Confira o seletor de ambiente. Metade das confusões morre aqui.
2. Visão Geral: algum cartão marcado como Acima do normal?
3. API Logs, filtrando por 4xx e 5xx: o dicionário costuma dar a resposta na própria linha.
4. Analytics filtrado por credencial: o problema é geral ou de uma integração só?
5. Uso: a Previsão indica estouro de cota no horizonte?
6. Credenciais → Último uso: alguma chave sendo usada fora da janela esperada?
7. API Explorer: reproduza a chamada manualmente para separar API de código.

Só depois disso vale abrir um chamado — e, se abrir, os exports em JSON ou CSV dos logs e da auditoria são exatamente o anexo que acelera a resposta.

Perguntas Frequentes