Criar validação de troca de chip

Authorizations

Authorization

string

header

required

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

Idempotency-Key

string

Torna a operação segura para retentativa. Reenviar a mesma chave repete a resposta original em vez de executar a operação de novo.

Required string length: 1 - 256

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

Body

application/json

Dados para criar uma validação de troca de chip.

phone

string

required

Telefone celular brasileiro do titular, em formato E.164.

Example:

"+5511999998888"

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

max_age_hours

integer

Janela, em horas, para considerar uma troca de chip como recente.

Required range: 1 <= x <= 2400

Example:

24

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 concluída.

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

Available options:

liveness_document_match,

liveness_cpf_match,

cpf_phone_match,

sim_swap,

telco_financial_capacity,

phone_ownership

status

enum<string>

required

Estado atual.

Valor	O que é
`pending`	Criada, aguardando o titular concluir o fluxo hospedado ou devolver o código
`completed`	Resolvida; veja `result`
`failed`	Não foi possível concluir
`expired`	O prazo 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`, `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`.

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

Available options:

liveness_failed,

face_mismatch,

spoof_detected,

document_tampered,

document_invalid,

document_unreadable,

cpf_reference_not_found,

data_unavailable,

phone_not_covered,

invalid_code

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 validação vence, em ISO-8601. Preenchida nas validações hospedadas e nas que enviam um código; null nas síncronas.

attempts_remaining

integer | null

required

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.

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

Referência da API

Validações

Chaves de API

Criar validação de troca de chip

Authorizations

Headers

Body

Response