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

# Tomadores de Crédito

Cadastro de devedores.

O tomador de crédito é o **devedor** de uma operação. Antes de construir a operação, é necessário cadastrar o devedor e enviar seus documentos comprobatórios.

A API aceita dois tipos de devedores:

* **Pessoa Física (PF)**: Identificada pelo **CPF**.
* **Pessoa Jurídica (PJ)**: Identificada pelo **CNPJ**. Toda PJ deve possuir um **representante legal**, cujos documentos também são enviados na operação.

> 📘 Informação
>
> O identificador do devedor (`CPF` ou `CNPJ`) é a chave utilizada para vinculá-lo à operação e aos seus documentos.

## Cadastro de Devedores

Este endpoint cadastra o **devedor** (tomador) que será vinculado às operações do Motor de Ativos. O mesmo endpoint atende **Pessoa Física** e **Pessoa Jurídica**. O campo `person_type` define o comportamento e, consequentemente, quais campos são obrigatórios.

```
POST /laas/v2/debtors
```

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

> 📘 Campos condicionais por tipo de pessoa
>
> Além dos campos comuns, o payload exige um conjunto de dados adicionais conforme o `person_type`:
>
> * `natural_person` (PF) → `birth_date`, `mother_name`, `marital_status`, `earnings`
> * `legal_person` (PJ) → `foundation_date`, `legal_status`, `cnae`, `gross_revenue_last_12_months`, `legal_representatives`

## Campos comuns (PF e PJ)

Aplicam-se aos dois tipos de pessoa.

| Parâmetro             | Tipo            | Obrigatório | Descrição                                                               |
| --------------------- | --------------- | ----------- | ----------------------------------------------------------------------- |
| `person_type`         | `string` (enum) | Sim         | Tipo de pessoa. Valores: `natural_person`, `legal_person`.              |
| `name`                | `string`        | Sim         | Nome completo (PF) ou razão social (PJ).                                |
| `identification`      | `string`        | Sim         | CPF (PF) ou CNPJ (PJ).                                                  |
| `email`               | `string`        | Sim         | E-mail de contato.                                                      |
| `phone`               | `string`        | Sim         | Telefone com DDD.                                                       |
| `street`              | `string`        | Sim         | Logradouro.                                                             |
| `address_number`      | `string`        | Sim         | Número do endereço.                                                     |
| `neighborhood`        | `string`        | Sim         | Bairro.                                                                 |
| `city`                | `string`        | Sim         | Cidade.                                                                 |
| `state`               | `string`        | Sim         | UF (2 letras).                                                          |
| `zip_code`            | `string`        | Sim         | CEP.                                                                    |
| `account_type`        | `string` (enum) | Sim         | Tipo de conta bancária. Valores: `checking_account`, `savings_account`. |
| `bank`                | `integer`       | Sim         | Código do banco (COMPE).                                                |
| `bank_agency`         | `string`        | Sim         | Número da agência.                                                      |
| `bank_account_number` | `string`        | Sim         | Número da conta com dígito.                                             |
| `pep`                 | `string` (enum) | Sim         | Pessoa Exposta Politicamente. Valores: `Sim`, `Não`.                    |
| `nationality`         | `string`        | Sim         | Nacionalidade.                                                          |

## Campos exclusivos de Pessoa Física

Obrigatórios quando `person_type` = `natural_person`.

| Parâmetro        | Tipo                           | Obrigatório | Descrição                                                          |
| ---------------- | ------------------------------ | ----------- | ------------------------------------------------------------------ |
| `birth_date`     | `string` (date-time, ISO 8601) | Sim (PF)    | Data de nascimento.                                                |
| `mother_name`    | `string`                       | Sim (PF)    | Nome da mãe.                                                       |
| `marital_status` | `string` (enum)                | Sim (PF)    | Estado civil. Valores: `single`, `married`, `divorced`, `widowed`. |
| `earnings`       | `number`                       | Sim (PF)    | Renda mensal declarada.                                            |

## Campos exclusivos de Pessoa Jurídica

Obrigatórios quando `person_type` = `legal_person`.

| Parâmetro                      | Tipo                           | Obrigatório | Descrição                                             |
| ------------------------------ | ------------------------------ | ----------- | ----------------------------------------------------- |
| `foundation_date`              | `string` (date-time, ISO 8601) | Sim (PJ)    | Data de fundação.                                     |
| `legal_status`                 | `string` (enum)                | Sim (PJ)    | Natureza jurídica. Ver valores aceitos abaixo.        |
| `cnae`                         | `string`                       | Sim (PJ)    | Código CNAE da atividade principal.                   |
| `gross_revenue_last_12_months` | `number`                       | Sim (PJ)    | Faturamento dos últimos 12 meses.                     |
| `legal_representatives`        | `array<object>`                | Sim (PJ)    | Lista de representantes legais. Ver estrutura abaixo. |

**Valores aceitos em `legal_status`:**

`mei`, `ei`, `eireli`, `sociedade_anonima`, `sociedade_simples_limitada`, `sociedade_limitada_unipessoal`, `sociedade_empresaria_limitada`, `sociedade_em_conta_de_participacao`, `inova_simples`, `empresario_rural`, `cooperativa`, `empresa_simples_de_credito` e `sociedade_anonima_do_futebol`.

### Objeto `legal_representatives[]`

Cada item do array representa um representante legal da PJ.

| Parâmetro             | Tipo                           | Obrigatório | Descrição                                                      |
| --------------------- | ------------------------------ | ----------- | -------------------------------------------------------------- |
| `name`                | `string`                       | Sim         | Nome completo do representante.                                |
| `identification`      | `string`                       | Sim         | CPF do representante.                                          |
| `email`               | `string`                       | Sim         | E-mail de contato.                                             |
| `phone`               | `string`                       | Sim         | Telefone com DDD.                                              |
| `birth_date`          | `string` (date-time, ISO 8601) | Sim         | Data de nascimento.                                            |
| `mother_name`         | `string`                       | Sim         | Nome da mãe.                                                   |
| `pep`                 | `string` (enum)                | Sim         | Pessoa Exposta Politicamente. Valores: `Sim`, `Não`.           |
| `nationality`         | `string`                       | Sim         | Nacionalidade.                                                 |
| `street`              | `string`                       | Sim         | Logradouro.                                                    |
| `address_number`      | `string`                       | Sim         | Número do endereço.                                            |
| `neighborhood`        | `string`                       | Sim         | Bairro.                                                        |
| `city`                | `string`                       | Sim         | Cidade.                                                        |
| `state`               | `string`                       | Sim         | UF (2 letras).                                                 |
| `zip_code`            | `string`                       | Sim         | CEP.                                                           |
| `account_type`        | `string` (enum)                | Sim         | Tipo de conta. Valores: `checking_account`, `savings_account`. |
| `bank`                | `integer`                      | Sim         | Código do banco (COMPE).                                       |
| `bank_agency`         | `string`                       | Sim         | Número da agência.                                             |
| `bank_account_number` | `string`                       | Sim         | Número da conta com dígito.                                    |

## Exemplo de requisição: Pessoa Jurídica

```json
{
  "person_type": "legal_person",
  "name": "Empresa Exemplo Ltda",
  "identification": "00000000000000",
  "email": "contato@exemplo.com",
  "phone": "(11) 99999-9999",
  "street": "Av. Exemplo",
  "address_number": "702",
  "neighborhood": "Centro",
  "city": "São Paulo",
  "state": "SP",
  "zip_code": "01230-000",
  "account_type": "checking_account",
  "bank": 310,
  "bank_agency": "0001",
  "bank_account_number": "80758-0",
  "pep": "Não",
  "nationality": "Brasileiro",
  "foundation_date": "1949-03-02T12:19:45.764Z",
  "legal_status": "sociedade_empresaria_limitada",
  "cnae": "9056-0/77",
  "gross_revenue_last_12_months": 120000,
  "legal_representatives": [
    {
      "name": "Representante Exemplo",
      "identification": "00000000000",
      "email": "representante@exemplo.com",
      "phone": "(11) 99999-9999",
      "birth_date": "1970-01-20T12:19:45.764Z",
      "mother_name": "Nome da Mãe Exemplo",
      "pep": "Não",
      "nationality": "Brasileiro",
      "street": "Av. Exemplo",
      "address_number": "702",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zip_code": "01230-000",
      "account_type": "savings_account",
      "bank": 310,
      "bank_agency": "0001",
      "bank_account_number": "80758-0"
    }
  ]
}
```

## Exemplo de requisição: Pessoa Física

```json
{
  "person_type": "natural_person",
  "name": "Nome Exemplo",
  "identification": "00000000000",
  "email": "pessoa@exemplo.com",
  "phone": "(11) 99999-9999",
  "street": "Av. Exemplo",
  "address_number": "702",
  "neighborhood": "Centro",
  "city": "São Paulo",
  "state": "SP",
  "zip_code": "01230-000",
  "account_type": "checking_account",
  "bank": 310,
  "bank_agency": "0001",
  "bank_account_number": "80758-0",
  "pep": "Não",
  "nationality": "Brasileiro",
  "birth_date": "1990-03-02T12:19:45.764Z",
  "mother_name": "Nome da Mãe Exemplo",
  "marital_status": "single",
  "earnings": 200000.00
}
```

> 🚧 Formato de datas
>
> Os campos `birth_date` e `foundation_date` seguem o padrão ISO 8601 (`YYYY-MM-DDTHH:mm:ss.sssZ`).

## Fluxo de envio de documentos

O envio de documentos ocorre em duas etapas:

1. **Cadastro do devedor**: O devedor é cadastrado na operação com seu identificador (`CPF`/`CNPJ`) e demais dados.
2. **Upload via URL assinada**: Para cada documento, a API disponibiliza uma **URL assinada**. O arquivo é então enviado diretamente para essa URL em formato **binary**.

> ⚠️ Importante
>
> O conteúdo do arquivo deve ser enviado como **binary** (corpo bruto da requisição), e não como `multipart/form-data` ou base64. Cada URL assinada corresponde a um único documento (`file_type`) e possui validade limitada.

### Exemplo de upload

```bash cURL
curl --request PUT \
     --url '{url_assinada}' \
     --header 'content-type: application/pdf' \
     --data-binary '@documento.pdf'
```

## Formatos aceitos

Os documentos devem ser enviados em um dos seguintes formatos:

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

## Documentos por tipo de devedor

Cada documento é referenciado pelo seu **identificador** (`file_type`), que deve ser informado no momento de solicitar a URL assinada.

### Pessoa Física (PF)

| Documento                           | Identificador (`file_type`)   |
| ----------------------------------- | ----------------------------- |
| Documento de identificação (RG/CNH) | `debtor_identification_file`  |
| Comprovante de renda                | `debtor_proof_of_income_file` |
| Comprovante de endereço             | `debtor_address_proof_file`   |

### Pessoa Jurídica (PJ)

| Documento                                       | Identificador (`file_type`)                      |
| ----------------------------------------------- | ------------------------------------------------ |
| Contrato social ou estatuto                     | `debtor_social_or_statute_contract`              |
| Comprovante de endereço                         | `debtor_address_proof_file`                      |
| Comprovante de faturamento dos últimos 12 meses | `debtor_monthly_turnover_on_last_12_months_file` |

### Representante Legal (obrigatório para PJ)

| Documento                                   | Identificador (`file_type`)          |
| ------------------------------------------- | ------------------------------------ |
| Documento de identificação do representante | `representative_identification_file` |
| Comprovante de endereço do representante    | `representative_address_proof_file`  |

> 📘 Informação
>
> Os documentos do **representante legal** só se aplicam a devedores do tipo **PJ**. Para devedores **PF**, envie apenas os documentos da seção Pessoa Física.