Esquemas e enumerações

Tipos TypeScript canônicos para cada esquema compartilhado da Certivant — status das requisições, tipos de documento, tipos de verificação, formato da pontuação de risco, campos do solicitante e da entidade KYB, envelope do webhook e paginação.

Esta página reúne as enumerações e as estruturas compartilhadas que aparecem em vários endpoints. Os esquemas completos de cada endpoint estão na referência interativa em /api/docs.

Prefixos de ID

Todos os identificadores da Certivant são strings com prefixo (no estilo ULID, após o prefixo). O prefixo faz parte do identificador — não o remova.

Prefixo	Recurso
`org_`	Organização
`req_`	Requisição de KYC / KYB
`doc_`	Documento
`app_`	Solicitante
`kyb_`	Registro de entidade KYB
`check_`	Verificação
`kyk_`	Chave de API
`whsec_`	Segredo de assinatura do webhook

Estes IDs são estáveis para sempre — nunca são reaproveitados e não mudam após a criação.

Tipos de requisição

type RequestType = "INDIVIDUAL" | "BUSINESS";

INDIVIDUAL — KYC. Verifica uma pessoa física.
BUSINESS — KYB. Verifica uma empresa, os seus diretores e os seus beneficiários finais.

Status das requisições

type RequestStatus =
  | "PENDING_UPLOAD"  // Awaiting documents
  | "PROCESSING"      // Submitted, automated checks running
  | "APPROVED"        // Cleared. Done.
  | "REJECTED"        // Failed. May be resubmitted.
  | "ESCALATED"       // Borderline. Awaiting human decision.
  | "CANCELLED";      // Withdrawn before completion.

O ciclo de vida segue estritamente em frente — quando uma requisição está APPROVED, REJECTED ou CANCELLED, ela não volta atrás. Uma requisição REJECTED pode ser redefinida para PENDING_UPLOAD por meio de /resubmit, o que abre um novo caminho pela mesma máquina de estados, no mesmo registro.

Tipos de documento

type DocumentType =
  | "GOVERNMENT_ID"
  | "PASSPORT"
  | "SELFIE"
  | "PROOF_OF_ADDRESS"
  | "CERTIFICATE_OF_INCORPORATION"
  | "COMPANY_OWNERSHIP_STRUCTURE"
  | "BANK_STATEMENT"
  | "OTHER";

GOVERNMENT_ID é o único tipo que exige o parâmetro side (front / back).

Status dos documentos

type DocumentStatus = "pending" | "verified" | "failed" | "corrupted";

pending — enviado, ainda não processado (aparece somente antes de a requisição principal ser submetida).
verified — aprovado nas verificações de autenticidade após a submissão.
failed — reprovado em pelo menos uma verificação. Os motivos aparecem nos registros de verificação vinculados.
corrupted — o arquivo não pôde ser decodificado. Envie-o novamente.

Tipos de verificação

type CheckType =
  | "document_authenticity"
  | "ocr"
  | "face_match"
  | "liveness"
  | "sanctions_screening"
  | "pep_screening"
  | "adverse_media"
  | "proof_of_address"
  | "phone_verification"
  | "email_verification"
  | "registry_lookup";

type CheckResult = "pass" | "fail" | "review";

Uma requisição normalmente tem de 4 a 8 verificações, dependendo do conjunto de documentos e das configurações de KYC da sua organização.

Decisões

O mecanismo de risco gera uma de três decisões, que correspondem aos status das requisições:

type RiskDecision = "approve" | "reject" | "escalate";

Decisão do mecanismo	Status resultante
`approve`	`APPROVED`
`reject`	`REJECTED`
`escalate`	`ESCALATED` (aguarda revisão humana)

Pontuação de risco

type RiskScore = {
  score: number;         // 0–100. Higher = lower risk
  decision: RiskDecision;
  factors: RiskFactor[];
  factorVerdicts?: { factor: string; verdict: "pass" | "fail" | "review" }[];
  disqualifiers?: string[];   // Hard blockers, e.g. "document_expired"
  reviewTriggers?: string[];  // Reasons for escalation
  reason?: string;       // Free-text summary for humans
};

type RiskFactor = {
  name: string;          // e.g. "face_match", "liveness"
  weight: number;        // 0–1, contribution to overall score
  score: number;         // 0–1, this factor's standalone score
};

A pontuação é apenas informativa. O campo decision é o que de fato dirige as transições de estado, e os limiares de pontuação para aprovar / encaminhar / rejeitar são configuráveis por organização no painel, em KYC → Configurações → Limiares.

Estrutura do solicitante

type Applicant = {
  externalRef?: string;
  fullName?: string;
  dateOfBirth?: string;     // ISO 8601 date (YYYY-MM-DD)
  nationality?: string;     // ISO 3166-1 alpha-2 (2 chars)
  email?: string;
  phone?: string;           // E.164 format with leading +
  emailVerified?: boolean;
  phoneVerified?: boolean;
  metadata?: Record<string, unknown>;
};

Todos os campos são opcionais na criação. Qualquer campo ausente pode ser preenchido pelo solicitante por meio de uma sessão hospedada, ou pode ficar em branco se as verificações subjacentes não precisarem dele (por exemplo, você pode executar uma triagem apenas de sanções somente com fullName e dateOfBirth).

Estrutura da entidade KYB

type KybEntity = {
  companyName: string;
  registrationNo?: string;
  countryOfIncorp?: string; // ISO 3166-1 alpha-2
  companyType?: string;     // "private_limited" | "llc" | "partnership" | "sole_trader" | …
  directors?: Director[];
  ubos?: Ubo[];
};

type Director = {
  fullName: string;
  dateOfBirth?: string;
  nationality?: string;
  appointedAt?: string;     // ISO 8601 date
};

type Ubo = {
  fullName: string;
  dateOfBirth?: string;
  nationality?: string;
  ownershipPercentage?: number;  // 0–100
};

Envelope do webhook

type WebhookPayload = {
  event: KycWebhookEventType;
  requestId: string;
  organizationId: string;
  externalRef?: string;
  subTenantName?: string;        // Partner mode: end-customer display name
  subTenantExternalId?: string;  // Partner mode: your end-customer id
  status: RequestStatus;
  timestamp: string;        // ISO 8601
  data?: Record<string, unknown>;  // Event-specific
};

type KycWebhookEventType =
  | "kyc.request.created"
  | "kyc.request.processing"
  | "kyc.request.approved"
  | "kyc.request.rejected"
  | "kyc.request.escalated"
  | "kyc.request.cancelled"
  | "kyc.document.uploaded"
  | "kyc.check.completed";

Veja Eventos de webhook para a estrutura de data de cada evento.

Paginação

type PaginatedResponse<T> = {
  data: T[];
  pagination: {
    total: number;   // Total matching rows across all pages
    page: number;    // Current page, 1-indexed
    limit: number;   // Page size
    pages: number;   // Total page count
  };
};

Use limit com até 100 para minimizar as idas e voltas. O padrão é 20 se você omitir o parâmetro.

Códigos de país e moeda

Países: ISO 3166-1 alpha-2 (US, GB, FR, JP). Letras minúsculas são aceitas, mas são normalizadas para maiúsculas nas respostas.
Números de telefone: E.164, com + no início (+14155551234).
Datas: ISO 8601 (YYYY-MM-DD). Carimbos de data e hora com fuso horário (2026-05-27T10:00:00.000Z).
Moedas: códigos de três letras da ISO 4217 (USD, EUR, GBP).

Onde encontrar mais

A referência interativa em /api/v1/docs (também incorporada na página Referência da API) mostra todos os endpoints com construtores de requisição ao vivo.
O JSON OpenAPI 3.1 bruto em /api/v1/openapi.json — importe-o no Postman, gere clientes ou use-o no seu gerador de código favorito.

Ambos são públicos: não é preciso login nem chave de API, e descrevem apenas os endpoints /api/v1/kyc/** com os quais você constrói a integração. Os esquemas, escopos e respostas de erro de cada endpoint no documento OpenAPI são a fonte autoritativa; esta página apenas reúne as estruturas que se repetem entre os endpoints.

Esquemas e enumerações

On this page