# API Parsers e Exportacao

As APIs dinamicas do FastApp suportam dois fluxos parecidos, mas com usos
diferentes:

- Parsers inline via `$parser` ou `$format`, usados para transformar a resposta
  da listagem em texto tecnico.
- Exportacao de arquivos via endpoint `/export`, usada pela UI para download em
  formatos de escritorio.

## Parsers Inline

Use parsers quando quiser mudar o corpo da resposta da propria listagem.

| Format | Parameter | Content-Type | Description |
| :--- | :--- | :--- | :--- |
| **JSON** | `json` | `application/json` | Default format. Returns full envelope (`data`, `total`, etc). |
| **CSV** | `csv` | `text/csv` | Returns raw records as a CSV table. |
| **YAML** | `yaml` | `text/yaml` | Returns raw records in YAML format. |
| **Markdown** | `markdown`, `md` | `text/markdown` | Returns GitHub-flavored markdown tables. |

Examples:

```http
GET /api/v1/data/app/lead?$parser=csv
GET /api/v1/data/app/user?$parser=yaml
GET /api/v1/data/app/lead/123?$parser=markdown
```

Parsers continuam funcionando com data sources externos: a resposta externa e
normalizada antes da transformacao.

## Exportacao De Arquivos

Use o endpoint dedicado quando a intencao for baixar arquivo com headers de
download:

```http
GET /api/v1/data/{app}/{object}/export?format=csv
```

Formatos suportados:

| Format | Parameter | Content-Type |
| :--- | :--- | :--- |
| **CSV** | `format=csv` | `text/csv; charset=utf-8` |
| **Excel** | `format=xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
| **PDF** | `format=pdf` | `application/pdf` |
| **JSON** | `format=json` | `application/json; charset=utf-8` |

O endpoint define `Content-Disposition: attachment` e gera filename usando o
template do objeto, por padrao `{app}-{object}-{date}`.

## Escopos

| Scope | Uso |
| :--- | :--- |
| `current_query` | Exporta a consulta filtrada/sortida, ignorando paginacao de tela e respeitando `max_rows`. |
| `current_page` | Exporta apenas a pagina atual com `$limit` e `$skip`. |
| `selected` | Exporta os IDs enviados em `ids=...`. |

Examples:

```http
GET /api/v1/data/task-board/task_item/export?format=xlsx&scope=current_query&status=TODO
GET /api/v1/data/task-board/task_item/export?format=csv&scope=current_page&$limit=25&$skip=50
GET /api/v1/data/task-board/task_item/export?format=pdf&scope=selected&ids=a1,b2,c3
```

O endpoint reaproveita filtros, sort, app hint, RBAC, data sources externos,
relacoes e campos computed do contrato dinamico de listagem.

## Configuracao Por Objeto

Todo objeto nasce exportavel por padrao. Para customizar:

```json
{
  "ui_config": {
    "export": {
      "enabled": true,
      "formats": ["csv", "xlsx", "pdf", "json"],
      "scopes": ["current_query", "current_page", "selected"],
      "max_rows": 5000,
      "include_hidden_fields": false,
      "filename_template": "{app}-{object}-{date}",
      "fields": ["id", "nome", "status"]
    }
  }
}
```

Regras importantes:

- `enabled: false` remove o botao e bloqueia o endpoint para o objeto.
- `formats` restringe o menu e o servidor.
- `scopes` restringe consulta, pagina e selecionados.
- `fields` define as colunas exportadas.
- `include_hidden_fields` permite incluir campos com `show_in_list: false`.
- Propriedades com `exportable: false` nunca entram na exportacao.

## UI

O botao de exportacao fica em `CoreExportDataButton` e e usado por:

- `CoreDynamicCRUD`, cobrindo tabela, lista, kanban, agenda, mapa e views
  hibridas.
- CMS object views como `object_table`, `object_list`, `object_list_simple`,
  `object_list_integrated`, `object_kanban` e `object_schedule`.

## Limites

- `max_rows` default: `5000`.
- PDF limita a tabela renderizada as primeiras colunas para manter legibilidade.
- Exportacao massiva/assincrona, relatorios customizados e envio agendado por
  email ficam fora desta sprint.