# Cobrança — Beneficiários (UY3)

> 4 endpoints. Placeholders: `{{baseUrl}}` e `{{token}}`.

## Autenticação

Envie o token em toda requisição no header `Authorization: Bearer {{token}}` (JWT do AWS Cognito). Integrações servidor-a-servidor podem usar `X-Api-Key`. Todo tráfego é HTTPS; a credencial nunca vai na URL nem em query string.

## Beneficiários

Beneficiários que recebem os valores das cobranças.

### GET /api/v1/Beneficiary

**Método de visualização da lista de beneficiarios/cedentes** — Lista e filtra registros de api.

Método de visualização da lista de beneficiarios/cedentes.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|---|---|
| `RegistrationNumber` | query | `string` | opcional | — | `valor` |
| `WalletCode` | query | `integer` | opcional | — | `10` |
| `Page` | query | `integer` | opcional | — | `10` |
| `Size` | query | `integer` | opcional | — | `10` |

**Resposta 200**

Campos:

| Campo | Tipo | Obrigatório | Descrição | Valores | Exemplo |
|---|---|---|---|---|---|
| `data` | `array de objeto` | opcional | — | objeto — ver detalhe abaixo | `[ … ]` |
| `page` | `integer` | opcional | — | — | `0` |
| `totalPages` | `integer` | opcional | — | — | `0` |
| `totalItems` | `integer` | opcional | — | — | `0` |
| `isCountTruncated` | `boolean` | opcional | — | — | `true` |

Detalhe de `data`:

| Campo | Tipo | Obrigatório | Descrição | Valores | Exemplo |
|---|---|---|---|---|---|
| `id` | `string` | opcional | — | — | `"texto"` |
| `beneficiaryCode` | `integer (int64)` | opcional | — | — | `0` |
| `companyName` | `string` | opcional | — | — | `"Fulano de Tal"` |
| `businessName` | `string` | opcional | — | — | `"Fulano de Tal"` |
| `personTypeValue` | `string` | opcional | — | — | `"texto"` |
| `personTypeValueDisplay` | `string` | opcional | — | — | `"texto"` |
| `registrationNumber` | `string` | opcional | — | — | `"12345678909"` |
| `address` | `objeto` | opcional | — | objeto — ver detalhe abaixo | `{ … }` |
| `startedAt` | `string (date-time)` | opcional | — | — | `"2025-08-11T13:45:00Z"` |
| `enabled` | `boolean` | opcional | — | — | `true` |
| `wallets` | `array de objeto` | opcional | — | objeto — ver detalhe abaixo | `[ … ]` |
| `representatives` | `array de objeto` | opcional | — | objeto — ver detalhe abaixo | `[ … ]` |
| `walletsManaged` | `array de integer (int64)` | opcional | — | — | `[ … ]` |

Detalhe de `address`:

| Campo | Tipo | Obrigatório | Descrição | Valores | Exemplo |
|---|---|---|---|---|---|
| `zipCode` | `string` | opcional | — | — | `"01310930"` |
| `addressName` | `string` | opcional | — | — | `"Fulano de Tal"` |
| `number` | `string` | opcional | — | — | `"texto"` |
| `complement` | `string` | opcional | — | — | `"texto"` |
| `district` | `string` | opcional | — | — | `"texto"` |
| `city` | `string` | opcional | — | — | `"texto"` |
| `uf` | `string` | opcional | — | — | `"texto"` |

Detalhe de `wallets`:

| Campo | Tipo | Obrigatório | Descrição | Valores | Exemplo |
|---|---|---|---|---|---|
| `id` | `string` | opcional | — | — | `"texto"` |
| `beneficiaryId` | `string` | opcional | — | — | `"3fa85f64-5717-4562-b3fc-2c963f66afa6"` |
| `beneficiaryName` | `string` | opcional | — | — | `"Fulano de Tal"` |
| `walletCode` | `integer (int64)` | opcional | — | — | `0` |
| `bankAgency` | `string` | opcional | — | — | `"texto"` |
| `bankAccount` | `string` | opcional | — | — | `"texto"` |
| `bankAccountDebtCosts` | `string` | opcional | — | — | `"texto"` |
| `bankSlipCosts` | `objeto` | opcional | — | objeto — ver detalhe abaixo | `{ … }` |
| `billingTypeValue` | `string` | opcional | — | — | `"texto"` |
| `billingTypeValueDisplay` | `string` | opcional | — | — | `"texto"` |
| `daysOverdueLimit` | `integer (int64)` | opcional | — | — | `0` |
| `interestCodeValue` | `string` | opcional | — | — | `"texto"` |
| `interestCodeValueDisplay` | `string` | opcional | — | — | `"texto"` |
| `notificationRecepients` | `array de string` | opcional | — | — | `[ … ]` |
| `createdAt` | `string (date-time)` | opcional | — | — | `"2025-08-11T13:45:00Z"` |
| `enabled` | `boolean` | opcional | — | — | `true` |
| `enableAutoSubmitToDebtCollection` | `boolean` | opcional | — | — | `true` |

Detalhe de `representatives`:

| Campo | Tipo | Obrigatório | Descrição | Valores | Exemplo |
|---|---|---|---|---|---|
| `personTypeValue` | `string` | opcional | — | — | `"texto"` |
| `personTypeValueDisplay` | `string` | opcional | — | — | `"texto"` |
| `registrationNumber` | `string` | opcional | — | — | `"12345678909"` |

Detalhe de `bankSlipCosts`:

| Campo | Tipo | Obrigatório | Descrição | Valores | Exemplo |
|---|---|---|---|---|---|
| `register` | `integer (int64)` | opcional | — | — | `0` |
| `cancellation` | `integer (int64)` | opcional | — | — | `0` |
| `discount` | `integer (int64)` | opcional | — | — | `0` |
| `changeDueDate` | `integer (int64)` | opcional | — | — | `0` |
| `settlement` | `integer (int64)` | opcional | — | — | `0` |
| `debtCollection` | `integer (int64)` | opcional | — | — | `0` |
| `debtCollectionCancellation` | `integer (int64)` | opcional | — | — | `0` |
| `debtCollectionSettlement` | `integer (int64)` | opcional | — | — | `0` |
| `debtCollectionSuccess` | `integer (int64)` | opcional | — | — | `0` |
| `transferRegister` | `integer (int64)` | opcional | — | — | `0` |
| `transferCancellation` | `integer (int64)` | opcional | — | — | `0` |
| `overDueCancellation` | `integer (int64)` | opcional | — | — | `0` |

Exemplo:

```json
{
  "data": [
    {
      "id": "texto",
      "beneficiaryCode": 0,
      "companyName": "Fulano de Tal",
      "businessName": "Fulano de Tal",
      "personTypeValue": "texto",
      "personTypeValueDisplay": "texto",
      "registrationNumber": "12345678909",
      "address": {
        "zipCode": "01310930",
        "addressName": "Fulano de Tal",
        "number": "texto",
        "complement": "texto",
        "district": "texto",
        "city": "texto",
        "uf": "texto"
      },
      "startedAt": "2025-08-11T13:45:00Z",
      "enabled": true,
      "wallets": [
        {}
      ],
      "representatives": [
        {}
      ],
      "walletsManaged": [
        0
      ]
    }
  ],
  "page": 0,
  "totalPages": 0,
  "totalItems": 0,
  "isCountTruncated": true
}
```

**Códigos de retorno**

| Código | Significado |
|---|---|
| `200` | Requisição bem-sucedida. |

**cURL**

```bash
curl -X GET "{{baseUrl}}/api/v1/Beneficiary" \
  -H "Authorization: Bearer {{token}}"
```

---

### GET /api/v1/Beneficiary/{beneficiaryId}

**Método de visualização de um beneficiarios/cedentes específico** — Consulta api pelo identificador informado na rota.

Método de visualização de um beneficiarios/cedentes específico.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|---|---|
| `beneficiaryId` | path | `string` | obrigatório | Id do beneficiário/cedente | `3fa85f64-5717-4562-b3fc-2c963f66afa6` |

**Resposta 200**

Campos:

| Campo | Tipo | Obrigatório | Descrição | Valores | Exemplo |
|---|---|---|---|---|---|
| `id` | `string` | opcional | — | — | `"texto"` |
| `beneficiaryCode` | `integer (int64)` | opcional | — | — | `0` |
| `companyName` | `string` | opcional | — | — | `"Fulano de Tal"` |
| `businessName` | `string` | opcional | — | — | `"Fulano de Tal"` |
| `personTypeValue` | `string` | opcional | — | — | `"texto"` |
| `personTypeValueDisplay` | `string` | opcional | — | — | `"texto"` |
| `registrationNumber` | `string` | opcional | — | — | `"12345678909"` |
| `address` | `objeto` | opcional | — | objeto — ver detalhe abaixo | `{ … }` |
| `startedAt` | `string (date-time)` | opcional | — | — | `"2025-08-11T13:45:00Z"` |
| `enabled` | `boolean` | opcional | — | — | `true` |
| `wallets` | `array de objeto` | opcional | — | objeto — ver detalhe abaixo | `[ … ]` |
| `representatives` | `array de objeto` | opcional | — | objeto — ver detalhe abaixo | `[ … ]` |
| `walletsManaged` | `array de integer (int64)` | opcional | — | — | `[ … ]` |

Detalhe de `address`:

| Campo | Tipo | Obrigatório | Descrição | Valores | Exemplo |
|---|---|---|---|---|---|
| `zipCode` | `string` | opcional | — | — | `"01310930"` |
| `addressName` | `string` | opcional | — | — | `"Fulano de Tal"` |
| `number` | `string` | opcional | — | — | `"texto"` |
| `complement` | `string` | opcional | — | — | `"texto"` |
| `district` | `string` | opcional | — | — | `"texto"` |
| `city` | `string` | opcional | — | — | `"texto"` |
| `uf` | `string` | opcional | — | — | `"texto"` |

Detalhe de `wallets`:

| Campo | Tipo | Obrigatório | Descrição | Valores | Exemplo |
|---|---|---|---|---|---|
| `id` | `string` | opcional | — | — | `"texto"` |
| `beneficiaryId` | `string` | opcional | — | — | `"3fa85f64-5717-4562-b3fc-2c963f66afa6"` |
| `beneficiaryName` | `string` | opcional | — | — | `"Fulano de Tal"` |
| `walletCode` | `integer (int64)` | opcional | — | — | `0` |
| `bankAgency` | `string` | opcional | — | — | `"texto"` |
| `bankAccount` | `string` | opcional | — | — | `"texto"` |
| `bankAccountDebtCosts` | `string` | opcional | — | — | `"texto"` |
| `bankSlipCosts` | `objeto` | opcional | — | objeto — ver detalhe abaixo | `{ … }` |
| `billingTypeValue` | `string` | opcional | — | — | `"texto"` |
| `billingTypeValueDisplay` | `string` | opcional | — | — | `"texto"` |
| `daysOverdueLimit` | `integer (int64)` | opcional | — | — | `0` |
| `interestCodeValue` | `string` | opcional | — | — | `"texto"` |
| `interestCodeValueDisplay` | `string` | opcional | — | — | `"texto"` |
| `notificationRecepients` | `array de string` | opcional | — | — | `[ … ]` |
| `createdAt` | `string (date-time)` | opcional | — | — | `"2025-08-11T13:45:00Z"` |
| `enabled` | `boolean` | opcional | — | — | `true` |
| `enableAutoSubmitToDebtCollection` | `boolean` | opcional | — | — | `true` |

Detalhe de `representatives`:

| Campo | Tipo | Obrigatório | Descrição | Valores | Exemplo |
|---|---|---|---|---|---|
| `personTypeValue` | `string` | opcional | — | — | `"texto"` |
| `personTypeValueDisplay` | `string` | opcional | — | — | `"texto"` |
| `registrationNumber` | `string` | opcional | — | — | `"12345678909"` |

Detalhe de `bankSlipCosts`:

| Campo | Tipo | Obrigatório | Descrição | Valores | Exemplo |
|---|---|---|---|---|---|
| `register` | `integer (int64)` | opcional | — | — | `0` |
| `cancellation` | `integer (int64)` | opcional | — | — | `0` |
| `discount` | `integer (int64)` | opcional | — | — | `0` |
| `changeDueDate` | `integer (int64)` | opcional | — | — | `0` |
| `settlement` | `integer (int64)` | opcional | — | — | `0` |
| `debtCollection` | `integer (int64)` | opcional | — | — | `0` |
| `debtCollectionCancellation` | `integer (int64)` | opcional | — | — | `0` |
| `debtCollectionSettlement` | `integer (int64)` | opcional | — | — | `0` |
| `debtCollectionSuccess` | `integer (int64)` | opcional | — | — | `0` |
| `transferRegister` | `integer (int64)` | opcional | — | — | `0` |
| `transferCancellation` | `integer (int64)` | opcional | — | — | `0` |
| `overDueCancellation` | `integer (int64)` | opcional | — | — | `0` |

Exemplo:

```json
{
  "id": "texto",
  "beneficiaryCode": 0,
  "companyName": "Fulano de Tal",
  "businessName": "Fulano de Tal",
  "personTypeValue": "texto",
  "personTypeValueDisplay": "texto",
  "registrationNumber": "12345678909",
  "address": {
    "zipCode": "01310930",
    "addressName": "Fulano de Tal",
    "number": "texto",
    "complement": "texto",
    "district": "texto",
    "city": "texto",
    "uf": "texto"
  },
  "startedAt": "2025-08-11T13:45:00Z",
  "enabled": true,
  "wallets": [
    {
      "id": "texto",
      "beneficiaryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "beneficiaryName": "Fulano de Tal",
      "walletCode": 0,
      "bankAgency": "texto",
      "bankAccount": "texto",
      "bankAccountDebtCosts": "texto",
      "bankSlipCosts": {
        "register": 0,
        "cancellation": 0,
        "discount": 0,
        "changeDueDate": 0,
        "settlement": 0,
        "debtCollection": 0,
        "debtCollectionCancellation": 0,
        "debtCollectionSettlement": 0,
        "debtCollectionSuccess": 0,
        "transferRegister": 0,
        "transferCancellation": 0,
        "overDueCancellation": 0
      },
      "billingTypeValue": "texto",
      "billingTypeValueDisplay": "texto",
      "daysOverdueLimit": 0,
      "interestCodeValue": "texto",
      "interestCodeValueDisplay": "texto",
      "notificationRecepients": [
        "01310930"
      ],
      "createdAt": "2025-08-11T13:45:00Z",
      "enabled": true,
      "enableAutoSubmitToDebtCollection": true
    }
  ],
  "representatives": [
    {
      "personTypeValue": "texto",
      "personTypeValueDisplay": "texto",
      "registrationNumber": "12345678909"
    }
  ],
  "walletsManaged": [
    0
  ]
}
```

**Códigos de retorno**

| Código | Significado |
|---|---|
| `200` | Requisição bem-sucedida. |

**cURL**

```bash
curl -X GET "{{baseUrl}}/api/v1/Beneficiary/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {{token}}"
```

---

### DELETE /api/v1/Beneficiary/{beneficiaryId}

**Método responsável por desabilitar um beneficiario/cedente específico** — Remove um registro de api.

Método responsável por desabilitar um beneficiario/cedente específico.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|---|---|
| `beneficiaryId` | path | `string` | obrigatório | Id do beneficiário/cedente | `3fa85f64-5717-4562-b3fc-2c963f66afa6` |

**Códigos de retorno**

| Código | Significado |
|---|---|
| `200` | Requisição bem-sucedida. |

**cURL**

```bash
curl -X DELETE "{{baseUrl}}/api/v1/Beneficiary/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {{token}}"
```

---

### POST /api/v1/Beneficiary/{beneficiaryId}/Reactivate

**Método responsável por habilitar um beneficiario/cedente específico** — Cria um novo registro de api.

Método responsável por habilitar um beneficiario/cedente específico.

**Parâmetros**

| Nome | Em | Tipo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|---|---|
| `beneficiaryId` | path | `string` | obrigatório | Id do beneficiário/cedente | `3fa85f64-5717-4562-b3fc-2c963f66afa6` |

**Códigos de retorno**

| Código | Significado |
|---|---|
| `200` | Requisição bem-sucedida. |

**cURL**

```bash
curl -X POST "{{baseUrl}}/api/v1/Beneficiary/3fa85f64-5717-4562-b3fc-2c963f66afa6/Reactivate" \
  -H "Authorization: Bearer {{token}}"
```

---