# Requisitos de KYC

Entenda os tipos de documentos e verificações que cada cliente precisa completar para ser aprovado.

## Fluxo de Verificação

Quando um cliente atinge o status `pending_kyc`, o array `customer.kyc` lista todos os documentos e verificações necessários. O fluxo de verificação funciona em duas etapas:

1. **Envio antecipado via API (opcional):** o parceiro envia pela API os documentos que já possui do cliente (identidade, comprovante de endereço, documentos da empresa, etc.). Isso acelera o processo porque esses documentos já estarão prontos quando o cliente iniciar a sessão de biometria.
2. **Sessão de biometria (obrigatória):** o parceiro gera uma URL de sessão e a apresenta ao cliente. Na sessão, o cliente envia os documentos restantes, tira a selfie e confirma a submissão. A confirmação é o que dispara a avaliação de todos os documentos.


A selfie só pode ser capturada pelo próprio cliente na sessão de biometria.

> **Info:** O array `kyc` só está disponível a partir do status `pending_kyc`. Durante o status `creating`, o enriquecimento de sócios ainda está em andamento e os requisitos não foram resolvidos.


## Estrutura de um Requisito

Todos os requisitos compartilham a mesma estrutura base:


```json
{
  "requirement_id": "identity_12345678900",
  "requirement_type": "identity",
  "label": "Documento de identidade",
  "mandatory": true,
  "subject": {
    "name": "Joao Silva",
    "cpf": "12345678900",
    "subject_type": "applicant"
  },
  "submitted": null
}
```

| Campo | Descrição |
|  --- | --- |
| `requirement_id` | Identificador do requisito. Use este valor ao enviar documentos. |
| `requirement_type` | Tipo do requisito. Determina quais evidências e anexos são aceitos. |
| `label` | Nome legível do requisito para exibir ao usuário. |
| `mandatory` | Se `true`, o requisito precisa ser completado para o cliente avançar. |
| `subject` | Pessoa ou empresa à qual o requisito se refere. `null` para requisitos da empresa. |
| `submitted` | Estado da submissão. `null` quando nenhum documento foi enviado. |


## Requisitos por Pessoa vs. Empresa

Requisitos podem ser vinculados a uma pessoa (sócio ou titular) ou à empresa como um todo.

Requisitos de pessoa incluem o campo `subject` com os dados de quem deve enviar o documento:


```json
"subject": {
  "name": "Joao Silva",
  "cpf": "12345678900",
  "subject_type": "applicant"
}
```

O `subject_type` pode ser:

- `applicant` para o titular do cadastro
- `co_owner` para sócios identificados durante o enriquecimento


Requisitos de empresa (como `company_document` ou `articles_of_association`) não possuem `subject`. Eles se aplicam à empresa cadastrada.

## Envio Antecipado via API

Se o parceiro já possui documentos do cliente, pode enviá-los pela API antes da sessão de biometria. Documentos enviados antecipadamente não precisam ser enviados novamente na sessão.

O endpoint `POST /v3/customers/{customer_id}/kyc-attachments` aceita uploads individuais por requisito. Cada upload precisa dos campos `requirement_id`, `evidence_type`, `attachment_type` e o arquivo.

> **Tip:** O envio antecipado é opcional, mas reduz o que o cliente precisa fazer na sessão de biometria. Quanto mais documentos o parceiro enviar, mais rápido o cliente conclui a verificação.


## Tipos de Requisitos

### `identity` - Documento de Identidade

Documento de identidade com foto de uma pessoa (titular ou sócio). Aceita CNH ou RG como evidência.

**CNH** (`evidence_type: "cnh"`): aceita duas formas de envio.

CNH física (frente e verso):

| Anexo | `attachment_type` | Formatos |
|  --- | --- | --- |
| Frente | `front` | JPEG, PNG |
| Verso | `back` | JPEG, PNG |


CNH digital (arquivo único):

| Anexo | `attachment_type` | Formatos |
|  --- | --- | --- |
| Arquivo | `file` | PDF |


**RG** (`evidence_type: "rg"`):

| Anexo | `attachment_type` | Formatos |
|  --- | --- | --- |
| Frente | `front` | JPEG, PNG |
| Verso | `back` | JPEG, PNG |



```typescript Node.js
import fs from "fs";

// CNH física - enviar frente e verso
await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "identity_12345678900",
  evidenceType: "cnh",
  attachmentType: "front",
  file: fs.createReadStream("/path/to/cnh-frente.jpg"),
});

await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "identity_12345678900",
  evidenceType: "cnh",
  attachmentType: "back",
  file: fs.createReadStream("/path/to/cnh-verso.jpg"),
});
```


```ruby Ruby
# CNH física - enviar frente e verso
client.customers.upload_kyc_attachment(
  customer.id,
  requirement_id: "identity_12345678900",
  evidence_type: "cnh",
  attachment_type: "front",
  file: File.open("/path/to/cnh-frente.jpg")
)

client.customers.upload_kyc_attachment(
  customer.id,
  requirement_id: "identity_12345678900",
  evidence_type: "cnh",
  attachment_type: "back",
  file: File.open("/path/to/cnh-verso.jpg")
)
```


```python Python
# CNH física - enviar frente e verso
client.customers.upload_kyc_attachment(
    customer.id,
    requirement_id="identity_12345678900",
    evidence_type="cnh",
    attachment_type="front",
    file=open("/path/to/cnh-frente.jpg", "rb"),
)

client.customers.upload_kyc_attachment(
    customer.id,
    requirement_id="identity_12345678900",
    evidence_type="cnh",
    attachment_type="back",
    file=open("/path/to/cnh-verso.jpg", "rb"),
)
```


```bash cURL
# CNH física - frente
curl -X POST "https://sandbox.api.dinie.com.br/v3/customers/${CUSTOMER_ID}/kyc-attachments" \
  -H "Authorization: Bearer dinie_at_..." \
  -F "requirement_id=identity_12345678900" \
  -F "evidence_type=cnh" \
  -F "attachment_type=front" \
  -F "file=@/path/to/cnh-frente.jpg"

# CNH física - verso
curl -X POST "https://sandbox.api.dinie.com.br/v3/customers/${CUSTOMER_ID}/kyc-attachments" \
  -H "Authorization: Bearer dinie_at_..." \
  -F "requirement_id=identity_12345678900" \
  -F "evidence_type=cnh" \
  -F "attachment_type=back" \
  -F "file=@/path/to/cnh-verso.jpg"
```

> **Tip:** A CNH digital é enviada como um único PDF, sem necessidade de separar frente e verso.


### `selfie` - Selfie

Foto do rosto da pessoa para validação biométrica. Sempre vinculada a um `subject`.

| Anexo | `attachment_type` | Formatos |
|  --- | --- | --- |
| Foto | `photo` | JPEG, PNG |


> **Warning:** A selfie só pode ser capturada pelo cliente na sessão de biometria. Não é possível enviar a selfie pela API.


### `proof_of_address` - Comprovante de Endereço

Comprovante de endereço da pessoa. Sempre vinculado a um `subject`.

| Anexo | `attachment_type` | Formatos |
|  --- | --- | --- |
| Arquivo | `file` | PDF, JPEG, PNG |



```typescript Node.js
await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "proof_of_address_12345678900",
  evidenceType: "proof_of_address",
  attachmentType: "file",
  file: fs.createReadStream("/path/to/comprovante.pdf"),
});
```


```ruby Ruby
client.customers.upload_kyc_attachment(
  customer.id,
  requirement_id: "proof_of_address_12345678900",
  evidence_type: "proof_of_address",
  attachment_type: "file",
  file: File.open("/path/to/comprovante.pdf")
)
```


```python Python
client.customers.upload_kyc_attachment(
    customer.id,
    requirement_id="proof_of_address_12345678900",
    evidence_type="proof_of_address",
    attachment_type="file",
    file=open("/path/to/comprovante.pdf", "rb"),
)
```


```bash cURL
curl -X POST "https://sandbox.api.dinie.com.br/v3/customers/${CUSTOMER_ID}/kyc-attachments" \
  -H "Authorization: Bearer dinie_at_..." \
  -F "requirement_id=proof_of_address_12345678900" \
  -F "evidence_type=proof_of_address" \
  -F "attachment_type=file" \
  -F "file=@/path/to/comprovante.pdf"
```

### `company_document` - Documento da Empresa

Documento constitutivo da empresa. Requisito sem `subject`, aplicado à empresa cadastrada.

| Anexo | `attachment_type` | Formatos |
|  --- | --- | --- |
| Arquivo | `file` | PDF, JPEG, PNG |


O `evidence_type` é `ccmei` (Certificado da Condição de Microempreendedor Individual).


```typescript Node.js
await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "company_document",
  evidenceType: "ccmei",
  attachmentType: "file",
  file: fs.createReadStream("/path/to/ccmei.pdf"),
});
```


```ruby Ruby
client.customers.upload_kyc_attachment(
  customer.id,
  requirement_id: "company_document",
  evidence_type: "ccmei",
  attachment_type: "file",
  file: File.open("/path/to/ccmei.pdf")
)
```


```python Python
client.customers.upload_kyc_attachment(
    customer.id,
    requirement_id="company_document",
    evidence_type="ccmei",
    attachment_type="file",
    file=open("/path/to/ccmei.pdf", "rb"),
)
```


```bash cURL
curl -X POST "https://sandbox.api.dinie.com.br/v3/customers/${CUSTOMER_ID}/kyc-attachments" \
  -H "Authorization: Bearer dinie_at_..." \
  -F "requirement_id=company_document" \
  -F "evidence_type=ccmei" \
  -F "attachment_type=file" \
  -F "file=@/path/to/ccmei.pdf"
```

### `ei_mei_documents` - Documentos de EI/MEI

Requisito composto que exige dois documentos: o registro de EI e o CCMEI. Ambos precisam ser enviados. Sem `subject`.

| Anexo | `attachment_type` | Formatos |
|  --- | --- | --- |
| Registro de EI | `ei_registration_requirement` | PDF, JPEG, PNG |
| CCMEI | `ccmei` | PDF, JPEG, PNG |


O `evidence_type` para ambos é `ei_mei`.


```typescript Node.js
// Registro de EI
await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "ei_mei_documents",
  evidenceType: "ei_mei",
  attachmentType: "ei_registration_requirement",
  file: fs.createReadStream("/path/to/registro-ei.pdf"),
});

// CCMEI
await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "ei_mei_documents",
  evidenceType: "ei_mei",
  attachmentType: "ccmei",
  file: fs.createReadStream("/path/to/ccmei.pdf"),
});
```


```ruby Ruby
# Registro de EI
client.customers.upload_kyc_attachment(
  customer.id,
  requirement_id: "ei_mei_documents",
  evidence_type: "ei_mei",
  attachment_type: "ei_registration_requirement",
  file: File.open("/path/to/registro-ei.pdf")
)

# CCMEI
client.customers.upload_kyc_attachment(
  customer.id,
  requirement_id: "ei_mei_documents",
  evidence_type: "ei_mei",
  attachment_type: "ccmei",
  file: File.open("/path/to/ccmei.pdf")
)
```


```python Python
# Registro de EI
client.customers.upload_kyc_attachment(
    customer.id,
    requirement_id="ei_mei_documents",
    evidence_type="ei_mei",
    attachment_type="ei_registration_requirement",
    file=open("/path/to/registro-ei.pdf", "rb"),
)

# CCMEI
client.customers.upload_kyc_attachment(
    customer.id,
    requirement_id="ei_mei_documents",
    evidence_type="ei_mei",
    attachment_type="ccmei",
    file=open("/path/to/ccmei.pdf", "rb"),
)
```


```bash cURL
# Registro de EI
curl -X POST "https://sandbox.api.dinie.com.br/v3/customers/${CUSTOMER_ID}/kyc-attachments" \
  -H "Authorization: Bearer dinie_at_..." \
  -F "requirement_id=ei_mei_documents" \
  -F "evidence_type=ei_mei" \
  -F "attachment_type=ei_registration_requirement" \
  -F "file=@/path/to/registro-ei.pdf"

# CCMEI
curl -X POST "https://sandbox.api.dinie.com.br/v3/customers/${CUSTOMER_ID}/kyc-attachments" \
  -H "Authorization: Bearer dinie_at_..." \
  -F "requirement_id=ei_mei_documents" \
  -F "evidence_type=ei_mei" \
  -F "attachment_type=ccmei" \
  -F "file=@/path/to/ccmei.pdf"
```

### `income_statement` - Declaração de Faturamento

Declaração de faturamento da empresa. Sem `subject`.

| Anexo | `attachment_type` | Formatos |
|  --- | --- | --- |
| Arquivo | `file` | PDF, JPEG, PNG |



```typescript Node.js
await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "income_statement",
  evidenceType: "income_statement",
  attachmentType: "file",
  file: fs.createReadStream("/path/to/faturamento.pdf"),
});
```


```ruby Ruby
client.customers.upload_kyc_attachment(
  customer.id,
  requirement_id: "income_statement",
  evidence_type: "income_statement",
  attachment_type: "file",
  file: File.open("/path/to/faturamento.pdf")
)
```


```python Python
client.customers.upload_kyc_attachment(
    customer.id,
    requirement_id="income_statement",
    evidence_type="income_statement",
    attachment_type="file",
    file=open("/path/to/faturamento.pdf", "rb"),
)
```


```bash cURL
curl -X POST "https://sandbox.api.dinie.com.br/v3/customers/${CUSTOMER_ID}/kyc-attachments" \
  -H "Authorization: Bearer dinie_at_..." \
  -F "requirement_id=income_statement" \
  -F "evidence_type=income_statement" \
  -F "attachment_type=file" \
  -F "file=@/path/to/faturamento.pdf"
```

### `articles_of_association` - Contrato Social

Contrato social ou documento equivalente da empresa. Sem `subject`.

| Anexo | `attachment_type` | Formatos |
|  --- | --- | --- |
| Arquivo | `file` | PDF, JPEG, PNG |



```typescript Node.js
await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "articles_of_association",
  evidenceType: "articles_of_association",
  attachmentType: "file",
  file: fs.createReadStream("/path/to/contrato-social.pdf"),
});
```


```ruby Ruby
client.customers.upload_kyc_attachment(
  customer.id,
  requirement_id: "articles_of_association",
  evidence_type: "articles_of_association",
  attachment_type: "file",
  file: File.open("/path/to/contrato-social.pdf")
)
```


```python Python
client.customers.upload_kyc_attachment(
    customer.id,
    requirement_id="articles_of_association",
    evidence_type="articles_of_association",
    attachment_type="file",
    file=open("/path/to/contrato-social.pdf", "rb"),
)
```


```bash cURL
curl -X POST "https://sandbox.api.dinie.com.br/v3/customers/${CUSTOMER_ID}/kyc-attachments" \
  -H "Authorization: Bearer dinie_at_..." \
  -F "requirement_id=articles_of_association" \
  -F "evidence_type=articles_of_association" \
  -F "attachment_type=file" \
  -F "file=@/path/to/contrato-social.pdf"
```

### `eireli_incorporation_statement` - Ato Constitutivo de EIRELI

Ato constitutivo de Empresa Individual de Responsabilidade Limitada. Sem `subject`.

| Anexo | `attachment_type` | Formatos |
|  --- | --- | --- |
| Arquivo | `file` | PDF, JPEG, PNG |



```typescript Node.js
await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "eireli_incorporation_statement",
  evidenceType: "eireli_incorporation_statement",
  attachmentType: "file",
  file: fs.createReadStream("/path/to/ato-constitutivo.pdf"),
});
```


```ruby Ruby
client.customers.upload_kyc_attachment(
  customer.id,
  requirement_id: "eireli_incorporation_statement",
  evidence_type: "eireli_incorporation_statement",
  attachment_type: "file",
  file: File.open("/path/to/ato-constitutivo.pdf")
)
```


```python Python
client.customers.upload_kyc_attachment(
    customer.id,
    requirement_id="eireli_incorporation_statement",
    evidence_type="eireli_incorporation_statement",
    attachment_type="file",
    file=open("/path/to/ato-constitutivo.pdf", "rb"),
)
```


```bash cURL
curl -X POST "https://sandbox.api.dinie.com.br/v3/customers/${CUSTOMER_ID}/kyc-attachments" \
  -H "Authorization: Bearer dinie_at_..." \
  -F "requirement_id=eireli_incorporation_statement" \
  -F "evidence_type=eireli_incorporation_statement" \
  -F "attachment_type=file" \
  -F "file=@/path/to/ato-constitutivo.pdf"
```

### `email` - Email do Co-titular

Requisito de nível pessoal para coletar o email de co-titulares que precisam assinar digitalmente a CCB. Cada co-titular gera um requisito `email_{cpf}` com o campo `subject` identificando a pessoa.

> **Nota:** O email do titular principal já é informado na criação do cliente. Este requisito aparece apenas para co-titulares que precisam assinar a CCB.


O envio é feito pelo endpoint de upload de anexos KYC, usando o campo `value` em vez de `file`:


```typescript Node.js
await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "email_12345678900",
  evidenceType: "email",
  attachmentType: "email",
  value: "co-titular@example.com",
});
```


```ruby Ruby
client.customers.upload_kyc_attachment(
  customer.id,
  requirement_id: "email_12345678900",
  evidence_type: "email",
  attachment_type: "email",
  value: "co-titular@example.com"
)
```


```python Python
client.customers.upload_kyc_attachment(
    customer.id,
    requirement_id="email_12345678900",
    evidence_type="email",
    attachment_type="email",
    value="co-titular@example.com",
)
```


```bash cURL
curl -X POST "https://sandbox.api.dinie.com.br/v3/customers/${CUSTOMER_ID}/kyc-attachments" \
  -H "Authorization: Bearer dinie_at_..." \
  -F "requirement_id=email_12345678900" \
  -F "evidence_type=email" \
  -F "attachment_type=email" \
  -F "value=co-titular@example.com"
```

## Sessão de Biometria

Após enviar os documentos que já possui (ou mesmo sem enviar nenhum), o parceiro deve gerar uma sessão de biometria e apresentar a URL ao cliente. Na sessão, o cliente envia os documentos pendentes, captura a selfie e confirma a submissão.

A confirmação na sessão de biometria dispara a avaliação de todos os documentos, incluindo os enviados antecipadamente via API.


```typescript Node.js
const session = await client.customers.createBiometricsSession(customer.id);

// Apresente esta URL ao cliente
console.log(session.session_url);
console.log(session.expires_at);  // Expira em 30 minutos
```


```ruby Ruby
session = client.customers.create_biometrics_session(customer.id)

# Apresente esta URL ao cliente
puts session.session_url
puts session.expires_at  # Expira em 30 minutos
```


```python Python
session = client.customers.create_biometrics_session(customer.id)

# Apresente esta URL ao cliente
print(session.session_url)
print(session.expires_at)  # Expira em 30 minutos
```


```bash cURL
curl -X POST "https://sandbox.api.dinie.com.br/v3/customers/${CUSTOMER_ID}/biometrics" \
  -H "Authorization: Bearer dinie_at_..."
```

> **Info:** A sessão de biometria expira em 30 minutos. Gere uma nova sessão caso o tempo expire.


## Status de Revisão

Após a confirmação na sessão de biometria, cada requisito passa por revisão. O campo `submitted.review_status` indica o resultado:

| Status | Descrição |
|  --- | --- |
| `pending` | Documento enviado, aguardando revisão |
| `accepted` | Documento aprovado |
| `rejected` | Documento rejeitado. Consulte `review_reason` para o motivo |


Quando um documento é rejeitado, o campo `submitted.review_reason` contém o motivo. Envie um novo documento para o mesmo `requirement_id` para substituir o anterior.

## Acompanhando o Progresso

O webhook `customer.kyc_updated` é disparado sempre que um documento é enviado com sucesso. O payload inclui o array `kyc` atualizado com o estado de todos os requisitos.

Quando todos os requisitos obrigatórios são aceitos, o status do cliente avança para `under_review` e depois para `active`.

## Referência Rápida

| Requisito | `evidence_type` | Anexos | Formatos | Sujeito | Envio via API |
|  --- | --- | --- | --- | --- | --- |
| `identity` | `cnh` | `front`, `back` (física) ou `file` (digital) | JPEG, PNG ou PDF | Pessoa | Sim |
| `identity` | `rg` | `front`, `back` | JPEG, PNG | Pessoa | Sim |
| `selfie` | `selfie` | `photo` | JPEG, PNG | Pessoa | Somente biometria |
| `proof_of_address` | `proof_of_address` | `file` | PDF, JPEG, PNG | Pessoa | Sim |
| `company_document` | `ccmei` | `file` | PDF, JPEG, PNG | Empresa | Sim |
| `ei_mei_documents` | `ei_mei` | `ei_registration_requirement`, `ccmei` | PDF, JPEG, PNG | Empresa | Sim |
| `income_statement` | `income_statement` | `file` | PDF, JPEG, PNG | Empresa | Sim |
| `articles_of_association` | `articles_of_association` | `file` | PDF, JPEG, PNG | Empresa | Sim |
| `eireli_incorporation_statement` | `eireli_incorporation_statement` | `file` | PDF, JPEG, PNG | Empresa | Sim |
| `email` | `email` | `email` | texto (value) | Pessoa | Sim |


## Guias Relacionados

- [Cadastro e Ofertas](/guides/customer-registration) para o fluxo completo de onboarding
- [Webhooks](/apis/concepts/webhooks) para configurar os endpoints de notificação