Esta versão (v0.7) ainda não foi publicada no npm.
Pular para o conteúdo

Verificação de identidade (KYC) ​

A demo do cenário KYC (consultar a situação e enviar um documento, sem expor o arquivo no painel) está em Jogo responsável.

O namespace kyc consulta a situação da verificação de identidade do jogador e envia documentos para análise. A análise é manual, feita pela equipe do operador no painel administrativo: não há provedor externo nem redirecionamento. Todos os métodos exigem login.

Consultar a situação ​

ts
const kyc = await enginex.kyc.getStatus()
// {
//   level: 'basic',
//   status: 'not_started',
//   cpfVerified: true,
//   documentVerified: false,
//   selfieVerified: false,
//   addressVerified: false,
//   rejectionReason: null,
//   updatedAt: null,
// }
statusO que significaO que mostrar
not_startednada enviado aindao pedido de documentos
pendingdocumento recebido, aguardando a análise"Recebemos seus documentos"
in_reviewem análise pela equipe do operador"Estamos analisando seus documentos"
approvedverificação aprovadaa confirmação (e libere o que dependia do KYC)
rejectedrecusada; o motivo vem em rejectionReasono motivo e o pedido de reenvio

level e status chegam sem o prefixo do gateway (KYC_LEVEL_FULL → 'full', KYC_VERIFICATION_STATUS_IN_REVIEW → 'in_review'). Os dois tipos são uniões abertas: pode chegar 'unspecified' (o serviço não preencheu) ou um valor novo, então trate o caso padrão. Com validation: 'warn', um valor que o SDK não conhece chega como veio do gateway e é reportado em onValidationIssue; com 'strict', a chamada rejeita com VALIDATION_ERROR (veja Validação de respostas). rejectionReason e updatedAt vêm null quando o gateway não informa (texto vazio e data 1970-01-01T00:00:00Z no fio).

Documentos por nível ​

Os níveis são cumulativos. Qual nível o operador exige (e para quê) é regra do operador: o gateway não a expõe, então a tela decide a partir dos campos *Verified.

levelO que já foi verificadoDocumentos (documentType)
nonenada—
basicCPF e e-mail (no cadastro)— (cpfVerified)
intermediate+ documento de identidaderg_front + rg_back, ou cnh_front + cnh_back, ou passport (documentVerified)
full+ selfie e comprovante de endereçoselfie (selfieVerified) e proof_address (addressVerified)

A correspondência entre documentos e níveis vem da descrição dos níveis no protobuf do serviço de compliance; o serviço em si não está disponível para conferência, então trate-a como orientação.

Enviar um documento ​

uploadDocument recebe o tipo do documento e o arquivo (Blob ou File) e envia como multipart (document_type + file). Devolve o id do documento recebido; a situação passa para pending (documento recebido, aguardando a análise) e muda de novo quando a equipe do operador analisar. Se o gateway responder sem confirmar o recebimento (success: false ou sem id), a chamada rejeita com UNKNOWN (status 201), com a mensagem do gateway quando ela vem (senão a do SDK): consulte getStatus e só envie de novo se o documento não aparece (veja operação não confirmada).

No browser ​

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

O File do <input> vai ao gateway com o nome original. Os hooks do cliente recebem só o nome do campo (file), o tipo e o tamanho do arquivo — nunca o nome original (que pode identificar o jogador) nem o conteúdo.

No Node ​

No Node 20+ (Blob e FormData são globais), passe um Blob com o tipo certo:

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' }),
})

Tamanho e formato ​

O SDK não limita tamanho nem formato, e o gateway também não. Recomendamos até 4 MB, em JPEG, PNG ou PDF: acima disso, o serviço de compliance provavelmente recusa o arquivo (limite padrão de mensagens do gRPC, não verificado) com RESOURCE_EXHAUSTED (429). Valide antes de enviar e reduza a imagem no próprio app (ex.: redimensionar a foto para ~2000 px no lado maior):

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
}

documentType fora da lista ou file que não é Blob/File rejeitam com CONFIGURATION_ERRORantes de qualquer request (é erro de uso do app). O envio não é idempotente: depois de uma falha de rede (NETWORK_ERROR, TIMEOUT), consulte getStatus antes de reenviar e trave o botão enquanto o envio está em andamento.

Acompanhar a análise ​

Não há aviso em tempo real de mudança na verificação: consulte getStatus de novo ao abrir a tela e, enquanto estiver em pending ou in_review, com um 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()
    }
  })
}

Com TanStack Query, o mesmo fica em refetchInterval: (q) => (waiting.has(q.state.data?.status ?? '') ? 60_000 : false).

Erros ​

CódigoQuando
CONFIGURATION_ERRORdocumentType fora da lista ou file que não é Blob/File (sem request)
INVALID_ARGUMENT (400)o gateway não conseguiu ler o multipart ou o arquivo, ou recusou o tipo (mensagem do gateway)
RESOURCE_EXHAUSTED (429)arquivo grande demais para o serviço de compliance, ou limite de requisições (e.retryAfter)
UNKNOWN (201)o gateway respondeu sem confirmar o recebimento (success: false ou sem id)
UNAUTHENTICATED (401)sem sessão
VALIDATION_ERRORem 'strict', nível ou situação que o SDK não conhece, ou updatedAt que não é data

Outros erros do serviço de compliance chegam com o code preservado, alguns como HTTP 500: decida sempre por isEnginexError(error, code), nunca pelo status. Os códigos que outras operações devolvem por causa do KYC (KYC_REQUIRED, KYC_PENDING, KYC_REJECTED, por exemplo no depósito e no saque) estão em Códigos de erro.

Testes ​

createMockFetch() já responde GET /kyc/status (nível basic, not_started) e aceita o upload multipart como o gateway (201, ou 400 INVALID_ARGUMENT sem arquivo ou com tipo inválido); depois de um envio, a situação passa para 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', ... }

O que o gateway ainda não oferece ​

  • Limite de tamanho. O gateway não limita o arquivo nem devolve um erro próprio para "grande demais"; o teto real é o do serviço de compliance (provavelmente ~4 MB do gRPC, não verificado). Por isso a recomendação de até 4 MB e a validação no app.
  • Leitura completa garantida. O gateway lê o arquivo com uma única leitura: há risco de o documento ser gravado truncado sem erro. Se a análise recusar um arquivo íntegro como ilegível, reenvie.
  • Lista de documentos enviados. Não há rota para listar os documentos já enviados nem a situação de cada um: só a situação geral (getStatus) e os campos *Verified.
  • Início de verificação externa. StartKYC (verificação por provedor externo com redirecionamento) não tem rota no gateway; o fluxo é só envio de documentos e análise manual.
  • Tempo real. Nenhum evento de realtime avisa a aprovação ou a recusa: acompanhe com getStatus.
  • Idempotência. O upload não tem Idempotency-Key: um reenvio cria outro documento.