> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /api/v1/accounts/kyc/documents

> Faz upload de um documento KYC para o seller de uma organização. Aceita imagens e PDF (apenas CNH_FULL). Limite de 3 MB por arquivo.

Envia um documento KYC para verificação do seller de uma organização. A requisição deve ser `multipart/form-data`. Cada chamada envia **um documento por vez**. Use [Consultar Status KYC](https://scaleup-c34c4386.mintlify.site/api-reference/accounts/kyc/get-documents.md) para saber quais documentos ainda estão pendentes.

> [!NOTE]
>
> A organização pai pode enviar documentos em nome de suas sub-organizações filhas. Basta usar o JWT da organização pai e informar o `organization_id` da filha.

## Autenticação

Aceita dois tipos de autenticação:

* **JWT da própria organização** — organização enviando seus próprios documentos
* **JWT da organização pai** — organização pai enviando documentos em nome de uma filha

## Corpo da Requisição (multipart/form-data)

**organization\_id** `string` *required*

Identificador único da organização cujo documento será enviado.

**type** `string` *required*

Tipo do documento. Valores aceitos: `SELFIE`, `CNH_FULL`, `CNH_FRONT`, `CNH_BACK`, `RG_FRONT`, `RG_BACK`.

**file** `file` *required*

Arquivo do documento. Tamanho máximo: **3 MB**.

## Formatos Aceitos por Tipo

| Tipo | Formatos | PDF aceito? |
| - | - | - |
| `SELFIE` | JPEG, PNG, BMP, WebP, HEIC, HEIF | Não |
| `CNH_FULL` | JPEG, PNG, BMP, WebP, HEIC, HEIF, **PDF** | **Sim** |
| `CNH_FRONT` | JPEG, PNG, BMP, WebP, HEIC, HEIF | Não |
| `CNH_BACK` | JPEG, PNG, BMP, WebP, HEIC, HEIF | Não |
| `RG_FRONT` | JPEG, PNG, BMP, WebP, HEIC, HEIF | Não |
| `RG_BACK` | JPEG, PNG, BMP, WebP, HEIC, HEIF | Não |

## Resposta

**success** `boolean`

`true` quando o documento foi enviado com sucesso.

**document\_type** `string`

Tipo do documento enviado.

**result** `object`

Resposta bruta do gateway de pagamento.

## Exemplos

### Sub-organização enviando seu próprio documento

```bash cURL theme={null}
curl -X POST "https://app.chargefy.io/api/v1/accounts/kyc/documents" \
  -H "Authorization: Bearer $SUBORG_ACCESS_TOKEN" \
  -F "organization_id=org_01j9abc333" \
  -F "type=SELFIE" \
  -F "file=@/caminho/para/selfie.jpg"
```

```typescript SDK theme={null}
import { Chargefy } from 'chargefy-js';
import fs from 'fs';

const chargefy = new Chargefy({ accessToken: '<supabase_jwt>', server: 'production' });

const file = fs.readFileSync('./selfie.jpg');
const result = await chargefy.kyc.uploadDocument('org_01j9abc333', 'SELFIE', file);
if (result.ok) {
  console.log('Documento enviado:', result.value.documentType);
}
```

```javascript Browser (fetch) theme={null}
const form = new FormData();
form.append('organization_id', 'org_01j9abc333');
form.append('type', 'SELFIE');
form.append('file', fileInput.files[0]); // <input type="file">

const response = await fetch('https://app.chargefy.io/api/v1/accounts/kyc/documents', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer <supabase_jwt>' },
  // NÃO definir Content-Type manualmente — o fetch define automaticamente com o boundary
  body: form,
});
const result = await response.json();
```

### Organização pai enviando documento de uma filha

```bash cURL theme={null}
curl -X POST "https://app.chargefy.io/api/v1/accounts/kyc/documents" \
  -H "Authorization: Bearer $PARENT_ACCESS_TOKEN" \
  -F "organization_id=org_01j9abc333" \
  -F "type=CNH_FRONT" \
  -F "file=@/caminho/para/cnh_frente.jpg"
```

```typescript SDK theme={null}
// Inicializar com o JWT da organização PAI
const chargefy = new Chargefy({ accessToken: '<supabase_jwt>', server: 'production' });

// Enviar documento para a sub-organização FILHA
const file = fs.readFileSync('./cnh_frente.jpg');
await chargefy.kyc.uploadDocument('org_01j9abc333', 'CNH_FRONT', file);
```

### Fluxo completo de envio de documentos

```typescript theme={null}
import { Chargefy } from 'chargefy-js';
import fs from 'fs';

const chargefy = new Chargefy({ accessToken: '<supabase_jwt>', server: 'production' });
const orgId = 'org_01j9abc333';

// 1. Verificar quais documentos ainda faltam
const statusResult = await chargefy.kyc.getDocuments(orgId);
if (!statusResult.ok) throw new Error('Falha ao consultar status KYC');

const { documents, kycComplete } = statusResult.value;

if (kycComplete) {
  console.log('KYC já está completo!');
} else {
  console.log('Documentos pendentes:', documents.pendingUpload);

  // 2. Enviar cada documento pendente
  for (const docType of documents.pendingUpload) {
    const filePath = `./documentos/${docType.toLowerCase()}.jpg`;
    const file = fs.readFileSync(filePath);

    const uploadResult = await chargefy.kyc.uploadDocument(orgId, docType, file);
    if (uploadResult.ok) {
      console.log(`✓ ${docType} enviado com sucesso`);
    } else {
      console.error(`✗ Falha ao enviar ${docType}:`, uploadResult.error);
    }
  }
}
```

## Resposta de Exemplo

```json theme={null}
{
  "success": true,
  "document_type": "SELFIE",
  "result": {}
}
```

## Erros

| Status | Descrição |
| - | - |
| `400` | Campo ausente, tipo inválido, formato de arquivo não permitido ou arquivo maior que 3 MB |
| `401` | Token ausente ou inválido |
| `403` | Token não pertence à organização ou à sua organização pai |
| `404` | Seller não encontrado para esta organização |
| `412` | Seller não pode receber documentos no estado atual (ex: já aprovado ou desabilitado) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.