> For the complete documentation index, see [llms.txt](https://docs.cange.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cange.me/api/cadastros-v2/consultar-linhas-de-um-cadastro.md).

# Consultar linhas de um cadastro

## Consultar linhas de um cadastro

`POST /register/v2/query`

Retorna as linhas de um cadastro de forma paginada, permitindo **escolher os campos** (select), **filtrar**, **ordenar** e **buscar** — tudo através de um único parâmetro `filterSchema`.

A resposta é paginada por **cursor** (não por página/offset), o que mantém a performance mesmo em cadastros com centenas de milhares de linhas.

{% hint style="info" %}
Toda a requisição é escopada pela empresa e pelo usuário do seu token. Você só recebe linhas às quais esse usuário tem acesso.
{% endhint %}

### 1. Autenticação e headers

A API usa um **JWT** no header `Authorization: Bearer <token>`. Veja como obter e renovar seu token na página de [Autenticação](https://docs.cange.me/api/autenticacao).

Toda chamada precisa destes headers:

| Header          | Valor                  | Obrigatório |
| --------------- | ---------------------- | ----------- |
| `Authorization` | `Bearer <token>`       | ✅           |
| `Content-Type`  | `application/json`     | ✅           |
| `Origin`        | `https://app.cange.me` | ✅           |

{% hint style="warning" %}
O header `Origin: https://app.cange.me` é **obrigatório em todas as chamadas**. A API só aceita origens da allowlist — uma requisição com `Origin` diferente é bloqueada por CORS.
{% endhint %}

### 2. A requisição

```
POST /register/v2/query
Authorization: Bearer <token>
Content-Type: application/json
Origin: https://app.cange.me
```

| Campo          | Tipo          | Obrigatório | Descrição                                                  |
| -------------- | ------------- | ----------- | ---------------------------------------------------------- |
| `id_register`  | integer       | ✅           | ID do cadastro.                                            |
| `filterSchema` | string (JSON) | —           | Select, filtros, ordenação e busca (ver abaixo).           |
| `page_size`    | integer       | —           | Linhas por página. Padrão `50`, máximo `200`.              |
| `cursor`       | string        | —           | Cursor da próxima página (vem em `page_info.next_cursor`). |

Chamada mínima (sem `filterSchema`) — retorna as primeiras linhas com as colunas de sistema:

```bash
curl -X POST https://api.cange.me/register/v2/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Origin: https://app.cange.me" \
  -d '{ "id_register": 183, "page_size": 20 }'
```

### 3. O `filterSchema`

O `filterSchema` é uma **string JSON** com quatro blocos, todos opcionais:

```json
{
  "fieldView":  [ /* quais campos retornar (SELECT) */ ],
  "conditions": [ /* filtros (combinados com E) */ ],
  "orderBy":    [ /* ordenação */ ],
  "searchText": "texto de busca livre"
}
```

#### Descobrindo os campos do cadastro

Para montar `fieldView`, `conditions` e `orderBy` você precisa do `id_field`, do `form_id` e do `type` de cada campo. Busque a estrutura do cadastro:

```bash
curl "https://api.cange.me/register/v2/?id_register=183" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Origin: https://app.cange.me"
```

O `form.id_form` é o `form_id`; cada item de `form.fields[]` traz `id_field` e `type`.

#### `fieldView` — escolher os campos (SELECT)

Cada item precisa dos **três** identificadores:

```json
{ "id_field": 9803, "form_id": 2957, "type": "TEXT_SHORT_FIELD" }
```

{% hint style="warning" %}
Se você omitir `form_id` (ou `type`), o campo é **silenciosamente ignorado** e não volta na resposta. Se `fieldView` estiver vazio, a resposta traz **apenas as colunas de sistema** (sem os campos do cadastro).
{% endhint %}

Campos de sistema usam IDs negativos: `-1` = data de criação, `-2` = usuário criador, `-3` = ID da linha.

#### `conditions` — filtrar

Filtros são combinados com **E**. Cada condição:

```json
{
  "selectedField": { "id_field": 9803, "form_id": 2957, "type": "TEXT_SHORT_FIELD" },
  "selectedComparator": "Contém",
  "value": "construtora"
}
```

#### `orderBy` — ordenar

```json
{
  "selectedField": { "id_field": 9803, "type": "TEXT_SHORT_FIELD" },
  "selectedOrder": "A → Z"
}
```

Direções por tipo: texto `"A → Z"` / `"Z → A"`; número `"1 → 9"` / `"9 → 1"`; booleano `"Verdadeiro → Falso"` / `"Falso → Verdadeiro"`; datas do mais novo/antigo.

### 4. Comparadores

`selectedComparator` aceita tanto o rótulo em português quanto o **operador SQL** equivalente:

| Rótulo                                   | SQL                       | Observação                   |
| ---------------------------------------- | ------------------------- | ---------------------------- |
| `Igual a`                                | `=`                       |                              |
| `Não é igual a`                          | `!=`                      |                              |
| `Contém`                                 | `LIKE`                    | busca parcial                |
| `Não contém`                             | `NOT LIKE`                |                              |
| `Semelhante a`                           | fulltext                  | busca por similaridade       |
| `Maior que` / `Menor que`                | `>` / `<`                 |                              |
| `Igual a ou maior que` / `... menor que` | `>=` / `<=`               |                              |
| `Está em branco` / `Não está em branco`  | `IS NULL` / `IS NOT NULL` | ignora `value`               |
| `É uma das` / `Não é uma das`            | `IN` / `NOT IN`           | `value` separado por vírgula |
| `Antes de` / `Depois de`                 | `<` / `>`                 | datas                        |

### 5. Exemplos

**Selecionar campos específicos:**

```bash
curl -X POST https://api.cange.me/register/v2/query \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Origin: https://app.cange.me" \
  -d '{
    "id_register": 183,
    "page_size": 20,
    "filterSchema": "{\"fieldView\":[{\"id_field\":-3},{\"id_field\":9803,\"form_id\":2957,\"type\":\"TEXT_SHORT_FIELD\"},{\"id_field\":36776,\"form_id\":2957,\"type\":\"COMBO_BOX_FIELD\"}]}"
  }'
```

**Filtrar + ordenar:**

```bash
curl -X POST https://api.cange.me/register/v2/query \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Origin: https://app.cange.me" \
  -d '{
    "id_register": 183,
    "filterSchema": "{\"conditions\":[{\"selectedField\":{\"id_field\":9803,\"form_id\":2957,\"type\":\"TEXT_SHORT_FIELD\"},\"selectedComparator\":\"Contém\",\"value\":\"construtora\"}],\"orderBy\":[{\"selectedField\":{\"id_field\":9803,\"type\":\"TEXT_SHORT_FIELD\"},\"selectedOrder\":\"A → Z\"}]}"
  }'
```

**Próxima página (cursor):**

```bash
curl -X POST https://api.cange.me/register/v2/query \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Origin: https://app.cange.me" \
  -d '{ "id_register": 183, "page_size": 20, "cursor": "eyJzb3J0X3Zh..." }'
```

### 6. Formato da resposta

```json
{
  "items": [
    {
      "form_answer.id_form_answer": 6507,
      "form_answer.register_id": 183,
      "form_answer.dt_created": "2023-04-06T22:16:01.000Z",
      "form_answer.user_id_creator": 76,
      "field:9803": {
        "value": "Empresa Exemplo LTDA",
        "display_value": "Empresa Exemplo LTDA",
        "value_number": null,
        "value_date": null,
        "value_bool": null,
        "related_id": null
      }
    }
  ],
  "page_info": { "next_cursor": "eyJzb3J0X3Zh...", "has_more": true },
  "execution_stats": { "plan": "large", "cached": false, "duration_ms": 24, "total_count": 316 }
}
```

Cada linha traz as **colunas de sistema** (`form_answer.*`) e um objeto **`field:<id_field>`** por campo selecionado:

* `value` — valor bruto; `display_value` — valor exibível (rótulo de combo, etc.).
* `value_number` / `value_date` / `value_bool` — valor tipado quando aplicável.
* `related_id` — para campos que referenciam outro cadastro/fluxo.

Continue paginando enquanto `page_info.has_more` for `true`, passando `page_info.next_cursor` na próxima chamada.