Procurando a documentação anterior?Acesse v1.docs.pluggy.ai
PluggyDocs

Conceitos Básicos

URL base, transporte, convenções de solicitação e resposta, e como os endpoints paginados são lidos.

Ver como Markdown

URL Base#

Um ambiente. Teste contra os conectores 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çãoAPI. 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:

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 ErroAPI.

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.

CampoSignificado
resultsOs registros desta página.
nextA 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:

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/transactionsAPI e GET /v2/itemsAPI — este último é opt-in 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:

CampoSignificado
totalRegistros que correspondem à solicitação, em todas as páginas.
totalPagesPáginas necessárias para ler todos.
pageA página nesta resposta.
resultsOs 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.

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.

GET /transactions está obsoleto

A página baseada GET /transactionsAPI está obsoleta e disponível apenas até 2026-12-31, conforme anunciado no changelog desde junho de 2026. Mova para GET /v2/transactionsAPI, 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.

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

GET /transactionsGET /v2/transactions
accountIdaccountId (mesmo)
idsids, separados por vírgula, até 500 (mesmo)
from / todateFrom / dateTo
createdAtFromcreatedAtFrom (mesmo; não pode ser combinado com dateFrom)
page / pageSizeafter: siga o valor next de cada resposta até que seja null. Páginas contêm até 500 transações.
billId, type, operationTypeNã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: createdTransactionsLinkAplicaçõ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.

Esta página foi útil?