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.

A chamada

Node.js

const resposta = await fetch("https://api.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: cadastro.cpf },
    integration_origin_public_id: process.env.LEGITIMUZ_ORIGIN_ID!,
  }),
});

if (!resposta.ok) {
  const erro = await resposta.json();
  throw new Error(`Legitimuz respondeu ${resposta.status}: ${erro.message}`);
}

const { verification, entry } = await resposta.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.url ou entry.access_credential	sim
verification.public_id	não é necessário, guarde no seu banco
verification.expires_at	opcional, se a sua interface mostra um contador

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.cadastros.vincularVerificacao(cadastro.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 criarComRetry(corpo: CriarVerificacao, tentativa = 0): Promise<Resposta> {
  const resposta = await chamarLegitimuz(corpo);

  const recuperavel = resposta.status === 429 || resposta.status >= 500;
  if (!recuperavel || tentativa >= 4) return resposta;

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

  return criarComRetry(corpo, tentativa + 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.