Visão geral

A API pública da Legitimuz: as quatro rotas, como autenticam e o que fica do lado do widget.

A API pública tem quatro rotas. O seu servidor cria a verificação com POST /public/verifications, e o desfecho chega por webhook. Para ler os dados ou as imagens de uma verificação, use as três rotas GET.

https://api-core.legitimuz.com

Sandbox e produção usam o mesmo host. O que separa os dois é a chave.

Rotas

Rota	Para que serve	Permissão da chave
POST /public/verifications	Criar a verificação e obter a entrada da jornada	Criar link de verificação
GET /public/validations-persons	Listar a verificação mais recente de cada titular, com o resultado de cada etapa	Ver verificações
GET /public/validations-persons/{public_id}	Consultar uma verificação pelo public_id, com os mesmos campos da listagem	Ver verificações
GET /public/validations-persons/{public_id}/files	Baixar a selfie e o documento de uma verificação	Ver verificações e Ver mídia da verificação

As três rotas de leitura também exigem que o IP do seu servidor esteja liberado. Veja permissões de leitura.

Ciclo

1. O seu servidor cria a verificação

   POST /public/verifications com o header X-API-Key. Devolve o public_id e a entrada da jornada.

2. A pessoa percorre a jornada

   O widget abre com a credencial que veio na entrada e conversa com a Legitimuz sozinho.

3. O seu servidor recebe a decisão

   verification.decided chega assinado ao seu endpoint.

4. Se precisar, o seu servidor lê a verificação

   Consulte a verificação pelo public_id do webhook, liste as verificações ou baixe as imagens.

As rotas que o widget usa durante a jornada não são contrato público. Elas mudam junto com as telas. Chame só as quatro rotas desta página.

Autenticação

Header X-API-Key, com a chave da integração (lz_...). A chave não é aceita no corpo nem na query string. Detalhes em autenticação.

Convenções

• Datas em ISO 8601, em UTC.
• schema_version no topo do corpo de criação. Hoje, "1.0". As rotas de leitura não levam.
• Requisições usam schema fechado: campo ou parâmetro desconhecido é recusado.
• Respostas são aditivas: campo novo pode aparecer, e o seu cliente ignora o que não conhece.
• Toda resposta traz X-Request-Id. Registre-o: é o que localiza uma chamada no suporte.

Páginas

Status

Os cinco valores e o que cada um significa.

Erros e limites

O envelope, o catálogo e o comportamento diante de 429.