# Conceitos Básicos

## URL Base

```
https://api.pluggy.ai
```

Um ambiente. Teste contra os [conectores Sandbox](/docs/guides/sandbox) em vez de um host separado.

## Transporte

HTTPS com TLS 1.2 ou posterior. Conexões que negociam uma versão TLS mais antiga são rejeitadas.

## Solicitações

REST sobre JSON. Envie `Content-Type: application/json` em cada solicitação com um corpo, e a credencial em `X-API-KEY` — veja [Autenticação](/reference/authentication). Os verbos significam o que dizem: `GET` lê, `POST` cria, `PATCH` atualiza, `DELETE` remove.

## Respostas

JSON. A API evolui sem versões **adicionando** campos às respostas; nada é removido ou renomeado. Seu cliente deve aceitar e ignorar campos que não conhece — a maioria das bibliotecas HTTP faz isso por padrão, um desserializador estrito pode não fazer.

Os erros compartilham uma forma, independentemente do endpoint:

```json
{
  "code": 401,
  "codeDescription": "CLIENT_KEYS_UNAUTHORIZED",
  "message": "As chaves do cliente são inválidas"
}
```

`code` repete o status HTTP; `codeDescription`, quando presente, é o identificador estável para ramificar; `message` é para as pessoas. Alguns erros adicionam um objeto `data`. Os códigos de status estão listados em [Códigos de Erro](/reference/error-codes).

## Paginação

Dois modelos estão em uso. Os endpoints `v2` paginam com um cursor; todos os outros endpoints de lista ainda paginam por número de página.

Os cursores são como esta API pagina a partir de agora, e a paginação por número de página está sendo descontinuada. Onde um endpoint de cursor `v2` existe, escreva sua integração contra ele.

### Cursor (`endpoints v2`)

Peça a primeira página com seus filtros. A resposta carrega os registros e `next`: uma string de consulta pronta para a próxima página.

```http
GET https://api.pluggy.ai/v2/transactions
    ?accountId={ACCOUNT_ID}
X-API-KEY: {apiKey}
```

```json
{
  "results": [],
  "next": "?accountId={ACCOUNT_ID}&after={CURSOR}"
}
```

| Campo | Significado |
| --- | --- |
| `results` | Os registros desta página. |
| `next` | A string de consulta da próxima página, ou `null` na última. |

Para continuar, anexe `next` ao caminho do endpoint exatamente como recebido — ele já carrega seus filtros e o cursor `after`:

```http
GET https://api.pluggy.ai/v2/transactions
    ?accountId={ACCOUNT_ID}
    &after={CURSOR}
X-API-KEY: {apiKey}
```

Nunca construa ou decodifique `after` você mesmo: o valor é opaco e só é válido como retornado. Um `next` `null` significa que não há mais nada para ler. A paginação por cursor está disponível em [`GET /v2/transactions`](/reference/transaction/transactions-list-by-cursor) e [`GET /v2/items`](/reference/items/items-list-by-cursor) — este último é opcional por equipe; peça suporte para habilitá-lo.

### Número da página (outros endpoints de lista)

Investimentos, transações de investimento, contas de cartão de crédito (`GET /bills`), clientes de pagamento, destinatários e solicitações, e pré-autorização de Transferências Inteligentes paginam por página:

```http
GET https://api.pluggy.ai/investments
    ?itemId={ITEM_ID}
    &page=2
    &pageSize=500
X-API-KEY: {apiKey}
```

```json
{
  "total": 200,
  "totalPages": 15,
  "page": 1,
  "results": []
}
```

| Campo | Significado |
| --- | --- |
| `total` | Registros correspondentes à solicitação, em todas as páginas. |
| `totalPages` | Páginas necessárias para ler todos. |
| `page` | A página nesta resposta. |
| `results` | Os registros desta página. |

Dois parâmetros de consulta dirigem isso: `page` (padrão `1`) e `pageSize` (padrão `500` onde o endpoint aceita — verifique o endpoint). Para ler tudo, solicite `page=1`, depois `page=2` … até `totalPages`.

`page` deve ser um inteiro entre 1 e 1.000.000, e `pageSize` um inteiro entre 1 e 500. Não confie que um `pageSize` maior será reduzido para 500: a maioria dos endpoints de lista, incluindo `GET /items`, `GET /consents`, investimentos, contas de cartão de crédito, pagamentos e Transferências Inteligentes, rejeitam. Um valor fora desses intervalos, ou um não numérico ou vazio (`page=0`, `page=abc`, `pageSize=501`, `pageSize=`), retorna `400` com `codeDescription` `INVALID_PARAMETERS`:

```json
{
  "code": 400,
  "codeDescription": "INVALID_PARAMETERS",
  "message": "pageSize não pode ser maior que 500"
}
```

Todos os endpoints de lista fora `v2` paginam dessa forma hoje, e espera-se que esses ganhem equivalentes de cursor. Mantenha a lógica de paginação em um só lugar em sua integração: mover um endpoint é então uma mudança em uma função em vez de em cada ponto de chamada.

<Callout variant="warning" title="GET /transactions está obsoleto">
A página baseada [`GET /transactions`](/reference/transaction/transactions-list) está **obsoleta** e **disponível apenas até 2026-12-31**, conforme anunciado no [changelog](/changelog#2026.06-transition-to-cursor-pagination-on-the-transactions-endpoint) desde junho de 2026. Mova para [`GET /v2/transactions`](/reference/transaction/transactions-list-by-cursor), que pagina por cursor como acima.

Aplicações criadas em ou após **2026-06-02 00:00 horário de Brasília (03:00 UTC)** já recebem `410 Gone` com `codeDescription` `ENDPOINT_DEPRECATED` de `GET /transactions`, e devem usar `/v2` desde o início.
</Callout>

### Mudando de `GET /transactions` para `GET /v2/transactions`

| `GET /transactions` | `GET /v2/transactions` |
| --- | --- |
| `accountId` | `accountId` (mesmo) |
| `ids` | `ids`, separados por vírgula, até 500 (mesmo) |
| `from` / `to` | `dateFrom` / `dateTo` |
| `createdAtFrom` | `createdAtFrom` (mesmo; não pode ser combinado com `dateFrom`) |
| `page` / `pageSize` | `after`: siga o valor `next` de cada resposta até que seja `null`. Páginas contêm até 500 transações. |
| `billId`, `type`, `operationType` | Não disponíveis como filtros. Cada transação ainda carrega esses campos (`billId` dentro de `creditCardMetadata`), então filtre do seu lado. |
| `transactions/created` webhook: `createdTransactionsLink` | Aplicações criadas antes de 2026-06-02 00:00 horário de Brasília (03:00 UTC): use `createdTransactionsLinkV2` do mesmo payload. |

Leia o guia: [Conceitos básicos](/docs/developer-tools/basic-concepts).