KYC

Todos os endpoints exigem Authorization: Bearer <token> e o header x-client-id: <seu Client_ID> — o tenant id é o mesmo valor do Client_ID do OAuth (detalhes); sem ele a chamada falha com 400 MISSING_CLIENT_ID. O produto KYC precisa estar habilitado para o seu tenant — caso contrário as chamadas retornam 403 PRODUCT_NOT_ENABLED.

Visão geral

A API de KYC permite que o seu tenant solicite processos de verificação de identidade (background-check e, opcionalmente, documentoscopia) para pessoas físicas (PF) e pessoas jurídicas (PJ), inteiramente via API. Cada consulta é cobrada por chamada bem-sucedida, conforme o tipo (PF/PJ) e o modelo escolhido.

Modelos de background-check

O campo backgroundcheckModel define a profundidade da verificação (e o volume de dados retornado):

Modelo	Descrição
BASIC	Validação de identidade essencial
MEDIUM	Validação estendida
COMPLETE	Verificação completa (background check)

O preço unitário varia por tipo (PF/PJ) e modelo, conforme o seu contrato.

Fluxo assíncrono

O KYC é assíncrono:

1. Você inicia o processo (POST /v1/kyc/person ou /v1/kyc/company). A resposta traz um kycUUID e status: "PROCESSING".
2. O resultado é processado de forma assíncrona (processos kyc-backgroundcheck e kyc-documentscopy) — acompanhe por polling em GET /v1/kyc/list (push por webhook para eventos kyc-* está no roadmap).
3. Quando documentscopyFlag = true, é gerada uma URL de webview (entregue de forma assíncrona) que o usuário final deve preencher para concluir a documentoscopia.

A cobrança ocorre na iniciação bem-sucedida (quando o kycUUID é retornado), de forma idempotente por kycUUID.

---

POST /v1/kyc/person

Inicia um processo de KYC para uma pessoa física (identificada por CPF).

Body:

Campo	Tipo	Obrigatório	Descrição
backgroundcheckModel	string	Sim	BASIC | MEDIUM | COMPLETE
documentscopyFlag	boolean	Não	Se true, inicia a documentoscopia (gera webview) após o background-check (padrão: false)
vatNumber	string	Sim	CPF (11 dígitos)
name	string	Sim	Nome completo
birthDate	string	Sim	Data de nascimento (dd-mm-aaaa)
motherName	string	Sim	Nome completo da mãe

Response 200 OK:

{
  "status": 0,
  "httpCode": 200,
  "when": 1710498645123,
  "data": {
    "kycUUID": "9a8c3a75-4c71-4c26-b373-14f9a6c25eaf",
    "status": "PROCESSING",
    "kycType": "PF",
    "model": "BASIC",
    "documentscopy": true,
    "webviewUrl": null
  }
}

webviewUrl pode chegar null na iniciação e ser preenchida depois — consulte GET /v1/kyc/list até ela aparecer.

---

POST /v1/kyc/company

Inicia um processo de KYC para uma pessoa jurídica (identificada por CNPJ).

Body:

Campo	Tipo	Obrigatório	Descrição
backgroundcheckModel	string	Sim	BASIC | MEDIUM | COMPLETE
documentscopyFlag	boolean	Não	Se true, gera uma webview de documentoscopia para cada integrante do qsa (padrão: false)
vatNumber	string	Sim	CNPJ (14 dígitos)
legalName	string	Sim	Razão social
qsa	array	Sim	Quadro de Sócios e Administradores (1 a 3 registros); ao menos um SOCIO_ADMINISTRADOR

Cada item de qsa:

Campo	Tipo	Descrição
ownerType	string	SOCIO_ADMINISTRADOR | SOCIO
vatNumber	string	CPF do sócio
name	string	Nome do sócio
birthDate	string	Data de nascimento (dd-mm-aaaa)
motherName	string	Nome da mãe do sócio

Response 200 OK:

{
  "status": 0,
  "httpCode": 200,
  "when": 1710498645123,
  "data": {
    "kycUUID": "9a8c3a75-4c71-4c26-b373-14f9a6c25eaf",
    "status": "PROCESSING",
    "kycType": "PJ",
    "model": "COMPLETE",
    "documentscopy": false
  }
}

---

GET /v1/kyc/list

Lista os processos de KYC do seu tenant (com o status mais recente). A lista é servida do nosso registro interno, escopada ao seu tenant — você nunca enxerga processos de outros tenants.

Query params:

Param	Tipo	Obrigatório	Descrição
kycUUID	string	Não	Filtra por um processo específico

Response 200 OK:

{
  "page": 1,
  "limit": 20,
  "result": [
    {
      "kycUUID": "9a8c3a75-4c71-4c26-b373-14f9a6c25eaf",
      "vatNumber": "111***11",
      "process": "kyc-backgroundcheck",
      "status": "APPROVED",
      "kycType": "PF"
    }
  ]
}

• process: kyc-backgroundcheck | kyc-documentscopy
• status: APPROVED | REPROVED | PROCESSING | PENDING
• vatNumber é retornado mascarado.

---

POST /v1/kyc/manual-decision

Aplica uma decisão manual (aprovar/reprovar) a um processo de KYC do seu tenant. O kycUUID precisa pertencer ao seu tenant.

Body:

Campo	Tipo	Obrigatório	Descrição
kycUUID	string	Sim	Identificador do processo
decision	string	Sim	APPROVED | REPROVED
reason	string	Sim	Justificativa (até 500 caracteres)

Response 200 OK:

{
  "status": 0,
  "httpCode": 200,
  "when": 1710498645123,
  "data": {
    "kycUUID": "9a8c3a75-4c71-4c26-b373-14f9a6c25eaf",
    "decision": "APPROVED"
  }
}

---

Acompanhamento de status

Os processos de KYC são atualizados de forma assíncrona:

Processo	Quando atualiza
kyc-backgroundcheck	Conclusão/atualização do background-check
kyc-documentscopy	Geração da webview e conclusão/atualização da documentoscopia

Cada registro carrega o kycUUID e o status (APPROVED | REPROVED | PROCESSING | PENDING).

Consulte por polling. Hoje o acompanhamento é feito via GET /v1/kyc/list (ex.: a cada 30s enquanto PROCESSING). Os eventos kyc-* ainda não são entregues no webhook do tenant — o push por webhook (payload mínimo kycUUID + status) está no roadmap. Os webhooks de onboarding de conta (onboarding-*, incluindo onboarding-biometrics) não são afetados e já são entregues normalmente.

---

Erros comuns

HTTP	Situação
400	Modelo inválido (backgroundcheckModel), CPF/CNPJ ausente, qsa sem SOCIO_ADMINISTRADOR
403	Produto KYC não habilitado para o tenant; ou kycUUID de outro tenant no manual-decision

Consulte Tratamento de Erros para o envelope padrão de erro.