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

Recursos de Item

O que a instituição declarou para um consentimento de Open Finance, recurso por recurso — e como diferenciar 'o banco não compartilhou' de 'não coletamos'.

Ver como Markdown

Quando um produto retorna vazio, há duas razões muito diferentes por trás disso, e elas levam a próximos passos opostos:

  • a instituição nunca compartilhou — o consentimento não cobre, o usuário ainda precisa autorizá-lo, ou o banco o reporta como indisponível. O usuário final pode corrigir isso em seu banco;
  • não temos o registro — o consentimento cobre, mas a sincronização não o trouxe. Isso é algo que devemos analisar.

GET /items/{id}/resources responde à primeira. Ele lista os recursos que a instituição financeira declarou para o consentimento deste item, exatamente como a instituição os reportou — nada inferido, nada mesclado com nossos próprios dados.

Open Finance apenas

Apenas instituições de Open Finance reportam uma lista de recursos. Um item em um direct connector retorna uma página vazia em vez de um erro, então é seguro chamar para qualquer item.

A resposta#

O endpoint é paginado (page, pageSize, padrão 500 por página):

json
{
  "page": 1,
  "total": 3,
  "totalPages": 1,
  "results": [
    { "resourceId": "92792126-fa1e-4e1c-a2b2-5b7b0d4a0b11", "type": "ACCOUNT", "status": "AVAILABLE" },
    { "resourceId": "0d1e2f34-55aa-4b0c-9f3d-77c1a0e2b345", "type": "CREDIT_CARD_ACCOUNT", "status": "PENDING_AUTHORISATION" },
    { "resourceId": "5f6a7b89-1122-4c33-8d44-99e0f1a2b3c4", "type": "FUND", "status": "UNAVAILABLE" }
  ]
}

Cada entrada tem três campos:

CampoO que é
resourceIdO identificador da instituição para o recurso. Ele corresponde ao providerId da conta, cartão de crédito, empréstimo ou investimento correspondente — não é um id da Pluggy.
typeO tipo de recurso de Open Finance, conforme declarado.
statusO que a instituição reporta sobre este recurso.

Status#

StatusO que significaQuem atua
AVAILABLEA instituição compartilha este recurso sob o consentimento.Ninguém — se os dados ainda estiverem faltando, é uma questão de coleta, não de consentimento.
PENDING_AUTHORISATIONO consentimento abrange este recurso, mas o usuário ainda não o autorizou em sua instituição.O usuário final, no aplicativo do banco.
UNAVAILABLEA instituição reporta como não disponível.O usuário final, ou ninguém — a instituição decide.
TEMPORARILY_UNAVAILABLEA instituição reporta como indisponível por enquanto.Tente novamente mais tarde.

PENDING_AUTHORISATION mantém a grafia britânica de Open Finance. É da regulamentação, não um erro de digitação.

Tipos#

TipoProduto ao qual pertence
ACCOUNTContas
CREDIT_CARD_ACCOUNTCartões de crédito
LOAN, FINANCING, INVOICE_FINANCING, UNARRANGED_ACCOUNT_OVERDRAFTEmpréstimos — as mesmas quatro famílias que o kind do Empréstimo utiliza
BANK_FIXED_INCOME, CREDIT_FIXED_INCOME, VARIABLE_INCOME, TREASURE_TITLE, FUNDInvestimentos

Quão atualizada está a lista#

A lista é um instantâneo da última execução que realmente alcançou a instituição, então pode ser mais antiga que o próprio item. O resourcesCollectedAt do Item diz quando foi coletada.

Esse campo também é o que torna uma lista vazia legível:

  • resourcesCollectedAt definido, lista vazia → a instituição não compartilhou nada sob este consentimento;
  • resourcesCollectedAt null → a lista nunca foi obtida. Uma resposta vazia não diz nada sobre o consentimento.

O que não responde#

Se a Pluggy possui o registro correspondente é uma questão separada. Um recurso pode estar AVAILABLE e ainda não ter dados do nosso lado, e o inverso também acontece — mantemos registros entre execuções, então os dados podem estar lá de uma sincronização anterior de um recurso que a instituição não declara mais.

Para esse lado, use os endpoints de produtos (/accounts, /investments, /loans) e o statusDetail do Item, que reporta os resultados de coleta por produto. Veja Item e Warnings & Status Codes.

Um triagem trabalhada#

Um cliente relata que um item conectado a um banco de Open Finance não retorna investimentos.

  1. GET /items/{id} — o status é UPDATED? O que diz statusDetail.investments? Se reportar um erro, o problema é de coleta e para aqui.
  2. GET /items/{id}/resources — há tipos de investimento na lista?
    • nenhum, e resourcesCollectedAt está definido → a instituição não compartilha investimentos sob este consentimento. Nada a corrigir do nosso lado;
    • presente como PENDING_AUTHORISATION → o usuário precisa autorizar esse recurso em seu banco;
    • presente como AVAILABLE → o consentimento cobre e devemos tê-lo. Isso é uma questão de coleta que vale a pena reportar, com o id do item e o resourceId em mãos.

As tabelas de cobertura por conector respondem a uma pergunta diferente — o que um conector suporta em geral — e vivem em Connectors coverage. Este endpoint responde a um consentimento, conforme a instituição declarou hoje.

Esta página foi útil?