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
const kyc = await enginex.kyc.getStatus()
// {
// level: 'basic',
// status: 'not_started',
// cpfVerified: true,
// documentVerified: false,
// selfieVerified: false,
// addressVerified: false,
// rejectionReason: null,
// updatedAt: null,
// }status | O que significa | O que mostrar |
|---|---|---|
not_started | nada enviado ainda | o pedido de documentos |
pending | documento recebido, aguardando a análise | "Recebemos seus documentos" |
in_review | em análise pela equipe do operador | "Estamos analisando seus documentos" |
approved | verificação aprovada | a confirmação (e libere o que dependia do KYC) |
rejected | recusada; o motivo vem em rejectionReason | o 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.
level | O que já foi verificado | Documentos (documentType) |
|---|---|---|
none | nada | — |
basic | CPF e e-mail (no cadastro) | — (cpfVerified) |
intermediate | + documento de identidade | rg_front + rg_back, ou cnh_front + cnh_back, ou passport (documentVerified) |
full | + selfie e comprovante de endereço | selfie (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
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" />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:
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):
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.
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ódigo | Quando |
|---|---|
CONFIGURATION_ERROR | documentType 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_ERROR | em '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.
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.