curl --request POST \
--url https://api.id.zapsign.com.br/v1/validations/liveness-document-match \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"consent": true
}
'{
"object": "validation",
"id": "val_06YGSA9CF0V6RVXT326BS4K1ZA",
"type": "liveness_document_match",
"status": "pending",
"result": null,
"reason_code": null,
"external_id": "pedido_12345",
"created_at": "2026-08-07T14:20:00Z",
"resolved_at": null,
"validation_url": "https://id.zapsign.com.br/validate/val_06YGSA9CF0V6RVXT326BS4K1ZA",
"expires_at": "2026-08-08T14:20:00Z",
"attempts_remaining": null,
"details": null
}Criar validação de prova de vida + documento
Confirma que o titular é uma pessoa real e dono do documento que apresenta. É hospedada e assíncrona: a resposta vem com status igual a pending e traz a validation_url para onde você redireciona o titular. O resultado chega depois, via GET /validations/{id}.
curl --request POST \
--url https://api.id.zapsign.com.br/v1/validations/liveness-document-match \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"consent": true
}
'{
"object": "validation",
"id": "val_06YGSA9CF0V6RVXT326BS4K1ZA",
"type": "liveness_document_match",
"status": "pending",
"result": null,
"reason_code": null,
"external_id": "pedido_12345",
"created_at": "2026-08-07T14:20:00Z",
"resolved_at": null,
"validation_url": "https://id.zapsign.com.br/validate/val_06YGSA9CF0V6RVXT326BS4K1ZA",
"expires_at": "2026-08-08T14:20:00Z",
"attempts_remaining": null,
"details": null
}Fluxo hospedado
validation_url como navegação de nível superior, com window.location.href = validation_url ou um link comum, de preferência depois de um gesto do titular. Nunca dentro de um iframe: o provedor bloqueia o embedding e a câmera do titular falha.Link aberto a partir de um app de mensagens
Navegadores embutidos de apps (Instagram, Facebook, WhatsApp) costumam bloquear a câmera, o que derruba qualquer fluxo de prova de vida. Quando o link chega por esses canais, oriente o titular a abrir no navegador do sistema. Bots de pré-visualização de link recebem uma página estática de marca e não consomem a sessão.Validade do link
expires_at governa o ciclo de vida da validation_url. Aberta depois de vencer, ou com a validação já resolvida, ela mostra uma página de marca (“Link expirado” ou “Verificação finalizada”), não um redirect quebrado. Uma validação pending que passa de expires_at sem conclusão vira expired.
Resultado
ConsulteGET /validations/{id} até o status sair de pending. Webhooks de saída para o integrador ainda não existem.Authorizations
Duas credenciais são aceitas no cabeçalho Authorization: Bearer ...: sua chave de API (prefixo sk_, criada no painel ou pelos endpoints de Chaves de API) ou um access token OAuth 2.1 do ZapSign ID (Authorization Code + PKCE S256, emissor https://id.zapsign.com.br, audiência https://api.id.zapsign.com.br/v1). Tokens OAuth carregam os escopos validations:read (consultas) e validations:write (criação e verificação) e não têm acesso aos endpoints de Chaves de API — esses exigem chave sk_ com full_access. Token OAuth rejeitado responde 401 com code invalid_token; escopo insuficiente responde 403 com code insufficient_scope e o cabeçalho WWW-Authenticate indicando o escopo exigido. Descoberta: https://id.zapsign.com.br/.well-known/oauth-authorization-server (servidor de autorização, RFC 8414) e https://api.id.zapsign.com.br/.well-known/oauth-protected-resource/v1 (recurso protegido, RFC 9728). Disponibilidade: o OAuth entra em produção na próxima publicação da plataforma; antes de integrar, confirme que os URLs de descoberta respondem JSON (e não 404) e, enquanto isso, autentique com a chave sk_.
Headers
Body
Dados para criar uma validação de prova de vida com confronto de documento.
Response
Validação criada em estado pending, com validation_url e expires_at preenchidos.
Resultado de uma validação.
Tipo da validação.
| Valor | O que é |
|---|---|
cpf_phone_match | Vínculo entre CPF e telefone |
sim_swap | Troca de chip |
liveness_document_match | Prova de vida + documento |
phone_ownership | Posse do telefone, por código no WhatsApp |
liveness_cpf_match | Prova de vida + CPF |
telco_financial_capacity | Capacidade financeira via operadora |
Os quatro primeiros têm endpoint de criação. Os outros dois podem aparecer em consultas e listagens de contas que os usam por outros canais.
liveness_document_match, liveness_cpf_match, cpf_phone_match, sim_swap, telco_financial_capacity, phone_ownership Resultado de negócio. É null enquanto status for pending.
| Valor | Aparece em |
|---|---|
match / no_match | cpf_phone_match |
recent_swap / no_recent_swap | sim_swap |
passed / not_passed | liveness_document_match, liveness_cpf_match, phone_ownership |
high_capacity / moderate_capacity / low_capacity | telco_financial_capacity |
unknown | Qualquer tipo, quando a fonte não deu uma resposta conclusiva. O motivo vem em reason_code. |
passed, not_passed, match, no_match, recent_swap, no_recent_swap, high_capacity, moderate_capacity, low_capacity, unknown Por que o resultado foi o que foi. É null quando o resultado não precisa de explicação. Acompanha unknown na maioria dos casos, e também not_passed quando a validação foi recusada por um motivo específico.
| Valor | O que é |
|---|---|
liveness_failed | Prova de vida não confirmada |
face_mismatch | O rosto não corresponde ao documento |
spoof_detected | Suspeita de fraude na captura |
document_tampered | Indícios de adulteração no documento |
document_invalid | Documento inválido ou não aceito |
document_unreadable | O documento não pôde ser lido |
cpf_reference_not_found | CPF não encontrado na base de referência |
data_unavailable | Dados indisponíveis na fonte consultada |
phone_not_covered | Telefone sem cobertura para a consulta |
invalid_code | O código enviado não confere, e as tentativas acabaram |
liveness_failed, face_mismatch, spoof_detected, document_tampered, document_invalid, document_unreadable, cpf_reference_not_found, data_unavailable, phone_not_covered, invalid_code Quantas chamadas de verificação ainda serão aceitas. Preenchida nos tipos que enviam um código para a pessoa devolver (hoje só phone_ownership) e null nos demais.
Vale 0 assim que a validação é resolvida, em qualquer desfecho, porque nenhuma outra tentativa será aceita.
Was this page helpful?