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

<Callout variant="info" title="Apenas Open Finance">
Apenas instituições de Open Finance relatam uma lista de recursos. Um item em um conector direto 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 relata sobre este recurso. |

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

| Status | O que significa | Quem age |
| :-- | :-- | :-- |
| `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 informa que não está disponível. | O usuário final, ou ninguém — a instituição decide. |
| `TEMPORARILY_UNAVAILABLE` | A instituição informa que está 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 usa |
| `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.

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

| Valor | O que significa |
| :-- | :-- |
| `true` | A instituição declara pelo menos um recurso `PENDING_AUTHORISATION`. |
| `false` | A lista foi lida e nada nela está pendente. |
| `null` | A lista ainda não foi lida (`resourcesCollectedAt` é `null`), por exemplo, enquanto a primeira execução do item ainda está em andamento. Sempre `null` para conectores que não sejam Open Finance. |

<Callout variant="info" title="Quando ler">
A lista é armazenada antes que os webhooks `item/created` e `item/updated` sejam enviados, então ler o
Item quando o webhook chega fornece o valor para essa execução. Lê-la antes, enquanto a
primeira execução ainda está em andamento, e será `null`.
</Callout>

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](/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 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](/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.