API Resources - Recursos Consentidos

Visão Geral

A API Resources permite consultar a lista de recursos financeiros que o cliente compartilhou com a instituição receptora por meio de um consentimento ativo no Open Finance Brasil. Ela retorna o status de cada recurso, considerando tanto o consentimento vinculado quanto a disponibilidade real do recurso na instituição transmissora.

Esta API é o ponto de entrada para descobrir quais produtos do cliente estão disponíveis para consulta, como contas, cartões, investimentos, empréstimos, entre outros, antes de chamar as APIs específicas de cada produto.

Casos de uso

• Descobrir quais contas bancárias do usuário foram compartilhadas no consentimento
• Verificar se um recurso específico está disponível antes de consultá-lo
• Identificar recursos pendentes de autorização em fluxos de alçada dupla

Pré-requisitos

Endpoint

GET /baas/v1/open/dat/resources

Obtém a lista de recursos mantidos pelo cliente na instituição transmissora para os quais ele forneceu consentimento.

Query Parameters

Responses

200 OK - Sucesso

Retorna a lista de recursos consentidos com seus respectivos status.

Headers de resposta:

Body:

{
  "data": [
    {
      "resourceId": "25cac914-d8ae-6789-b215-650a6215820d",
      "type": "ACCOUNT",
      "status": "AVAILABLE"
    },
    {
      "resourceId": "8a1b2c3d-4e5f-6789-abcd-ef0123456789",
      "type": "CREDIT_CARD_ACCOUNT",
      "status": "TEMPORARILY_UNAVAILABLE"
    },
    {
      "resourceId": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
      "type": "LOAN",
      "status": "PENDING_AUTHORISATION"
    }
  ],
  "links": {
    "self": "https://api.banco.com.br/open-banking/resources/v3/resources",
    "first": "https://api.banco.com.br/open-banking/resources/v3/resources?page=1",
    "prev": null,
    "next": "https://api.banco.com.br/open-banking/resources/v3/resources?page=2",
    "last": "https://api.banco.com.br/open-banking/resources/v3/resources?page=3"
  },
  "meta": {
    "requestDateTime": "2021-05-21T08:30:00Z",
    "totalRecords": 75,
    "totalPages": 3
  }
}

Campos de data[]

Restrições do resourceId:

• Mínimo: 1 caractere
• Máximo: 100 caracteres
• Padrão: ^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$

Campos de meta

202 Accepted

A requisição foi recebida e está sendo processada de forma assíncrona. Nenhum body é retornado. Tente novamente após alguns instantes.

Headers de resposta: x-fapi-interaction-id, x-v

Respostas de Erro

Todos os erros seguem a estrutura:

{
  "errors": [
    {
      "code": "CODIGO_DO_ERRO",
      "title": "Título legível do erro",
      "detail": "Descrição detalhada do problema ocorrido."
    }
  ],
  "meta": {
    "requestDateTime": "2021-05-21T08:30:00Z"
  }
}

Tabela de Códigos HTTP de Erro

Tipos de Recurso (type)

Correspondência de resourceId por produto

O resourceId retornado nesta API corresponde diretamente ao identificador usado nas APIs específicas:

resources[].resourceId == accountId           (ACCOUNT)
resources[].resourceId == creditCardAccountId (CREDIT_CARD_ACCOUNT)
resources[].resourceId == contractId          (LOAN, FINANCING, UNARRANGED_ACCOUNT_OVERDRAFT, INVOICE_FINANCING)
resources[].resourceId == investmentId        (BANK_FIXED_INCOME, CREDIT_FIXED_INCOME, VARIABLE_INCOME, TREASURE_TITLE, FUND)
resources[].resourceId == operationId         (EXCHANGE)

Status dos Recursos (status)

Diagrama de Status

stateDiagram-v2
    direction LR

    [*] --> AVAILABLE : Recurso ativo e\nconsentimento AUTHORISED

    AVAILABLE --> TEMPORARILY_UNAVAILABLE : Bloqueio temporário\n(ex: suspeita de fraude)
    AVAILABLE --> UNAVAILABLE             : Encerramento do\nrecurso

    TEMPORARILY_UNAVAILABLE --> AVAILABLE : Bloqueio removido

    PENDING_AUTHORISATION --> AVAILABLE   : Todos os titulares\nauthorizaram

    [*] --> PENDING_AUTHORISATION : Alçada dupla\nincompleta

    classDef ok      fill:#d5f5d5,stroke:#27ae60,color:#333
    classDef warn    fill:#fef9c3,stroke:#f39c12,color:#333
    classDef err     fill:#f5c6c6,stroke:#c0392b,color:#333
    classDef pending fill:#e8d5f5,stroke:#8e44ad,color:#333

    class AVAILABLE ok
    class TEMPORARILY_UNAVAILABLE warn
    class UNAVAILABLE err
    class PENDING_AUTHORISATION pending

Pontos de Atenção

⚠️

RESOURCES_READ no consentimento: A permission RESOURCES_READ deve ser solicitada explicitamente no momento da criação do consentimento. Consentimentos sem essa permission retornam 403 Forbidden.

⚠️

Consentimento AUTHORISED obrigatório: A API Resources só funciona para consentimentos em status AUTHORISED. Tentativas com consentimentos PENDING, REJECTED ou REVOKED retornam erro.

⚠️

resourceId = ID da API específica: O resourceId retornado aqui é o mesmo identificador a ser usado nas chamadas às APIs de produtos (accounts, loans, investments etc.). Não é um ID exclusivo da API Resources.

⚠️

TEMPORARILY_UNAVAILABLE não indica erro permanente: Um recurso neste status pode voltar a AVAILABLE. Não interprete como encerramento - implemente retry ou polling antes de comunicar indisponibilidade ao usuário.

⚠️

PENDING_AUTHORISATION em alçadas duplas: Para contas com mais de um titular, todos devem autorizar o consentimento. Recursos neste status só transitam para AVAILABLE após todos os co-titulares autorizarem.

⚠️

x-fapi-interaction-id obrigatório: A receptora deve gerar e enviar este header. Se o valor recebido for inválido, a transmissora gera um novo UUID e retorna 400. A receptora deve acatar o valor recebido da transmissora na resposta.

⚠️

Paginação: O tamanho mínimo de página é 25. Valores menores que 25 enviados no page-size serão tratados como 25 pela transmissora. Somente a última página pode retornar menos de 25 registros.

⚠️

202 Accepted: Se a transmissora retornar 202, a lista ainda não está pronta. Implemente retry com backoff antes de exibir erro ao usuário.

⚠️

Status 529 (Site Is Overloaded): É um código não-padrão HTTP utilizado pelo Open Finance Brasil para indicar sobrecarga com limite de TPS global atingido. Trate-o como 429 na lógica de retry.