---
agentTools:
  projectIndex: https://docs.grafeno.digital/llms.txt
---

# Fazer upload dos documentos do devedor

Faz o upload dos documentos do devedor para a plataforma.

Depois de cadastrar o tomador de crédito, é necessário enviar seus documentos comprobatórios. O envio ocorre em duas requisições: primeiro solicita-se uma **URL assinada** para um documento específico e, em seguida, o arquivo é enviado para essa URL em formato **binary**.

## Fluxo de envio

O processo ocorre em etapas, repetidas para cada documento:

1. **Cadastrar o tomador de crédito**: O devedor é cadastrado e passa a ser identificado pelo seu `CPF` ou `CNPJ`.
2. **Solicitar a URL assinada**: Envie um `POST` indicando o devedor e o tipo/formato do documento. A resposta traz a URL assinada.
3. **Enviar o arquivo** : O conteúdo do documento é enviado para a URL assinada via `PUT`, no corpo da requisição, em formato binário.
4. **Repetir**: O processo se repete para cada documento obrigatório do tomador.

> ⚠️ **Atenção ao envio de documentos**
>
> O cadastro e o upload de documentos do tomador de crédito são feitos **um documento por vez**. Não é possível enviar mais de um documento na mesma requisição. Além disso, o cliente é responsável por atender a **todos os documentos necessários e obrigatórios** conforme o tipo de tomador (**PF**, **PJ** e **representante legal**). Consulte a lista completa de documentos exigidos para cada tipo em [NOME\_DO\_LINK](URL_DA_DOC).

## Etapa 1 - Solicitar a URL assinada

Envie um `POST` informando o devedor e o documento a ser enviado. A resposta conterá a **URL assinada** para o upload.

```
POST /laas/v2/debtors/url-document
```

| Ambiente | Base URL                       |
| -------- | ------------------------------ |
| Staging  | `https://apis.stg.grafeno.be`  |
| Produção | `https://apis.grafeno.digital` |

### Parâmetros do corpo

| Parâmetro                       | Tipo     | Descrição                                                                                                        |
| ------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `debtor_identification`         | `string` | Identificador do devedor: `CPF` (PF) ou `CNPJ` (PJ), somente dígitos.                                            |
| `representative_identification` | `string` | Identificador do representante legal do devedor PJ: `CPF` , somente dígitos.                                     |
| `file_type`                     | `string` | Identificador do tipo de documento (ex.: `debtor_address_proof_file`). Ver a lista completa por tipo de tomador. |
| `file_format`                   | `string` | Formato do arquivo. Valores: `pdf`, `jpeg`, `jpg`.                                                               |

### Documentos necessários

| Tipo de devedor              | Documento                                       | Identificador (`file_type`)                      |
| ---------------------------- | ----------------------------------------------- | ------------------------------------------------ |
| **PF**                       | Documento de identificação (RG/CNH)             | `debtor_identification_file`                     |
| **PF**                       | Comprovante de renda                            | `debtor_proof_of_income_file`                    |
| **PF**                       | Comprovante de endereço                         | `debtor_address_proof_file`                      |
| **PJ**                       | Contrato social ou estatuto                     | `debtor_social_or_statute_contract`              |
| **PJ**                       | Comprovante de endereço                         | `debtor_address_proof_file`                      |
| **PJ**                       | Comprovante de faturamento dos últimos 12 meses | `debtor_monthly_turnover_on_last_12_months_file` |
| **Representante Legal** (PJ) | Documento de identificação do representante     | `representative_identification_file`             |
| **Representante Legal** (PJ) | Comprovante de endereço do representante        | `representative_address_proof_file`              |

<br />

> 📘 Informação
>
> Para devedores do tipo **PJ**, os documentos do **representante legal** (`representative_identification_file` e `representative_address_proof_file`) são **obrigatórios** no cadastro. Um cadastro de PJ sem os documentos do representante não será validado, e a confirmação da operação falhará.

### Exemplo de requisição

```curl cURL
curl --location 'https://apis.stg.grafeno.be/laas/v2/debtors/url-document' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
    "debtor_identification": "{cpf_ou_cnpj_do_devedor}",
    "file_type": "debtor_address_proof_file",
    "file_format": "pdf"
}'
```

### Resposta

A resposta retorna a **URL assinada** que será utilizada na etapa seguinte para o upload do arquivo.

```json 200 OK
{
  "url": "https://..."
}
```

## Etapa 2 - Enviar o arquivo

Com a URL assinada em mãos, envie o conteúdo do arquivo via `PUT`, em formato binário.

### Formatos aceitos

O header `Content-Type` da requisição **deve corresponder** ao formato do arquivo:

| Formato | Extensão | `Content-Type`    |
| ------- | -------- | ----------------- |
| PDF     | `.pdf`   | `application/pdf` |
| JPEG    | `.jpeg`  | `image/jpeg`      |
| JPG     | `.jpg`   | `image/jpeg`      |

### Regras do upload

* O método HTTP é **`PUT`**.
* O corpo da requisição é o **conteúdo binário** do arquivo (`--data-binary`), e **não** `multipart/form-data` nem base64.
* O header `Content-Type` deve refletir o formato real do arquivo (ver tabela acima) e ser coerente com o `file_format` informado na Etapa 1.
* Cada URL assinada corresponde a **um único documento** (`file_type`) e possui **validade limitada** de 60 segundos. Utilize-a dentro da janela de expiração.

### Exemplo: envio de um PDF

```curl cURL
curl --location --request PUT '{url_assinada}' \
--header 'Content-Type: application/pdf' \
--data-binary '@/caminho/para/documento.pdf'
```

### Exemplo: envio de uma imagem (JPEG/JPG)

```curl cURL
curl --location --request PUT '{url_assinada}' \
--header 'Content-Type: image/jpeg' \
--data-binary '@/caminho/para/documento.jpg'
```

## Validação

O envio dos arquivos é validado ao longo do processo. Se o tomador não tiver todos os documentos obrigatórios enviados, a **confirmação da operação** falhará, e o motivo será retornado via **webhook** (evento `credit-created.failed`), com mensagens como "devedor ainda não validado" ou documento/minuta ausente.