Verificación de identidad (KYC)
La demo del escenario KYC (consultar el estado y enviar un documento, sin exponer el archivo en el panel) está en Juego responsable.
El namespace kyc consulta el estado de la verificación de identidad del jugador y envía documentos para su revisión. La revisión es manual, a cargo del equipo del operador en el panel administrativo: no hay proveedor externo ni redirección. Todos los métodos requieren inicio de sesión.
Consultar el estado
const kyc = await enginex.kyc.getStatus()
// {
// level: 'basic',
// status: 'not_started',
// cpfVerified: true,
// documentVerified: false,
// selfieVerified: false,
// addressVerified: false,
// rejectionReason: null,
// updatedAt: null,
// }status | Qué significa | Qué mostrar |
|---|---|---|
not_started | aún no se ha enviado nada | la solicitud de documentos |
pending | documento recibido, a la espera de revisión | "Recibimos tus documentos" |
in_review | en revisión por el equipo del operador | "Estamos revisando tus documentos" |
approved | verificación aprobada | la confirmación (y habilita lo que dependía del KYC) |
rejected | rechazada; el motivo viene en rejectionReason | el motivo y la solicitud de reenvío |
level y status llegan sin el prefijo del gateway (KYC_LEVEL_FULL → 'full', KYC_VERIFICATION_STATUS_IN_REVIEW → 'in_review'). Ambos tipos son uniones abiertas: puede llegar 'unspecified' (el servicio no lo completó) o un valor nuevo, así que maneja el caso por defecto. Con validation: 'warn', un valor que el SDK no conoce llega tal como vino del gateway y se reporta en onValidationIssue; con 'strict', la llamada se rechaza con VALIDATION_ERROR (consulta Validación de respuestas). rejectionReason y updatedAt llegan null cuando el gateway no los informa (texto vacío y fecha 1970-01-01T00:00:00Z en la red).
Documentos por nivel
Los niveles son acumulativos. Qué nivel exige el operador (y para qué) es una regla del operador: el gateway no la expone, así que la pantalla decide a partir de los campos *Verified.
level | Qué ya se verificó | Documentos (documentType) |
|---|---|---|
none | nada | — |
basic | CPF y correo (en el registro) | — (cpfVerified) |
intermediate | + documento de identidad | rg_front + rg_back, o cnh_front + cnh_back, o passport (documentVerified) |
full | + selfie y comprobante de domicilio | selfie (selfieVerified) y proof_address (addressVerified) |
La correspondencia entre documentos y niveles proviene de la descripción de los niveles en el protobuf del servicio de compliance; el servicio en sí no está disponible para verificarlo, así que tómala como orientación.
Enviar un documento
uploadDocument recibe el tipo del documento y el archivo (Blob o File) y lo envía como multipart (document_type + file). Devuelve el id del documento recibido; el estado pasa a pending (documento recibido, a la espera de revisión) y vuelve a cambiar cuando el equipo del operador lo revise. Si el gateway responde sin confirmar la recepción (success: false o sin id), la llamada se rechaza con UNKNOWN (status 201), con el mensaje del gateway cuando lo trae (si no, el del SDK): consulta getStatus y solo vuelve a enviar si el documento no aparece (consulta operación no confirmada).
En el navegador
const input = document.querySelector<HTMLInputElement>('#rg-frente')!
input.addEventListener('change', async () => {
const file = input.files?.[0]
if (!file) return
const { documentId } = await enginex.kyc.uploadDocument({ documentType: 'rg_front', file })
showSent(documentId)
})<input id="rg-frente" type="file" accept="image/jpeg,image/png,application/pdf" />El File del <input> llega al gateway con su nombre original. Los hooks del cliente reciben solo el nombre del campo (file), el tipo y el tamaño del archivo, nunca el nombre original (que puede identificar al jugador) ni el contenido.
En Node
En Node 20+ (Blob y FormData son globales), pasa un Blob con el tipo correcto:
import { readFile } from 'node:fs/promises'
const bytes = await readFile('./comprovante.pdf')
await enginex.kyc.uploadDocument({
documentType: 'proof_address',
file: new Blob([bytes], { type: 'application/pdf' }),
})Tamaño y formato
El SDK no limita el tamaño ni el formato, y el gateway tampoco. Recomendamos hasta 4 MB, en JPEG, PNG o PDF: por encima de eso, el servicio de compliance probablemente rechaza el archivo (límite predeterminado de mensajes de gRPC, no verificado) con RESOURCE_EXHAUSTED (429). Valida antes de enviar y reduce la imagen en la propia app (p. ej., redimensiona la foto a ~2000 px en el lado mayor):
const MAX_BYTES = 4 * 1024 * 1024
const ACCEPTED = ['image/jpeg', 'image/png', 'application/pdf']
if (file.size > MAX_BYTES || !ACCEPTED.includes(file.type)) {
showError('Upload a JPEG, PNG or PDF up to 4 MB')
return
}Un documentType fuera de la lista, o un file que no es Blob/File, se rechaza con CONFIGURATION_ERRORantes de cualquier request (es un error de uso de la app). El envío no es idempotente: tras un fallo de red (NETWORK_ERROR, TIMEOUT), consulta getStatus antes de reenviar y bloquea el botón mientras el envío está en curso.
Seguir la revisión
No hay aviso en tiempo real de cambios en la verificación: consulta getStatus de nuevo al abrir la pantalla y, mientras esté en pending o in_review, con un intervalo generoso.
import type { KycStatus } from '@getenginex/sdk'
const waiting = new Set(['pending', 'in_review'])
async function watchKyc(onChange: (status: KycStatus) => void, signal: AbortSignal) {
while (!signal.aborted) {
const kyc = await enginex.kyc.getStatus(undefined, { signal })
onChange(kyc)
if (!waiting.has(kyc.status)) return kyc // approved, rejected, not_started...
await sleep(60_000, signal) // review is manual: minutes or hours
}
}
// Cancelable wait: `abort` ends the wait right away (without holding the screen for up to a minute).
function sleep(ms: number, signal: AbortSignal) {
return new Promise<void>((resolve) => {
const timer = setTimeout(done, ms)
signal.addEventListener('abort', done, { once: true })
function done() {
clearTimeout(timer)
signal.removeEventListener('abort', done)
resolve()
}
})
}Con TanStack Query, lo mismo queda como refetchInterval: (q) => (waiting.has(q.state.data?.status ?? '') ? 60_000 : false).
Errores
| Código | Cuándo |
|---|---|
CONFIGURATION_ERROR | documentType fuera de la lista o file que no es Blob/File (sin request) |
INVALID_ARGUMENT (400) | el gateway no pudo leer el multipart o el archivo, o rechazó el tipo (mensaje del gateway) |
RESOURCE_EXHAUSTED (429) | archivo demasiado grande para el servicio de compliance, o límite de solicitudes (e.retryAfter) |
UNKNOWN (201) | el gateway respondió sin confirmar la recepción (success: false o sin id) |
UNAUTHENTICATED (401) | sin sesión |
VALIDATION_ERROR | en 'strict', nivel o estado que el SDK no conoce, o updatedAt que no es una fecha |
Otros errores del servicio de compliance llegan con el code preservado, algunos como HTTP 500: decide siempre con isEnginexError(error, code), nunca por el status. Los códigos que otras operaciones devuelven a causa del KYC (KYC_REQUIRED, KYC_PENDING, KYC_REJECTED, por ejemplo en el depósito y en el retiro) están en Códigos de error.
Pruebas
createMockFetch() ya responde GET /kyc/status (nivel basic, not_started) y acepta el envío multipart como el gateway (201, o 400 INVALID_ARGUMENT sin archivo o con tipo inválido); después de un envío, el estado pasa a pending.
import { createEnginexClient } from '@getenginex/sdk'
import { createMockFetch } from '@getenginex/sdk/testing'
const enginex = createEnginexClient({
baseUrl: 'https://gateway.test', // in Node: absolute baseUrl + tenantHost (optional in the browser)
tenantHost: 'casino.test',
fetch: createMockFetch(),
})
await enginex.auth.login({ email: 'ana@exemplo.com', password: 'Senha@123' })
await enginex.kyc.uploadDocument({ documentType: 'selfie', file: new Blob(['x'], { type: 'image/jpeg' }) })
await enginex.kyc.getStatus() // { status: 'pending', ... }Lo que el gateway aún no ofrece
- Límite de tamaño. El gateway no limita el archivo ni devuelve un error propio de "demasiado grande"; el techo real es el del servicio de compliance (probablemente ~4 MB de gRPC, no verificado). Por eso la recomendación de hasta 4 MB y la validación en la app.
- Lectura completa garantizada. El gateway lee el archivo con una sola lectura: existe el riesgo de que el documento se guarde truncado sin error. Si la revisión rechaza un archivo íntegro por ilegible, vuelve a enviarlo.
- Lista de documentos enviados. No hay ruta para listar los documentos ya enviados ni el estado de cada uno: solo el estado general (
getStatus) y los campos*Verified. - Inicio de verificación externa.
StartKYC(verificación por proveedor externo con redirección) no tiene ruta en el gateway; el flujo es solo envío de documentos y revisión manual. - Tiempo real. Ningún evento de realtime avisa de la aprobación o el rechazo: haz el seguimiento con
getStatus. - Idempotencia. El envío no tiene
Idempotency-Key: un reenvío crea otro documento.