Esquemas y enumeraciones

Tipos TypeScript canónicos de cada esquema compartido de Certivant: estados de solicitud, tipos de documento, tipos de comprobación, forma de la puntuación de riesgo, campos de solicitante y de entidad KYB, sobre del webhook y paginación.

Esta página reúne las enumeraciones y las formas compartidas que aparecen en varios endpoints. Los esquemas completos de cada endpoint están en la referencia interactiva, en /api/docs.

Prefijos de ID

Todos los identificadores de Certivant son cadenas con prefijo (de estilo ULID después del prefijo). El prefijo forma parte del identificador: no lo elimine.

Prefijo	Recurso
`org_`	Organización
`req_`	Solicitud KYC / KYB
`doc_`	Documento
`app_`	Solicitante
`kyb_`	Registro de entidad KYB
`check_`	Comprobación de verificación
`kyk_`	Clave de API
`whsec_`	Secreto de firma de webhook

Estos ID son estables para siempre: nunca se reciclan ni cambian después de crearse.

Tipos de solicitud

type RequestType = "INDIVIDUAL" | "BUSINESS";

INDIVIDUAL: KYC. Verifica a una persona física.
BUSINESS: KYB. Verifica una empresa, sus directores y sus beneficiarios finales.

Estados de la solicitud

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.

El ciclo de vida es estrictamente hacia adelante: una vez que una solicitud está APPROVED, REJECTED o CANCELLED, no vuelve atrás. REJECTED puede restablecerse a PENDING_UPLOAD mediante /resubmit, lo que crea un nuevo recorrido por la misma máquina de estados en el mismo registro.

Tipos de documento

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

GOVERNMENT_ID es el único tipo que requiere el parámetro side (front / back).

Estados del documento

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

pending: subido, pero aún no procesado (solo se ve antes de enviar la solicitud principal).
verified: superó las comprobaciones de autenticidad tras el envío.
failed: no superó al menos una comprobación. Los motivos aparecen en los registros de comprobación vinculados.
corrupted: el archivo no pudo decodificarse. Vuelva a subirlo.

Tipos de comprobación

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";

Una solicitud suele tener entre 4 y 8 comprobaciones, según el conjunto de documentos y la configuración KYC de su organización.

Decisiones

El motor de riesgo genera una de tres decisiones, que se corresponden con los estados de la solicitud:

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

Decisión del motor	Estado resultante
`approve`	`APPROVED`
`reject`	`REJECTED`
`escalate`	`ESCALATED` (espera revisión humana)

Puntuación de riesgo

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
};

La puntuación es informativa. El campo decision es lo que realmente impulsa los cambios de estado, y los umbrales de puntuación para aprobar, escalar y rechazar se configuran por organización en el panel, en KYC → Configuración → Umbrales.

Forma del 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 los campos son opcionales al crear. Lo que falte puede completarlo el solicitante mediante una sesión alojada, o dejarse en blanco si las comprobaciones subyacentes no lo necesitan (por ejemplo, puede ejecutar un cribado solo de sanciones con fullName y dateOfBirth).

Forma de la entidad 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
};

Sobre del 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";

Consulte Eventos de webhook para la forma de data de cada evento.

Paginación

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 hasta 100 para minimizar los viajes de ida y vuelta. El valor por defecto es 20 si lo omite.

Códigos de país y de moneda

Países: ISO 3166-1 alpha-2 (US, GB, FR, JP). Se acepta minúscula, pero en las respuestas se normaliza a mayúscula.
Números de teléfono: E.164 con + inicial (+14155551234).
Fechas: ISO 8601 (YYYY-MM-DD). Marcas de tiempo con zona horaria (2026-05-27T10:00:00.000Z).
Monedas: códigos ISO 4217 de tres letras (USD, EUR, GBP).

Dónde encontrar más

La referencia interactiva en /api/v1/docs (también incrustada en la página de Referencia de la API) muestra cada endpoint con constructores de solicitudes en vivo.
El JSON OpenAPI 3.1 sin procesar en /api/v1/openapi.json: impórtelo en Postman, genere clientes o úselo con su herramienta de generación de código preferida.

Ambos son públicos: no se necesita inicio de sesión ni clave de API, y describen solo los endpoints /api/v1/kyc/** contra los que construye. Los esquemas, ámbitos y respuestas de error de cada endpoint en el documento OpenAPI son la fuente autorizada; esta página solo reúne las formas que se repiten entre endpoints.

Esquemas y enumeraciones

On this page