Docs

POST /v1/atos com o tipo, o sujeito (uma referência opaca do cliente e, se houver, a imagem de referência, cifrada só enquanto o ato está aberto, até 30 dias), o contexto opaco e o nível mínimo. O gateway resolve a política e devolve as etapas e o link da jornada.

Com a imagem de referência, a presença viva vem com match: é a mesma pessoa da referência. Sem ela, a etapa é presença viva, sem match.

Tipos cujas etapas ainda não executam respondem 501 dizendo qual etapa falta; nada é simulado.

GET /v1/atos com filtros por tipo, estado, resultado, referência do cliente, lote e período, e a trilha de etapas de cada ato (etapas=0 dispensa); GET /v1/atos/contagem, o total da mesma consulta; GET /v1/atos/exportar, a mesma consulta em CSV, até 50 000 linhas e sem dado do titular; GET /v1/atos/{id} com as etapas na ordem do servidor, o escopo, o encadeamento, o contexto só como hash e o veredito minimizado; POST /v1/atos/{id}/cancelar. A pessoa avança por POST /v1/atos/{id}/etapas/{nome}, pelo token do ato.

POST /v1/atos/{id}/evidencia abre o que o ato guarda cifrado, e exige uma pessoa com nível de supervisor, um motivo declarado e deixa registro. Ausência vai declarada em três estados distintos: aberto, apagado e nunca houve, porque somar os dois últimos apagaria a diferença entre um apagamento que aconteceu e um campo nunca preenchido.

GET /v1/atos/{id}/evidencia/acessos devolve quem abriu, quando e com que motivo, com as aberturas feitas pela Hummand junto e o elo de hash de cada uma. É a rota que o painel do cliente carrega antes de qualquer abertura. Cada linha traz o elo anterior e o id da requisição, e é conferível sozinha.

GET /v1/atos/{id}/acessos e GET /v1/acessos devolvem os recibos assinados humanproof-acesso/1 dessas aberturas, numa cadeia própria por cliente.

POST /v1/atos/lote cria vários atos do mesmo tipo com links e prazo comum, para campanhas e prova de vida; uma campanha maior se cria em partes de até 500, que seguem como uma só pelo lote_id. GET /v1/atos/lotes lista as campanhas, com nome, responsável e andamento; GET /v1/atos/lotes/{id}/relatorio presta contas de cada ato com o recibo que o prova, e GET /v1/atos/lotes/{id}/recibos devolve o trecho contínuo da cadeia; GET /v1/atos/lotes/{id}/pendentes devolve quem falta, com link reemitido. POST /v1/atos/{id}/referencia anexa a foto do cadastro depois da criação. POST /v1/atos/prova-excecao/fonte consulta uma fonte de estado vital a pedido e, se houver alerta, abre a prova de exceção.

Mandato: GET /v1/mandatos lista os concedidos, com quem recebeu a autoridade, situação e validade; GET /v1/mandatos/{id} devolve o estado e o escopo inteiro, para o executor comparar com a ação que a Hummand não conhece; POST /v1/mandatos/{id}/revogar derruba um; POST /v1/mandatos/revogar-lote derruba todos os de um mandatário ou de um cliente, com um recibo por mandato derrubado, porque o que um auditor confere é cada autoridade que caiu.

GET /v1/politica devolve a política efetiva por tipo: nível, etapas, prazo, rótulo e se é executável hoje. PUT /v1/politica, pelo Administrador, endurece a global por tipo, e cada edição é uma versão nova, listada em GET /v1/politica/versoes; GET /v1/politica/etapas diz o estado real de cada etapa. GET /v1/alerts computa as três situações na leitura, com filtro por tipo.

As rotas de checks seguem como alias por uma versão. POST /v1/document valida identidade civil (mock ou real, conforme o credenciamento). POST /v1/match e POST /v1/cpf avulsos respondem 501 por desenho: fora de um ato, não há prova.

GET /v1/atos/{id}/recibo devolve o recibo assinado, ou 202 enquanto pendente. GET /v1/recibos devolve o lote na ordem da cadeia, com filtro por data de emissão: é o que se exporta para verificar fora. GET /v1/verification-links/{token}/recibo é o comprovante de quem fez a jornada.

A chave pública está em /.well-known/humanproof/keys.json, como JWKS.

GET /v1/recibos/ponto devolve um objeto assinado com a mesma chave dos recibos, dizendo quantos recibos existiam e qual era o último hash. É o que fecha o único caso que o encadeamento sozinho não cobre: o corte do fim.

Quem audita guarda o ponto fora da Hummand e compara depois. Não há tabela nossa de pontos emitidos: a única cópia que vale é a de quem audita.

Endpoints por cliente com segredo rotacionável, entrega assinada e log de entregas; ping de teste pelo painel. Onze eventos assináveis, em dois vocabulários: os seis do check legado (completed, approved, rejected, needs_review, failed, expired), os três do ato (ato.concluido, ato.em_revisao, ato.expirado), recibo.emitido e mandato.revogado.

Os dois vocabulários convivem porque o payload legado não carrega tipo, nível nem resultado, e sem eles um ato delegado de nível 0 chegaria indistinguível de uma presença recorrente. mandato.revogado existe para quem cacheia autoridade parar de aceitá-la sem consultar a Hummand a cada ação.

O payload é sem dado pessoal por construção: ids, tipo, estado, resultado e hashes; nunca CPF, nunca conteúdo.

Na sexta falha o evento fica esgotado, sem se perder: GET /v1/webhooks/esgotados lista os esgotados, e POST /v1/webhooks/esgotados/{id}/reentregar devolve um à fila, com o mesmo event_id, para o receptor deduplicar.

As mesmas transições viram notificações no painel, com preferências por canal e por tipo.

verificar.hummand.com.br/s/{token} renderiza as etapas na ordem do servidor: transparência do contexto, consentimentos geral e biométrico, presença viva sob demanda, resultado e comprovante. Uma etapa que o gateway não executa aparece como ainda não disponível, nunca como sucesso.

A foto do cadastro pode ser anexada a cada ato depois da criação, também no lote, pelo painel ou por POST /v1/atos/{id}/referencia; com ela, a presença vem com match. Sem ela, a etapa é presença viva, sem match.

Sandbox com resultado simulado para testar a integração sem consumir presença nem entrar na cadeia.

dash.hummand.com.br: criar ato e campanha em lote, atos com busca e exportação em CSV, dossiê do ato, busca, minha fila, recibos com exportação do lote, mandatos, alertas, a tela ao vivo, orquestrações editáveis, ciclos de reverificação, unidades, privacidade com retenção, chaves de API, equipe com níveis de acesso e revisão de acessos, sessões, senha, passkey e SSO, webhooks, auditoria, analytics por período, uso e suporte.

Rotas que o painel usa e a API expõe com o mesmo contrato: GET /v1/ao-vivo, GET /v1/analytics com período livre e comparação, GET /v1/audit paginada e filtrável, GET /v1/auth/sessions, POST /v1/auth/sessions/encerrar-outras e POST /v1/auth/senha.

Desde a 0.23.0: GET /v1/atos/{id}/dossie, GET /v1/busca, GET /v1/atos/fila, POST /v1/atos/{id}/demonstracao (só ato de teste), /v1/auth/passkeys e POST /v1/auth/passkey, /v1/auth/sso/{provedor}/iniciar e /v1/sso, /v1/lista-ip, /v1/unidades, /v1/retencao e /v1/retencao/preservacoes, /v1/acessos/config e /v1/acessos/revisao, /v1/ciclos e /v1/suporte/chamados.

O contrato OpenAPI é exportado da aplicação e versionado; o cliente TypeScript é gerado dele e a versão acompanha a do gateway. O CI falha se contrato e cliente divergirem; nada é escrito à mão. Distribuição privada até decisão registrada.

A referência interativa da API fica atrás do acesso da borda até a documentação pública. Peça o acesso pelo contato; a conversa é técnica, direto com quem constrói.