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.

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