> ## Documentation Index
> Fetch the complete documentation index at: https://docs.id.zapsign.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução

> Base URL, autenticação, formato dos objetos e códigos de resposta da API da ID ZapSign.

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.

```
https://api.id.zapsign.com.br/v1
```

## Autenticação

Envie sua chave de API no cabeçalho `Authorization`.

```
Authorization: Bearer sk_...
```

Crie e revogue chaves no [painel](https://id.zapsign.com.br/app) ou pelos endpoints de [Chaves de API](/chaves-de-api/criar). O token completo aparece uma única vez, na criação.

<Warning>
  Sua chave dá acesso ao saldo da conta. Use no servidor, nunca no navegador nem em app mobile.
</Warning>

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

Os três endpoints de criação de validação aceitam o cabeçalho `Idempotency-Key`. Reenviar a mesma chave devolve a resposta original em vez de criar e cobrar outra validação.

```
Idempotency-Key: a3f1c9e2-7b64-4d18-9a02-5c6e8f0b1d34
```

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

<Note>
  `POST /api-keys` não aceita `Idempotency-Key`. Cada chamada emite um segredo novo, por definição.
</Note>

## Códigos de resposta

| Status | O que significa                                                   |
| ------ | ----------------------------------------------------------------- |
| `200`  | Sucesso. Em uma criação, o corpo já é o resultado final.          |
| `201`  | Recurso criado. Continua existindo depois da resposta.            |
| `400`  | O corpo ou um parâmetro não bate com o contrato.                  |
| `401`  | Chave de API ausente ou inválida.                                 |
| `402`  | Saldo insuficiente.                                               |
| `403`  | A chave não tem permissão para esta operação.                     |
| `404`  | O recurso não existe.                                             |
| `409`  | Outra requisição com a mesma `Idempotency-Key` está em andamento. |
| `413`  | Corpo maior que o limite.                                         |
| `422`  | O valor é válido no formato, mas quebra uma regra de negócio.     |
| `429`  | Limite de requisições excedido.                                   |
| `500`  | Erro nosso.                                                       |

Nas criações de validação, `200` e `201` marcam modos de execução diferentes. [Vínculo entre CPF e telefone](/validacoes/cpf-telefone) e [troca de chip](/validacoes/troca-de-chip) resolvem dentro da requisição e respondem `200`, com o resultado no corpo. [Prova de vida + documento](/validacoes/selfie-documento) responde `201`: cria uma validação `pending`, com `validation_url` para o titular, cujo resultado você busca depois em [`GET /validations/{id}`](/validacoes/consultar).

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](/erros).

## Por onde começar

<CardGroup cols={2}>
  <Card title="Vínculo entre CPF e telefone" icon="smartphone" href="/validacoes/cpf-telefone">
    Validação síncrona: a resposta já traz o resultado.
  </Card>

  <Card title="Prova de vida + documento" icon="id-card" href="/validacoes/selfie-documento">
    Validação hospedada: você redireciona o titular e consulta depois.
  </Card>
</CardGroup>