👤 Perfil e Verificação de Identidade (KYC)

Esta página orienta sobre como cadastrar o perfil do usuário e enviar a documentação para a validação de identidade (KYC - Know Your Customer). Sem a aprovação do KYC (nível de conta FULL ), o usuário não poderá realizar transações financeiras.

Ordem das Ações (Importante!)

Para evitar erros e dados bloqueados, siga rigorosamente esta sequência no seu código ou fluxo de telas:

┌────────────────────────┐
│  1. Definir Perfil     │  Definir CPF/CNPJ via PATCH /profile
└──────────┬─────────────┘
           │
           ▼
┌────────────────────────┐
│  2. Definir Endereço   │  Cadastrar endereço via PUT /profile/address
└──────────┬─────────────┘
           │
           ▼
┌────────────────────────┐
│  3. Upload de Arquivos │  Pegar URLs de upload e subir documentos
└──────────┬─────────────┘
           │
           ▼
┌────────────────────────┐
│  4. Submeter KYC       │  Enviar submissão final via POST /kyc
└────────────────────────┘

⚠️ Atenção: O CPF/CNPJ e dados cadastrais básicos ficam totalmente imutáveis após a primeira submissão de documentos. Certifique-se de salvá-los corretamente.

Passo 1 — CPF/CNPJ e Dados Pessoais

Antes de iniciar o envio de documentos, atualize os dados básicos do perfil do usuário:

Endpoint

curl -X PATCH https://api.dexkey.finance/v1/profile \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "identityDocument": "12345678900",
    "birthDate": "1990-01-01",
    "nationality": "BR"
  }'

• identityDocument: CPF ou CNPJ, apenas números

Passo 2 — Endereço do Usuário

O endereço é obrigatório caso o perfil do usuário exija um Comprovante de Residência (PROOF_OF_ADDRESS).

Endpoint

curl -X PUT https://api.dexkey.finance/v1/profile/address \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "zipCode": "01310100",
    "street": "Avenida Paulista",
    "number": "1000",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP"
  }'

Passo 3 — Upload de Documentos

O envio de cada arquivo é feito em uma única chamada: você envia o arquivo diretamente para a DEX API (não existe um passo separado de "pegar uma URL e depois fazer upload para ela").

3.1 — Consultar os Tipos de Documento Exigidos

Consulte quais arquivos o usuário precisa enviar (varia de acordo com nacionalidade e se é Pessoa Física ou Jurídica):

GET /v1/kyc/document-types

Resposta de Exemplo:

[
  { "code": "RG_FRONT", "name": "RG - Frente", "isRequired": true, "acceptedFormats": ["jpg", "jpeg", "png", "pdf"] },
  { "code": "RG_BACK", "name": "RG - Verso", "isRequired": true, "acceptedFormats": ["jpg", "jpeg", "png", "pdf"] },
  { "code": "SELFIE", "name": "Selfie com Documento", "isRequired": true, "acceptedFormats": ["jpg", "jpeg", "png"] },
  { "code": "PROOF_OF_ADDRESS", "name": "Comprovante de Residência", "isRequired": true, "acceptedFormats": ["jpg", "jpeg", "png", "pdf"] }
]

Use o campo code (não id , que é um UUID interno) como documentTypeCode no envio do arquivo.

3.2 — Enviar o Arquivo

Envie o arquivo físico e o documentTypeCode juntos, em uma chamada multipart/form-data:

curl -X POST https://api.dexkey.finance/v1/kyc/upload-url \
  -H "Authorization: Bearer $JWT" \
  -F "file=@rg-frente.jpg" \
  -F "documentTypeCode=RG_FRONT"

Do front-end (browser/mobile), o equivalente é:

const formData = new FormData();
formData.append('file', arquivoDoUsuario); // Objeto File ou Blob do front-end
formData.append('documentTypeCode', 'RG_FRONT');

await fetch('https://api.dexkey.finance/v1/kyc/upload-url', {
  method: 'POST',
  headers: { Authorization: `Bearer ${jwt}` },
  body: formData, // não defina Content-Type manualmente — o browser define o boundary do multipart
});

Resposta:

{
  "key": "kyc/user-id/RG_FRONT/uuid.jpg",
  "url": "https://.../uuid.jpg?..."
}

Repita esse passo para cada documento obrigatório retornado no Passo 3.1.

Boas Práticas para Upload de Documentos (Evite Rejeições)

Para garantir que a análise de compliance aprove o cadastro de primeira e evitar demoras na validação, seu front-end deve orientar os usuários finais seguindo as regras abaixo:

Dicas para Captura de Fotos:

• RG e CNH:

  • Remova o documento do plástico protetor antes de fotografar.

  • Certifique-se de que todos os quatro cantos e bordas do documento estão visíveis na foto.

  • Evite luzes direcionadas diretas para não gerar reflexos do flash sobre os dados textuais ou a foto.

• Selfie:

  • Enquadre o rosto inteiro, mantendo os olhos visíveis e sem adereços como óculos de sol ou bonés.

  • Garanta um ambiente bem iluminado. Fotos granuladas ou no escuro serão automaticamente recusadas.

• Comprovante de Residência:

  • Deve ter sido emitido nos últimos 90 dias.

  • Deve conter o nome completo do usuário final de forma legível.

Passo 4 — Submeter o KYC

Após fazer o upload de todos os documentos obrigatórios, faça a submissão final:

Endpoint

curl -X POST https://api.dexkey.finance/v1/kyc \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      { "documentTypeCode": "RG_FRONT", "fileUrl": "kyc/user-id/RG_FRONT/uuid.jpg" },
      { "documentTypeCode": "RG_BACK", "fileUrl": "kyc/user-id/RG_BACK/uuid2.jpg" },
      { "documentTypeCode": "SELFIE", "fileUrl": "kyc/user-id/SELFIE/uuid3.jpg" },
      { "documentTypeCode": "PROOF_OF_ADDRESS", "fileUrl": "kyc/user-id/PROOF_OF_ADDR/uuid4.jpg" }
    ]
  }'

Passo 5 — Acompanhar o Status

Para saber o resultado da análise, faça a consulta:

GET /v1/kyc/status

Resposta:

{
  "status": "AWAITING_REVIEW" // "AWAITING_REVIEW" (em análise), "APPROVED" (aprovado) ou "REJECTED" (rejeitado)
}

Consultar Status da Conta (BASIC/FULL)

Endpoint mais leve para saber rapidamente se a conta pode fazer Pix/Cripto (FULL) ou ainda está limitada (BASIC), sem precisar buscar o perfil completo:

curl https://api.dexkey.finance/v1/profile/status \
  -H "Authorization: Bearer $JWT"

{
  "accountStatus": "BASIC",
  "canUpgrade": true,
  "kycStatus": null,
  "kycSubmittedAt": null
}

• accountStatus: BASIC (recém-cadastrado, sem KYC) ou FULL (KYC aprovado, libera Pix/Swap/Cripto).

• canUpgrade: true quando a conta está em BASIC e pode iniciar o KYC.

• kycStatus / kycSubmittedAt: reservados para uso futuro — hoje sempre retornam null, independente do KYC real do usuário. Para o status de KYC de verdade, use GET /kyc/status (Passo 5 acima).