URL Base#
Um ambiente. Teste contra os conectores do 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 — 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 null next 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 é 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:
| 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.
GET /transactions está obsoleto
A página baseada GET /transactionsAPI está disponível apenas até 2026-12-31. Mova para GET /v2/transactionsAPI, que pagina por cursor como acima.
Leia o guia: Conceitos básicos.