Recursos de Item

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 informa que está 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 é nossa responsabilidade.

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 relatou — nada inferido, nada mesclado com nossos próprios dados.

A resposta#

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

{
  "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:

Filtrando por status#

Passe status para obter apenas os recursos em um estado, por exemplo GET /items/{id}/resources?status=PENDING_AUTHORISATION. Valores aceitos: AVAILABLE, PENDING_AUTHORISATION, UNAVAILABLE, TEMPORARILY_UNAVAILABLE. A paginação funciona da mesma forma, e total conta apenas os recursos correspondentes.

Status#

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

Tipos#

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.

Recursos pendentes de autorização#

O hasResourcesPendingAuthorization do Item informa se algo nesta lista está aguardando o usuário, sem precisar paginar por ela. Ele é lido desta mesma lista, então os dois sempre concordam.

Uma maneira típica de lidar com isso:

1. Em item/created ou item/updated, chame GET /items/{id}.
2. Se hasResourcesPendingAuthorization for true, chame GET /items/{id}/resources?status=PENDING_AUTHORISATION para ver quais recursos estão aguardando.
3. Informe ao seu usuário o que ele ainda precisa autorizar no aplicativo do banco — type diz a qual produto cada recurso pertence. Para contas empresariais, isso é frequentemente a aprovação de um segundo signatário.
4. Assim que o usuário os autorizar, a próxima atualização do item traz os dados dele, e o seguinte item/updated chega com hasResourcesPendingAuthorization definido como false.

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 relata 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 ele relatar um erro, o problema é de coleta e para aqui. Avisos INV_002 listam os investimentos ainda pendentes de autorização no banco (até 100), e hasResourcesPendingAuthorization: true diz que algum recurso, em qualquer produto, está aguardando o usuário; o passo 2 tem a lista completa.
2. GET /items/{id}/resources — há tipos de investimento na lista? Adicione ?status=PENDING_AUTHORISATION para ver apenas os que estão aguardando o usuário.
   • 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 deveríamos 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.