Emitir a credencial

Crie a verificação no seu backend e entregue ao cliente só o que ele pode ter.

A verificação nasce no seu servidor. É ali que a chave de API vive, e é de lá que sai a credencial de curta duração que o cliente usa.

Chamada

Node.js

const response = await fetch("https://api-core.legitimuz.com/public/verifications", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.LEGITIMUZ_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    schema_version: "1.0",
    ref_id: "pedido-4471",
    document: { type: "cpf", number: registration.cpf },
  }),
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(`Legitimuz responded ${response.status}: ${error.message}`);
}

const { verification, entry } = await response.json();

Referência completa

Todos os campos e os onze códigos de resposta.

O que devolver ao cliente

Só a entry. Nada mais.

Campo	Vai para o cliente
entry inteiro, como veio	sim
verification.expires_at	opcional, se a sua interface mostra um contador

Guarde o verification.public_id no seu banco, para ligar o webhook ao seu pedido. Não o repita numa segunda chave da resposta: ele é o mesmo valor que já vai dentro da entry.

A resposta da sua rota

// Guarde o vínculo antes de responder: sem ele, o webhook chega e você não sabe de quem é.
await db.registrations.linkVerification(registration.id, verification.public_id);

res.json({ entry });

Nunca devolva a chave de API, e nunca deixe o cliente escolher o CPF. O documento vem do seu cadastro; se ele vier do corpo da requisição, qualquer um cria verificação para qualquer pessoa na sua conta.

Retentativa

A criação é idempotente por ref_id. Repetir com o mesmo ref_id e o mesmo corpo devolve a verificação existente com 200, em vez de criar uma segunda.

Isso torna o retry seguro depois de um timeout de rede.

Repetir sem duplicar

async function createWithRetry(body: CreateVerification, attempt = 0): Promise<Response> {
  const response = await callLegitimuz(body);

  const isRetryable = response.status === 429 || response.status >= 500;
  if (!isRetryable || attempt >= 4) return response;

  const retryAfter = Number(response.headers.get("Retry-After"));
  const delay = Number.isFinite(retryAfter) ? retryAfter * 1000 : 2 ** attempt * 500;
  await new Promise((r) => setTimeout(r, delay + Math.random() * 250));

  return createWithRetry(body, attempt + 1);
}

Código	Repetir
429, 500, 503	sim, com backoff
400, 403, 404, 409, 415, 422	não, a mesma chamada falha de novo
401	não, até corrigir a chave

Erros da API

O envelope e o catálogo completo.

Onde guardar a chave

Ambiente	Onde
Desenvolvimento	.env fora do controle de versão
Produção	cofre de segredos do seu provedor
Em qualquer lugar	nunca no repositório, no bundle do front ou em log

Próximo passo

Abrir na web

O que fazer com a entry no browser.

Receber a decisão

O outro lado do ciclo.