Skip to main content
A API da ID ZapSign valida a identidade de uma pessoa a partir do CPF, do telefone ou de um documento com selfie. Você cria uma validação e recebe o resultado, e cada validação desconta do saldo da conta.

​
Base URL

Todas as requisições partem desta URL, sempre por HTTPS.

​
Autenticação

Envie sua chave de API no cabeçalho Authorization.
Crie e revogue chaves no painel ou pelos endpoints de Chaves de API. O token completo aparece uma única vez, na criação.
Sua chave dá acesso ao saldo da conta. Use no servidor, nunca no navegador nem em app mobile.

​
OAuth 2.1 (para integrações que agem em nome do usuário)

Além da chave sk_, a API aceita access tokens OAuth 2.1 emitidos pelo ZapSign ID (fluxo Authorization Code com PKCE S256, clientes públicos, sem client secret). O token vai no mesmo cabeçalho:
  • Emissor (issuer): https://id.zapsign.com.br
  • Autorização: https://id.zapsign.com.br/oauth/authorize
  • Token: https://id.zapsign.com.br/oauth/token
  • Revogação: https://id.zapsign.com.br/oauth/revoke
  • JWKS: https://id.zapsign.com.br/oauth/jwks
  • Descoberta do servidor de autorização (RFC 8414): https://id.zapsign.com.br/.well-known/oauth-authorization-server
  • Descoberta do recurso protegido (RFC 9728, na origem da API): https://api.id.zapsign.com.br/.well-known/oauth-protected-resource/v1 (é o mesmo URL anunciado em resource_metadata nos desafios WWW-Authenticate)
  • Recurso protegido (audiência aud do token): https://api.id.zapsign.com.br/v1
  • Escopos: validations:read (consultas e listagens) e validations:write (criação e confirmação de código). Omitir scope na autorização concede os dois.
O suporte a OAuth entra em produção na próxima publicação da plataforma. Antes de integrar, confirme que os dois endereços de descoberta acima respondem JSON (e não 404); enquanto isso, use a chave sk_.
O access token expira em 15 minutos; o refresh token dura 30 dias e é rotacionado a cada uso: reutilizar um refresh token antigo revoga a autorização inteira. Token inválido ou expirado responde 401 com code invalid_token; escopo insuficiente responde 403 com code insufficient_scope e o cabeçalho WWW-Authenticate indica o escopo exigido. Os endpoints de Chaves de API não aceitam tokens OAuth: exigem chave sk_ com full_access.

​
Objetos

Toda resposta traz um campo object que diz o que você recebeu: validation, api_key ou list. Os identificadores levam um prefixo do tipo, seguido de um ULID: val_ para validações, key_ para chaves. Datas são strings ISO-8601 em UTC.

​
Idempotência

Todos os POST /validations/* aceitam o cabeçalho Idempotency-Key, das criações à confirmação de código. Reenviar a mesma chave devolve a resposta original em vez de executar a operação de novo. Numa criação, isso é uma validação a menos criada e cobrada.
Quando a resposta é uma repetição, ela vem com Idempotent-Replayed: true. Use uma chave nova por operação de negócio, e a mesma chave em todas as retentativas dessa operação. Reaproveitar a chave com um corpo diferente responde 400 com idempotency_key_reuse.
POST /api-keys não aceita Idempotency-Key. Cada chamada emite um segredo novo, por definição.

​
Códigos de resposta

Nas criações de validação, 200 e 201 marcam modos de execução diferentes. Vínculo entre CPF e telefone e troca de chip resolvem dentro da requisição e respondem 200, com o resultado no corpo. As criações assíncronas respondem 201 e resolvem depois. Prova de vida + documento traz uma validation_url para o titular, e o resultado você busca em GET /validations/{id}. Posse de telefone por WhatsApp não tem validation_url: o resultado sai quando você confirma o código em POST /validations/{id}/verify. A diferença entre 400 e 422 é deliberada. 400 é problema de contrato (campo faltando, tipo errado). 422 é problema de conteúdo (um CPF que não passa no dígito verificador, por exemplo). Todo erro responde no mesmo formato, com um code estável e um doc_url que aponta para a explicação. A lista completa está em Erros.

​
Por onde começar

Vínculo entre CPF e telefone

Validação síncrona: a resposta já traz o resultado.

Prova de vida + documento

Validação hospedada: você redireciona o titular e consulta depois.