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.
| 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:
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:
| 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 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 /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.
