PluggyDocs

Conceitos básicos

Protocolos de segurança, convenções de API, ambiente, identificadores de solicitação e paginação usados pela Pluggy API.

Ver como Markdown

Protocolos de segurança#

A API da Pluggy exige o uso de HTTPS TLSv1.2 ou versões superiores por razões de segurança. Outros pedidos de versões TLS serão rejeitados. Toda comunicação deve ser feita em HTTPS.

Verbos da API e Protocolos#

A API da Pluggy é uma API RESTful baseada em solicitações e respostas JSON, portanto, todas as solicitações devem ter o cabeçalho Content-Type definido como application/json.

Seguimos os padrões RESTful e todos os verbos correspondem à sua ação específica para o recurso com o qual você estará se comunicando.

Campos de resposta da API

Evoluímos nossa API de uma maneira não destrutiva, adicionando novos campos às respostas de nossos endpoints. Isso torna mais simples, uma vez que não há mecanismos complicados de versionamento, mas também significa que seu cliente HTTP deve suportar o recebimento de campos desconhecidos em uma resposta e ignorá-los. Na maioria das bibliotecas, isso é suportado por padrão, mas, por favor, revise seu caso particular para verificar se isso está configurado corretamente.

Ambiente#

Nosso ambiente de produção está aceitando solicitações no seguinte host:

https://api.pluggy.ai

IDs de Solicitação#

Cada resposta da API da Pluggy carrega um cabeçalho x-request-id — um UUID identificando aquela única solicitação:

x-request-id: 079482e5-8aa4-4708-9aaa-43c2f2792b4a

Está presente em cada resposta, bem-sucedida ou não, e é o único valor que nos permite encontrar sua solicitação exata em nossos logs. Lê-lo não custa nada:

bash
curl -i https://api.pluggy.ai/connectors \
  -H 'X-API-KEY: YOUR_API_KEY' | grep -i x-request-id

Registre-o junto com seus próprios erros. Quando algo falha — um 4xx que você não esperava, uma solicitação que expirou, uma resposta cujo conteúdo parece errado — nos envie o x-request-id com seu relatório. Sem ele, procuramos por item, por janela de tempo e por endpoint e frequentemente encontramos vários candidatos; com ele, vamos direto para a solicitação que você viu, o que geralmente faz a diferença entre uma resposta no mesmo dia e uma conversa que se estende por vários dias.

Paginação#

Algumas respostas da Pluggy podem gerar uma grande quantidade de dados, em cujos casos o tamanho da resposta é limitado e dividido em páginas.

Por exemplo, se você fizer uma solicitação para /transaction?accountId={ACCOUNT_ID}, você receberá um objeto como:

json
{
  "total": 200,
  "totalPages": 15,
  "results": [],
  "page": 1
}
  • total: o tamanho dos dados da solicitação
  • totalPages: o número total de páginas abrangendo todos os registros disponíveis
  • results: o conteúdo da página atual
  • page: o número da página atual

Por exemplo, /transaction?accountId={ACCOUNT_ID}&page=2 é a segunda página dos resultados das transações.

Ao recuperar /transaction?accountId={ACCOUNT_ID}, depois /transaction?accountId={ACCOUNT_ID}&page=2, e assim por diante, você pode acessar todos os dados disponíveis, uma página de cada vez.

Resumindo, para obter todos os dados de um endpoint paginado, após sua primeira solicitação, você deve iterar tantas vezes quanto totalPages, fazendo uma nova solicitação e alterando o parâmetro de consulta page.

Esta página foi útil?