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

# Campos solicitados

> A funcionalidade de campos solicitados oferece flexibilidade ao permitir a definição de campos específicos a serem incluídos nas respostas das chamadas de API.

Para proporcionar maior flexibilidade na obtenção de dados, a API oferece uma funcionalidade de "campos solicitados", que permite selecionar campos específicos de retorno. Esta característica é especialmente útil ao trabalhar com campos expandidos, permitindo solicitar apenas os subcampos relevantes.

## Pontos importantes

* Na ausência do parâmetro fields, a saída padrão é fornecida.
* Não há limite de profundidade dos campos solicitados.

## Como funciona?

### Selecionando campos

Adicione o parâmetro `fields` à sua solicitação para especificar os campos desejados no retorno. Se estiver trabalhando com campos expandidos usando o parâmetro `expand`, também é possível aplicar a resposta seletiva.

Por exemplo, em uma requisição para buscar informações de um `Loan`, onde a resposta padrão seria:

```shell
curl --request GET \
     --url https://api.dev.base39.io/v1/loans/loan_63ff94f928a4fb05d70b7a17 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ${api-key}'
```

```json
{
  "id": "loan_63ff94f928a4fb05d70b7a17",
  "customer":  "cust_63ff98c128a4fb05d70b7a22",
  "employment": "empl_63ff98cf28a4fb05d70b7a25",
  "company": "comp_63ff55cf28a4fb05d70b7a55",
  "status": "open",
  "offer": {
    "disbursementAmount": 1000,
    "fund": "fund_63ff55cf28a4fb05d70b7aa1",
    "rebates": [
      {
        "feeType": "tac",
        "amountType": "absolute",
        "amount": 200
      },
      {
        "feeType": "registration",
        "amountType": "absolute",
        "amount": 150
      },
      {
        "feeType": "spread",
        "amountType": "absolute",
        "amount": 100
      },
    ]
    ...
  }
  ...
}
```

Por algum motivo, pode ser que o usuário queira somente utilizar os campos `id`, `customer` e `status`. Nesse caso, ao adicionar o `queryParameters` `fields=id,customer,status`, teremos:

```shell
curl --request GET \
     --url 'https://api.dev.base39.io/v1/loans/loan_63ff94f928a4fb05d70b7a17?fields=id,customer,status' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ${api-key}'
```

```json
{
  "id": "loan_63ff94f928a4fb05d70b7a17",
  "customer":  "cust_63ff98c128a4fb05d70b7a22"
  "status": "open",
}
```

### Campos aninhados

Você pode solicitar subcampos de campos expandidos. Utilize o ponto `.` para navegar entre subdocumentos.

Por exemplo, se quisermos somente os campos `id`, `offer.disbursementAmount` e `offer.fund`, adicionamos ao `queryParameters` a propriedade `fields=id,offer.disbursementAmount,offer.fund`. Note que foi utilizado o `.` para navegar entre subdocumentos.

```shell
curl --request GET \
     --url 'https://api.dev.base39.io/v1/loans/loan_63ff94f928a4fb05d70b7a17?fields=id,offer.disbursementAmount,offer.fund' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ${api-key}'
```

```json
{
  "id": "loan_63ff94f928a4fb05d70b7a17",
  "offer": {
    "disbursementAmount": 1000,
    "fund": "fund_63ff55cf28a4fb05d70b7aa1"
  }
}
```

### Campos em lista

É possível selecionar uma propriedade comum entre os subdocumentos de uma lista. Por exemplo, para selecionar somente os campos `id` do `loan`, e os campos `amount` e `feeType` contidos em `offer.rebates`, basta adicionar ao `queryParameters` a propriedade `fields=id,offer.rebates.feeType,offer.rebates.amount`.

```shell
curl --request GET \
     --url 'https://api.dev.base39.io/v1/loans/loan_63ff94f928a4fb05d70b7a17?fields=id,offer.rebates.feeType,offer.rebates.amount' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ${api-key}'
```

```json
{
  "id": "loan_63ff94f928a4fb05d70b7a17",
  "offer": {
    "rebates": [
      {
        "feeType": "tac",
        "amount": 200
      },
      {
        "feeType": "registration",
        "amount": 150
      },
      {
        "feeType": "spread",
        "amount": 100
      },
    ]
  }
}
```

Note que, como `rebates` é uma lista de `rebate`, então o recurso (campos solicitados) faz uma busca do campo em todos os subdocumentos dessa lista.

### Campos expandidos

A funcionalidade "campos solicitados" também possibilita a seleção de campos específicos após a realização de uma expansão de dados.

Por exemplo, suponhamos que haja uma solicitação que expanda o atributo `customer` dentro de um `Loan`:

```shell
curl --request GET \
     --url 'https://api.dev.base39.io/v1/loans/loan_63ff94f928a4fb05d70b7a17?expand=customer' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ${api-key}'
```

```json
{
  "id": "loan_63ff94f928a4fb05d70b7a17",
  "customer":  {
    "id": "cust_63ff98c128a4fb05d70b7a22",
    "name": "João",
    "username": "joao",
    ...
  }
  "employment": "empl_63ff98cf28a4fb05d70b7a25",
  "company": "comp_63ff55cf28a4fb05d70b7a55",
  "status": "open",
  "offer": {
    "disbursementAmount": 1000,
    "fund": "fund_63ff55cf28a4fb05d70b7aa1",
    "rebates": [
      {
        "feeType": "tac",
        "amountType": "absolute",
        "amount": 200
      },
      {
        "feeType": "registration",
        "amountType": "absolute",
        "amount": 150
      },
      {
        "feeType": "spread",
        "amountType": "absolute",
        "amount": 100
      },
    ]
    ...
  }
  ...
}
```

Esta é a resposta padrão para um campo expandido. No entanto, caso deseje obter somente os campos `id` e `name` do customer, você pode incluir ao `queryParameters` a instrução `fields=id,customer.id,customer.nome`.

```shell
curl --request GET \
     --url 'https://api.dev.base39.io/v1/loans/loan_63ff94f928a4fb05d70b7a17?expand=customer,employment&fields=id,customer.id,customer.nome' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ${api-key}'
```

```json
{
  "id": "loan_63ff94f928a4fb05d70b7a17",
  "customer": {
    "id": "cust_63ff98c128a4fb05d70b7a22",
    "name": "João",
  }
}
```