Criar validação de prova de vida + documento

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",
  "details": null
}

{
  "error": {
    "type": "invalid_request",
    "code": "missing_required_param",
    "message": "A required parameter is missing.",
    "param": "cpf",
    "doc_url": "https://docs.id.zapsign.com.br/missing_required_param",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid.",
    "doc_url": "https://docs.id.zapsign.com.br/invalid_api_key",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "payment_error",
    "code": "insufficient_balance",
    "message": "Insufficient balance for this validation.",
    "doc_url": "https://docs.id.zapsign.com.br/insufficient_balance",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_in_progress",
    "message": "A request with the same Idempotency-Key is still in progress.",
    "doc_url": "https://docs.id.zapsign.com.br/idempotency_in_progress",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "request_too_large",
    "message": "The request body is too large.",
    "doc_url": "https://docs.id.zapsign.com.br/request_too_large",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_cpf",
    "message": "The value provided is invalid.",
    "param": "cpf",
    "doc_url": "https://docs.id.zapsign.com.br/invalid_cpf",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after the indicated delay.",
    "doc_url": "https://docs.id.zapsign.com.br/rate_limit_exceeded",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "api_error",
    "message": "An internal error occurred.",
    "doc_url": "https://docs.id.zapsign.com.br/api_error",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

POST

validations

liveness-document-match

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",
  "details": null
}

{
  "error": {
    "type": "invalid_request",
    "code": "missing_required_param",
    "message": "A required parameter is missing.",
    "param": "cpf",
    "doc_url": "https://docs.id.zapsign.com.br/missing_required_param",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid.",
    "doc_url": "https://docs.id.zapsign.com.br/invalid_api_key",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "payment_error",
    "code": "insufficient_balance",
    "message": "Insufficient balance for this validation.",
    "doc_url": "https://docs.id.zapsign.com.br/insufficient_balance",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_in_progress",
    "message": "A request with the same Idempotency-Key is still in progress.",
    "doc_url": "https://docs.id.zapsign.com.br/idempotency_in_progress",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "request_too_large",
    "message": "The request body is too large.",
    "doc_url": "https://docs.id.zapsign.com.br/request_too_large",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_cpf",
    "message": "The value provided is invalid.",
    "param": "cpf",
    "doc_url": "https://docs.id.zapsign.com.br/invalid_cpf",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after the indicated delay.",
    "doc_url": "https://docs.id.zapsign.com.br/rate_limit_exceeded",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "api_error",
    "message": "An internal error occurred.",
    "doc_url": "https://docs.id.zapsign.com.br/api_error",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

Fluxo hospedado

Abra a 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

Consulte GET /validations/{id} até o status sair de pending. Webhooks de saída para o integrador ainda não existem.

Authorizations

Authorization

string

header

required

Sua chave de API no cabeçalho Authorization: Bearer sk_.... Crie e revogue chaves no painel ou pelos endpoints de Chaves de API.

Headers

Idempotency-Key

string

Torna a criação segura para retentativa. Reenviar a mesma chave repete a resposta original em vez de criar (e cobrar) uma validação nova.

Required string length: 1 - 256

Pattern: ^[A-Za-z0-9_-]{1,256}$

Body

application/json

Dados para criar uma validação de prova de vida com confronto de documento.

Confirma que o titular consentiu com a consulta. Precisa ser true.

redirect_url

string

Para onde o titular volta ao terminar o fluxo hospedado. Precisa ser https e um host público. Se você omitir, vale https://id.zapsign.com.br.

Example:

"https://sua-empresa.com.br/onboarding/concluido"

external_id

string

Sua referência de correlação. Volta em todas as respostas desta validação.

Required string length: 1 - 256

Pattern: ^[A-Za-z0-9_-]{1,256}$

Example:

"pedido_12345"

Response

Validação criada em estado pending, com validation_url e expires_at preenchidos.

Resultado de uma validação.

object

enum<string>

required

Sempre validation.

Available options:

validation

string

required

Identificador único da validação.

Example:

"val_0NQW3MVYJYQ453E95V3V1T76AV"

type

enum<string>

required

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
`liveness_cpf_match`	Prova de vida + CPF
`telco_financial_capacity`	Capacidade financeira via operadora

Os três primeiros têm endpoint de criação. Os outros dois podem aparecer em consultas e listagens de contas que os usam por outros canais.

Available options:

liveness_document_match,

liveness_cpf_match,

cpf_phone_match,

sim_swap,

telco_financial_capacity

status

enum<string>

required

Estado atual.

Valor	O que é
`pending`	Criada, aguardando o titular concluir o fluxo hospedado
`completed`	Resolvida; veja `result`
`failed`	Não foi possível concluir
`expired`	A sessão hospedada venceu sem conclusão

Available options:

pending,

completed,

failed,

expired

result

enum<string> | null

required

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

Available options:

passed,

not_passed,

match,

no_match,

recent_swap,

no_recent_swap,

high_capacity,

moderate_capacity,

low_capacity,

unknown

reason_code

enum<string> | null

required

Por que o resultado foi unknown. É null em qualquer outro caso.

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

Available options:

liveness_failed,

face_mismatch,

spoof_detected,

document_tampered,

document_invalid,

document_unreadable,

cpf_reference_not_found,

data_unavailable,

phone_not_covered

external_id

string | null

required

A referência de correlação que você enviou na criação.

created_at

string<date-time>

required

Data de criação em ISO-8601.

resolved_at

string<date-time> | null

required

Data de resolução em ISO-8601. É null enquanto não resolvida.

validation_url

string | null

required

URL para onde redirecionar o titular. Preenchida nas validações hospedadas; null nas síncronas.

expires_at

string<date-time> | null

required

Quando a sessão hospedada vence, em ISO-8601. Preenchida nas validações hospedadas; null nas síncronas.

details

object | null

required

Dados extraídos, agrupados pela chave do type. Hoje só liveness_document_match produz detalhes, e só com status igual a completed. Nos demais casos é null.

Show child attributes

⌘I

Referência da API

Validações

Chaves de API

Criar validação de prova de vida + documento

Fluxo hospedado

Link aberto a partir de um app de mensagens

Validade do link

Resultado

Authorizations

Headers

Body

Response

​Fluxo hospedado

​Link aberto a partir de um app de mensagens

​Validade do link

​Resultado

Authorizations

Headers

Body

Response

Fluxo hospedado

Link aberto a partir de um app de mensagens

Validade do link

Resultado