# Conceitos Básicos

## URL Base

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

Um ambiente. Teste contra os [conectores do 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 — 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 `null` `next` 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, clientes de pagamento, destinatários e solicitações, e pré-autorização de Smart Transfer 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 que correspondem à 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 o aceita — verifique o endpoint). Para ler tudo, solicite `page=1`, depois `page=2` … até `totalPages`.

Cada endpoint de lista fora do `v2` pagina 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 local de chamada.

<Callout variant="warning" title="GET /transactions está obsoleto">
A página baseada [`GET /transactions`](/reference/transaction/transactions-list) está disponível apenas até **2026-12-31**. Mova para [`GET /v2/transactions`](/reference/transaction/transactions-list-by-cursor), que pagina por cursor como acima.
</Callout>

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