> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rwsintegration.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultando a API do RWS Connect

> Todos os parâmetros que a API do RWS Connect suporta: select, filtros, agrupamento, agregações, ordenação e paginação

A API do RWS Connect expõe suas tabelas do [RWS Connect](/pt-br/core-concepts/rws-connect) como uma API REST. Toda consulta é uma requisição `GET` para `https://connect.rwsintegration.com`, e o que você recupera é controlado inteiramente por query parameters.

Os exemplos desta página usam um tenant fictício `acme` com uma tabela `employees` (colunas `employee_id`, `name`, `department`, `city`, `salary`, `hired_at`, mais as colunas padrão listadas abaixo).

## Configurando a conexão

O RWS Connect usa uma [conexão Simple](/pt-br/features/connections/api#simple) padrão:

| Campo                        | Valor                                   |
| ---------------------------- | --------------------------------------- |
| Nome                         | `RWS Connect`                           |
| Tipo                         | `API`                                   |
| URL                          | `https://connect.rwsintegration.com`    |
| Caminho base (URL base path) | `/`                                     |
| Autenticação                 | `Simple`                                |
| Headers                      | `x-api-key`: a chave fornecida pela RWS |

## Fundamentos da requisição

Dois parâmetros são obrigatórios em toda consulta:

| Parâmetro  | Valor                                                        |
| ---------- | ------------------------------------------------------------ |
| `database` | O nome do seu tenant, fornecido durante o onboarding         |
| `table`    | O nome da tabela, combinado quando o conector foi solicitado |

```
GET https://connect.rwsintegration.com/?database=acme&table=employees
```

A resposta sempre tem o mesmo formato:

```json theme={null}
{
  "Items": [
    {
      "employee_id": "1042",
      "name": "Ana Souza",
      "department": "Sales",
      "city": "Manaus",
      "salary": 4200.0,
      "extracted_at": "2026-07-28 06:00:12.000",
      "extraction_date": "2026-07-28"
    }
  ],
  "Total": 1580
}
```

* **`Items`**: os registros da página solicitada. Na configuração da extração, defina o **Path para o datapoint na resposta** como `Items`.
* **`Total`**: quantos registros correspondem à consulta no total (considerando todas as páginas). Para consultas agrupadas, o número de grupos.

Sem parâmetros de paginação, a consulta retorna os primeiros **20** registros.

## Prefixos de coluna

Um pipeline frequentemente combina vários endpoints ou tabelas de origem em um único dataset. Nesse caso, cada coluna recebe o prefixo da fonte de onde veio, e cada registro chega como um único objeto JSON plano:

```json theme={null}
{
  "employees_employee_id": "1042",
  "employees_name": "Ana Souza",
  "contracts_position": "Sales Analyst",
  "contracts_start_date": "2024-03-01"
}
```

Filtros, selects e todos os outros parâmetros usam o nome completo da coluna com prefixo (por exemplo `filter[contracts_start_date][>=]=2026-01-01`). Os exemplos desta página usam uma tabela de fonte única com colunas sem prefixo para simplificar.

## Selecionando colunas

Projete apenas as colunas que você precisa com `select[coluna]` (valor vazio):

```
?database=acme&table=employees&select[name]=&select[city]=
```

## Filtrando

Filtre com `filter[coluna][operador]=valor`. Omitir o operador significa igualdade:

```
?database=acme&table=employees&filter[city]=Manaus
?database=acme&table=employees&filter[salary][>=]=3000
```

Operadores suportados:

| Operador                 | Significado                                               |
| ------------------------ | --------------------------------------------------------- |
| `=` (padrão), `!=`, `<>` | Igual / diferente                                         |
| `>`, `>=`, `<`, `<=`     | Comparação                                                |
| `in`, `not in`           | Valor em uma lista                                        |
| `between`, `not between` | Valor dentro de um intervalo (dois valores)               |
| `like`, `not like`       | Busca por padrão, `%` como curinga                        |
| `ilike`, `not ilike`     | Busca por padrão sem diferenciar maiúsculas de minúsculas |
| `is`, `is not`           | Comparação de identidade                                  |

Operadores de lista e intervalo recebem valores em array:

```
?database=acme&table=employees&filter[department][in][]=Sales&filter[department][in][]=Finance
?database=acme&table=employees&filter[hired_at][between][]=2026-01-01&filter[hired_at][between][]=2026-06-30
```

Múltiplos filtros combinam com AND:

```
?database=acme&table=employees&filter[city]=Manaus&filter[salary][>=]=3000
```

<Note>
  Ao chamar a API manualmente (por exemplo com `curl`), lembre de fazer URL-encode dos caracteres especiais: `%` em um padrão `like` vira `%25`. Na configuração de extração da plataforma, os valores dos query parameters são codificados automaticamente.
</Note>

### Filtrando por data e hora

Prefixe o nome da coluna com `timestamp_` para comparar como data/hora em vez de texto. O prefixo existe apenas no filtro; a coluna mantém o nome real na resposta:

```
?database=acme&table=employees&filter[timestamp_extracted_at][>=]=2026-07-01
```

É aqui que os [parâmetros dinâmicos](/pt-br/features/extract/dynamic-parameters) brilham. Por exemplo, uma integração diária que lê apenas o snapshot de ontem:

```
filter[timestamp_extraction_date][>=]={{ now.subtract(1, days).format(YYYY-MM-DD) }}
```

## Ordenação

```
?database=acme&table=employees&sort[name]=asc
?database=acme&table=employees&sort[salary]=desc
```

## Paginação

A API pagina com `page[size]` e `page[number]` (começando em 1):

```
?database=acme&table=employees&page[size]=100&page[number]=2
```

Na configuração da sua extração isso mapeia diretamente para a [Paginação Simples](/pt-br/features/extract/pagination):

| Campo                          | Valor          |
| ------------------------------ | -------------- |
| Tipo                           | `Simples`      |
| Parâmetro do tamanho da página | `page[size]`   |
| Valor do tamanho da página     | ex.: `100`     |
| Parâmetro da página            | `page[number]` |
| Valor da página inicial        | `1`            |
| Tipo de fim de paginação       | `Objeto`       |

## Agrupamento e agregações

Agrupe com `group[coluna]` (ou o atalho `select[coluna]=group`, que também retorna a coluna) e agregue com `select[coluna]=<função>`:

```
?database=acme&table=employees&select[city]=group&select[salary]=sum
```

```json theme={null}
{
  "Items": [
    { "city": "Manaus", "salary": 182000.0 },
    { "city": "Belém", "salary": 97000.0 }
  ],
  "Total": 2
}
```

| Agregação      | Significado                          |
| -------------- | ------------------------------------ |
| `sum`          | Soma da coluna por grupo             |
| `sum_distinct` | Soma dos valores distintos por grupo |
| `avg`          | Média por grupo                      |
| `min` / `max`  | Mínimo / máximo por grupo            |
| `count`        | Contagem por grupo                   |

Para consultas agrupadas, `Total` é o número de grupos.

## Registro mais recente por chave

As tabelas do RWS Connect preservam histórico: cada execução do pipeline adiciona um snapshot. O filtro `over_` responde a pergunta mais comum sobre esse tipo de tabela: *"me dê apenas o registro mais recente de cada chave."*

```
?database=acme&table=employees&filter[over_employee_id][extracted_at]=first
```

Isso retorna um registro por `employee_id`: o de maior `extracted_at` (`first` mantém o mais novo, `last` mantém o mais antigo).

A sintaxe é `filter[over_<colunas>][<coluna de ordenação>]=first|last`. Combine colunas de agrupamento com `_and_`:

```
?database=acme&table=employees&filter[over_employee_id_and_department][extracted_at]=first
```

<Warning>
  * Apenas um filtro `over_` é permitido por consulta.
  * `over_` não pode ser combinado com `select`, `group` ou parâmetros de agregação.
  * O registro vencedor de cada chave é escolhido **antes** dos outros filtros serem aplicados. `filter[over_employee_id][extracted_at]=first` mais um filtro de data significa "pegue o registro mais recente de cada funcionário no geral e mantenha apenas se passar no filtro de data", e não "o registro mais recente dentro do intervalo".
</Warning>

### Somas por chave

Para totalizar uma coluna por chave e ainda retornar um registro por chave, use `select[coluna]=sum_over` com `over_group` (obrigatório):

```
?database=acme&table=employees&select[salary]=sum_over&over_group=department
```

## Colunas padrão

Toda tabela do RWS Connect carrega estas colunas, úteis para filtrar snapshots:

| Coluna                         | Significado                                          |
| ------------------------------ | ---------------------------------------------------- |
| `extracted_at`                 | Timestamp de quando o registro foi extraído          |
| `extraction_date`              | Data da execução do pipeline que produziu o registro |
| `extract_start_date_parameter` | Início da janela de datas que a execução extraiu     |
| `extract_end_date_parameter`   | Fim da janela de datas que a execução extraiu        |

## Comportamento e limites

* Resultados de consultas idênticas podem ser servidos de um cache por até **10 minutos**
* O tamanho de página padrão é de **20** registros
* Apenas um filtro de janela `over_` por consulta, e ele não pode ser combinado com `select`, `group` ou agregações

## Próximos passos

<CardGroup cols={2}>
  <Card title="Guia: Extrair dados do RWS Connect" icon="cloud-arrow-down" href="/pt-br/guides/rws-connect">
    Construa uma integração funcional sobre uma tabela do Connect
  </Card>

  <Card title="Parâmetros Dinâmicos" icon="brackets-curly" href="/pt-br/features/extract/dynamic-parameters">
    Injete datas e variáveis nos seus filtros
  </Card>
</CardGroup>