Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

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 ​

ts
const kyc = await enginex.kyc.getStatus()
// {
//   level: 'basic',
//   status: 'not_started',
//   cpfVerified: true,
//   documentVerified: false,
//   selfieVerified: false,
//   addressVerified: false,
//   rejectionReason: null,
//   updatedAt: null,
// }
statusQué significaQué mostrar
not_startedaún no se ha enviado nadala solicitud de documentos
pendingdocumento recibido, a la espera de revisión"Recibimos tus documentos"
in_reviewen revisión por el equipo del operador"Estamos revisando tus documentos"
approvedverificación aprobadala confirmación (y habilita lo que dependía del KYC)
rejectedrechazada; el motivo viene en rejectionReasonel 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.

levelQué ya se verificóDocumentos (documentType)
nonenada—
basicCPF y correo (en el registro)— (cpfVerified)
intermediate+ documento de identidadrg_front + rg_back, o cnh_front + cnh_back, o passport (documentVerified)
full+ selfie y comprobante de domicilioselfie (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 ​

ts
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)
})
html
<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:

ts
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):

ts
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.

ts
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ódigoCuándo
CONFIGURATION_ERRORdocumentType 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_ERRORen '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.

ts
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.