SDK de KYC hospedado

Os dados de identidade são coletados na página hospedada da Noviuz: seu servidor cria a sessão, o navegador abre o fluxo com o sessionId e, após a conclusão, seu servidor consulta o resultado oficial. O site parceiro recebe notificações do fluxo, mas não deve coletar nem registrar dados de identidade.

PacotesCopy Anchor Link

As versões listadas estão publicadas no npm. Instale cada pacote somente no ambiente em que será usado:

# No serviço que cria sessões e guarda a credencial
npm install @noviuz/kyc-server

# No app frontend que abre a experiência hospedada
npm install @noviuz/kyc-js

Origens e rotasCopy Anchor Link

Use apenas a origem em createSessionClient({ baseUrl }), sem caminho, credenciais, query ou fragmento. O SDK @noviuz/kyc-js usa a origem hospedada para abrir a experiência; essa configuração é diferente da origem da API usada pelo servidor.

1. Crie a sessão no servidorCopy Anchor Link

Instale @noviuz/kyc-server no backend ou função edge. A Noviuz provisiona uma credencial Bearer para armazenar, por exemplo, em NOVIUZ_KYC_SECRET_KEY; proteja também a rota do seu próprio serviço com a autenticação do usuário parceiro antes de emitir uma sessão.

import { createSessionClient } from '@noviuz/kyc-server/bearer';

const kyc = createSessionClient({
  baseUrl: process.env.NOVIUZ_KYC_API_BASE ?? 'https://api.noviuz.com',
  secretKey: process.env.NOVIUZ_KYC_SECRET_KEY!,
});

export async function createKycSession(attemptId: string) {
  const session = await kyc.mintSession(
    { customerType: 'individual' },
    { idempotencyKey: `kyc:${attemptId}` },
  );

  // Responda ao frontend apenas com o necessário para abrir o fluxo.
  return { sessionId: session.sessionId };
}

Use um attemptId opaco e persistente para repetir a mesma tentativa com a mesma chave de idempotência. A chave deve ter 16–255 caracteres ASCII imprimíveis; reutilize-a com o mesmo corpo para obter a mesma sessão e gere outra para uma nova tentativa. Nunca envie NOVIUZ_KYC_SECRET_KEY ao navegador nem registre a credencial ou o sessionId em logs.

customerType aceita individual (PF) ou business (PJ). Use o valor correspondente ao usuário que iniciará a verificação.

2. Abra a experiência no navegadorCopy Anchor Link

Instale @noviuz/kyc-js no frontend. Chame NoviuzKyc.open em uma ação do usuário ou no lado cliente, nunca durante renderização no servidor (SSR).

import { NoviuzKyc } from '@noviuz/kyc-js';

NoviuzKyc.open({
  sessionId, // recebido da rota autenticada do seu servidor
  onSuccess: ({ sessionId }) => notifyYourServer(sessionId),
  onReview: ({ sessionId }) => notifyYourServer(sessionId),
  onError: (error) => reportKycError(error.code),
});

onSuccess e onReview são notificações para a interface, não decisões autoritativas. O SDK transmite o sessionId à rota hospedada para abrir a sessão; trate-o como uma credencial limitada a esse fluxo. Não o propague para rotas do parceiro, analytics ou logs. Ao receber uma notificação, confira no servidor que a sessão pertence à tentativa autenticada antes de chamar getResult. Consulte o guia de integração do SDK para callbacks, eventos, CSP, opções visuais e modos de abertura.

3. Consulte o resultado no servidorCopy Anchor Link

Após a notificação, seu backend chama getResult. Só tome decisões de produto com base nessa resposta validada pelo servidor:

const result = await kyc.getResult(sessionId);

switch (result.status) {
  case 'approved':
    // Continue após aplicar também as regras do seu produto.
    break;
  case 'rejected':
  case 'expired':
  case 'cancelled':
    // Trate conforme o fluxo do seu produto.
    break;
  case 'under_review':
    // Encaminhe para análise; este estado não significa aprovação.
    break;
}

409 NOT_TERMINAL significa que ainda não há decisão final: consulte novamente a mesma sessão com atraso progressivo e limite. 401 indica credencial inválida, 404 sessão não encontrada ou pertencente a outra organização, 410 sessão expirada e 429 limite de chamadas excedido. Os erros são tipados pelo SDK; veja o README de @noviuz/kyc-server para detalhes.

4. O papel do EUID (Entity Unique Identifier)Copy Anchor Link

Ao atingir o estado approved, a resposta do servidor entrega o result.euid:

{
  "status": "approved",
  "sessionId": "ses_0192a8b3-...",
  "euid": "euid_0192a8b4-8f12-7000-a1b2-c3d4e5f6a7b8"
}

O que o EUID representa?Copy Anchor Link

O EUID é o identificador patrimonial único e soberano gerado pela plataforma Noviuz após corroborar documentos oficiais, regularidade perante a Receita Federal, vivacidade e biometria facial fail-closed.

• Imutável e Canônico: Diferente de e-mail, telefone ou documento que podem sofrer alterações ou homônimos, o EUID representa a Entidade perante o sistema operacional patrimonial.
• Indexação Recomendada: Armazene o euid na tabela de usuários do seu sistema (ALTER TABLE users ADD COLUMN noviuz_euid VARCHAR(64) UNIQUE;). Esse identificador é a chave para vincular contas correntes, concessões e custódias na Conta Nexiuz. Para entender mais sobre a governança de Entidades e mandatos, consulte o guia de Governança e autorização patrimonial.

Disponibilidade e alternativasCopy Anchor Link

A esteira de verificação de identidade requer ativação do serviço na sua conta de parceiro junto à Noviuz. Caso o serviço não esteja ativado para seu ambiente ou as credenciais não estejam provisionadas, as chamadas respondem 503 SERVICE_UNAVAILABLE. Confirme a habilitação, credenciais e origem autorizada com a equipe de integração da Noviuz.

Para páginas estáticas ou SPAs que não mantêm backend confidencial, existe também o endpoint público integrado ao modo de chave publicável do SDK de navegador. A origem (domínio) de quem incorpora a página deve estar previamente cadastrada no Portal. Esse modo não substitui a consulta autenticada do resultado pelo servidor; use o fluxo Bearer padrão sempre que seu sistema precisar agir com base no resultado da verificação. O SDK cuida do bootstrap e das chamadas de trilho da página hospedada; não chame esses endpoints internos diretamente.

Consulte a referência da API do SDK e os guias de integração do parceiro no repositório oficial do SDK. Rotas e trilhas disponíveis podem variar conforme a configuração e os pacotes contratados para o seu ambiente.