# 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 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.

<Callout variant="info" title="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.
</Callout>

## 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:

| Campo | O que é |
| :-- | :-- |
| `resourceId` | O **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. |
| `type` | O tipo de recurso de Open Finance, conforme declarado. |
| `status` | O que a instituição reporta sobre este recurso. |

## Status

| Status | O que significa | Quem atua |
| :-- | :-- | :-- |
| `AVAILABLE` | A 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_AUTHORISATION` | O 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. |
| `UNAVAILABLE` | A instituição reporta como não disponível. | O usuário final, ou ninguém — a instituição decide. |
| `TEMPORARILY_UNAVAILABLE` | A 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

| Tipo | Produto ao qual pertence |
| :-- | :-- |
| `ACCOUNT` | Contas |
| `CREDIT_CARD_ACCOUNT` | Cartões de crédito |
| `LOAN`, `FINANCING`, `INVOICE_FINANCING`, `UNARRANGED_ACCOUNT_OVERDRAFT` | Empréstimos — as mesmas quatro famílias que o [`kind`](/docs/products/loans) do Empréstimo utiliza |
| `BANK_FIXED_INCOME`, `CREDIT_FIXED_INCOME`, `VARIABLE_INCOME`, `TREASURE_TITLE`, `FUND` | Investimentos |

## 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](/docs/connections/item) e [Warnings & Status Codes](/docs/connections/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](/docs/connections/reporting-issues), 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](/docs/connections/connectors-coverage). Este endpoint responde a
**um** consentimento, conforme a instituição declarou hoje.