openapi: 3.0.0
info:
  title: API Resources - Open Finance Brasil
  description: |
    API que trata da consulta do status de recursos para o Open Finance Brasil - Dados cadastrais e transacionais.\
    Não possui segregação entre pessoa natural e pessoa jurídica.

    # Orientações importantes
    - A API resources lista os recursos vinculados ao consentimento específico, identificado por `consentId` e vinculado ao token enviado no header `Authorization`.
    - A API Resources somente está disponível para consentimentos que se encontram no status `AUTHORISED`.
    - Os `STATUS` dos recursos listados DEVEM considerar não apenas o consentimento vinculado mas também a disponibilidade do recurso na instituição transmissora dos dados.
    - A `permission` específica desta API  - `RESOURCES_READ` - DEVE ser solicitada pela instituição receptora na ocasião do pedido de criação do consentimento.
    - O identificador do recurso devolvido na API Resources - `resourceId` - quando apresentado corresponde ao mesmo identificador designado para o recurso em sua API específica, o seja: o `resourceId` corresponde ao `accountId` da API accounts, ao `creditCardAccountId` da API de conta
    pós-paga e assim sucessivamente.

    ## Status previstos para os recursos listados na API Resources
    - AVAILABLE: indica que o recurso encontra-se disponível e o(s) consentimento(s) associado(s) possui(em) status `AUTHORISED`.
    - UNAVAILABLE: indica que o recurso não está mais disponível, por exemplo, em caso de uma conta encerrada.
    - TEMPORARILY_UNAVAILABLE: indica que o recurso encontra-se temporariamente indisponível, embora o(s) consentimento(s) associado(s) possua(m) status `AUTHORISED`.  
    Caso de exemplo: conta temporariamente bloqueada por suspeita de fraude.
    - PENDING_AUTHORISATION: indica a existência de pendências para o compartilhamento do recurso, por exemplo, em caso de alçada dupla, quando é necessário o consentimento de mais de um titular.

    ## Permissions necessárias para a API Resources
    ### `/resources`
      - permissions:
        - GET: **RESOURCES_READ**
  version: 3.1.0
  license:
    name: Apache 2.0
    url: 'https://www.apache.org/licenses/LICENSE-2.0'
  contact:
    name: Governança do Open Finance Brasil – Especificações
    email: gt-interfaces@openbankingbr.org
    url: 'https://openbanking-brasil.github.io/areadesenvolvedor/'
servers:
  - url: 'https://api.banco.com.br/open-banking/resources/v3'
    description: Servidor de Produção
  - url: 'https://apih.banco.com.br/open-banking/resources/v3'
    description: Servidor de Homologação
tags:
  - name: Resources
paths:
  /resources:
    get:
      tags:
        - Resources
      summary: Obtém a lista de recursos consentidos pelo cliente.
      operationId: resourcesGetResources
      description: Método para obter a lista de recursos mantidos pelo cliente na instituição transmissora e para as quais ele tenha fornecido consentimento.
      parameters:
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/xFapiAuthDate'
        - $ref: '#/components/parameters/xFapiCustomerIpAddress'
        - $ref: '#/components/parameters/xFapiInteractionId'
        - $ref: '#/components/parameters/xCustomerUserAgent'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          $ref: '#/components/responses/OKResponseResourceList'
        '202':
          $ref: '#/components/responses/202ResponseResource'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        '529':
          $ref: '#/components/responses/SiteIsOverloaded'
        default:
          $ref: '#/components/responses/Default'
      security:
        - OpenId:
            - openid
          OAuth2Security:
            - 'consent:consentId'
            - resources
components:
  headers:
    xFapiInteractionId:
      description: Um UUID [RFC4122](https://tools.ietf.org/html/rfc4122) usado como um ID de correlação entre request e response. Campo de geração e envio obrigatório pela receptora (client) e o seu valor deve ser “espelhado” pela transmissora (server) no cabeçalho de resposta. Caso não seja recebido ou se for recebido um valor inválido, a transmissora deve gerar um x-fapi-interaction-id e retorná-lo na resposta com o HTTP Status Code 400. A receptora deve acatar o valor recebido da transmissora.
      schema:
        $ref: '#/components/schemas/XFapiInteractionId'
    X-V: 
      description: |
          Cabeçalho que indica a versão implementada da API pela instituição financeira. Deve ser preenchido de forma completa, por exemplo: x-v : 1.0.2
      required: true
      schema:
        $ref: '#/components/schemas/X-V'
  schemas:
    ResponseResourceList:
      type: object
      required:
        - data
        - links
        - meta
      properties:
        data:
          type: array
          minItems: 0
          items:
            type: object
            required:
              - resourceId
              - type
              - status
            x-regulatory-required:
              - resourceId
              - type
              - status
            properties:
              resourceId:
                type: string
                description: |
                  Identifica o recurso reportado pelo participante do Open Finance, no caso de:
                  - Contas de depósito à vista, de poupança ou de pagamento pré-paga : corresponde ao accountId;
                  - Conta de pagamento pós-paga: corresponde ao  creditCardAccountId;
                  - Empréstimos, Financiamentos, Direitos creditórios descontados e Adiantamento a depositantes: corresponde ao contractId
                  - Renda Fixa Bancária, Renda Fixa Crédito, Renda Variável, Título do Tesouro Direto e Fundo de Investimento: corresponde ao investmentId;
                  - Câmbio: corresponde ao operationId.
                minLength: 1
                maxLength: 100
                pattern: '^[a-zA-Z0-9][a-zA-Z0-9-]{0,99}$'
                example: 25cac914-d8ae-6789-b215-650a6215820d
              type:
                type: string
                enum:
                  - ACCOUNT
                  - CREDIT_CARD_ACCOUNT
                  - LOAN
                  - FINANCING
                  - UNARRANGED_ACCOUNT_OVERDRAFT
                  - INVOICE_FINANCING
                  - BANK_FIXED_INCOME
                  - CREDIT_FIXED_INCOME
                  - VARIABLE_INCOME
                  - TREASURE_TITLE
                  - FUND
                  - EXCHANGE
                description: |
                  Tipo de recurso (vide Enum):
                    - Account - Conta de depósito à vista, poupança ou pagamento pré-paga
                    - Credit Card Account - Conta de pagamento pós-paga (Cartão de Crédito)
                    - Loan - Empréstimo
                    - Financing - Financiamento
                    - Unarranged Account Overdraft - Cheque Especial
                    - Invoice Financing - Financiamento de Fatura
                    - Bank Fixed Income - Renda Fixa Bancária
                    - Credit Fixed Income - Renda Fixa Crédito
                    - Variabel Income - Renda Variável
                    - Treasure Title - Título do Tesouro Direto
                    - Fund - Fundo de Investimento
                    - Exchange - Câmbio
                example: ACCOUNT
              status:
                type: string
                enum:
                  - AVAILABLE
                  - UNAVAILABLE
                  - TEMPORARILY_UNAVAILABLE
                  - PENDING_AUTHORISATION
                description: |
                  Tipo de status de recurso (vide Enum):
                  Available - Disponível
                  Unavailable - Indisponível
                  Temporarily Unavailable - Temporariamente Indisponível
                  Pending Authorisation - Pendente de Autorização
                example: AVAILABLE
          description: Lista de recursos e seus respectivos status.
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/MetaResponse'
    Links:
      type: object
      description: Referências para outros recusos da API requisitada.
      required:
        - self
      properties:
        self:
          type: string
          format: url
          maxLength: 2000
          description: URI completo que gerou a resposta atual.
          example: 'https://api.banco.com.br/open-banking/api/v1/resource'
        first:
          type: string
          format: url
          maxLength: 2000
          description: URI da primeira página que originou essa lista de resultados. Restrição - Obrigatório quando não for a primeira página da resposta
          example: 'https://api.banco.com.br/open-banking/api/v1/resource'
        prev:
          type: string
          format: url
          maxLength: 2000
          description: "URI da página anterior dessa lista de resultados. Restrição - \tObrigatório quando não for a primeira página da resposta"
          example: 'https://api.banco.com.br/open-banking/api/v1/resource'
        next:
          type: string
          format: url
          maxLength: 2000
          description: URI da próxima página dessa lista de resultados. Restrição - Obrigatório quando não for a última página da resposta
          example: 'https://api.banco.com.br/open-banking/api/v1/resource'
        last:
          type: string
          format: url
          maxLength: 2000
          description: URI da última página dessa lista de resultados. Restrição - Obrigatório quando não for a última página da resposta
          example: 'https://api.banco.com.br/open-banking/api/v1/resource'
    Meta:
      type: object
      description: Meta informações referente à API requisitada.
      required:
        - requestDateTime
      properties:
        requestDateTime:
          description: 'Data e hora da consulta, conforme especificação RFC-3339, formato UTC.'
          type: string
          maxLength: 20
          format: date-time
          example: '2021-05-21T08:30:00Z'
    MetaResponse:
      type: object
      description: Meta informações referente à API requisitada.
      required:
        - requestDateTime
        - totalRecords
        - totalPages
      properties:
        requestDateTime:
          description: 'Data e hora da consulta, conforme especificação RFC-3339, formato UTC.'
          type: string
          maxLength: 20
          format: date-time
          example: '2021-05-21T08:30:00Z'
        totalRecords:
          type: integer
          format: int32
          description: Número total de registros no resultado
          example: 1
        totalPages:
          type: integer
          format: int32
          description: Número total de páginas no resultado
          example: 1
    XFapiInteractionId:
      type: string
      format: uuid
      minLength: 1
      maxLength: 36
      pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
      example: d78fc4e5-37ca-4da3-adf2-9b082bf92280
    X-V:
      type: string
      pattern: '^\d+\.\d+\.\d+$'
      example: 1.0.0
    ResponseErrorWithAbleAdditionalProperties:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          minItems: 1
          maxItems: 13
          items:
            type: object
            required:
              - code
              - title
              - detail
            properties:
              code:
                description: Código de erro específico do endpoint
                type: string
                pattern: '[\w\W\s]*'
                maxLength: 255
              title:
                description: Título legível por humanos deste erro específico
                type: string
                pattern: '[\w\W\s]*'
                maxLength: 255
              detail:
                description: Descrição legível por humanos deste erro específico
                type: string
                pattern: '[\w\W\s]*'
                maxLength: 2048
        meta:
          $ref: '#/components/schemas/Meta'
  parameters:
    Authorization:
      name: Authorization
      in: header
      description: Cabeçalho HTTP padrão. Permite que as credenciais sejam fornecidas dependendo do tipo de recurso solicitado
      required: true
      schema:
        type: string
        pattern: '[\w\W\s]*'
        maxLength: 2048
    page:
      name: page
      in: query
      description: Número da página que está sendo requisitada (o valor da primeira página é 1).
      schema:
        type: integer
        default: 1
        minimum: 1
        maximum: 2147483647
        format: int32
    pageSize:
      name: page-size
      in: query
      description: |
        Quantidade total de registros por páginas. 
        A transmissora deve considerar entrada como 25, caso seja informado algum valor menor pela receptora. 
        Enquanto houver mais que 25 registros a enviar, a transmissora deve considerar o mínimo por página como 25. 
        Somente a última página retornada (ou primeira, no caso de página única) pode conter menos de 25 registros. 
        Mais informações, acesse Especificações de APIs > Padrões > Paginação.
      schema:
        type: integer
        default: 25
        minimum: 25
        format: int32
        maximum: 1000
    xCustomerUserAgent:
      name: x-customer-user-agent
      in: header
      description: Indica o user-agent que o usuário utiliza.
      required: false
      schema:
        type: string
        pattern: '^[^\s](.*[^\s])?$'
        minLength: 1
        maxLength: 255
    xFapiAuthDate:
      name: x-fapi-auth-date
      in: header
      description: 'Data em que o usuário logou pela última vez com o receptor. Representada de acordo com a [RFC7231](https://tools.ietf.org/html/rfc7231).Exemplo: Sun, 10 Sep 2017 19:43:31 UTC'
      required: false
      schema:
        type: string
        pattern: '^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} (GMT|UTC)$'
        minLength: 29
        maxLength: 29
    xFapiCustomerIpAddress:
      name: x-fapi-customer-ip-address
      in: header
      description: O endereço IP do usuário se estiver atualmente logado com o receptor.
      required: false
      schema:
        type: string
        pattern: '^[^\s](.*[^\s])?$'
        minLength: 1
        maxLength: 255
    xFapiInteractionId:
      name: x-fapi-interaction-id
      in: header
      description: Um UUID [RFC4122](https://tools.ietf.org/html/rfc4122) usado como um ID de correlação entre request e response. Campo de geração e envio obrigatório pela receptora (client) e o seu valor deve ser “espelhado” pela transmissora (server) no cabeçalho de resposta. Caso não seja recebido ou se for recebido um valor inválido, a transmissora deve gerar um x-fapi-interaction-id e retorná-lo na resposta com o HTTP Status Code 400. A receptora deve acatar o valor recebido da transmissora.
      required: true
      schema:
        type: string
        format: uuid
        minLength: 1
        maxLength: 36
        pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
        example: d78fc4e5-37ca-4da3-adf2-9b082bf92280
  securitySchemes:
    OpenId:
      type: openIdConnect
      openIdConnectUrl: 'https://auth.mockbank.poc.raidiam.io/.well-known/openid-configuration'
    OAuth2Security:
      type: oauth2
      description: Fluxo OAuth necessário para que a receptora tenha acesso aos dados na instituição transmissora. Requer o processo de redirecionamento e autenticação do usuário a que se referem os dados.
      flows:
        authorizationCode:
          authorizationUrl: 'https://authserver.example/authorization'
          tokenUrl: 'https://authserver.example/token'
          scopes:
            resources: Escopo necessário para acesso à API Resources. O controle dos endpoints específicos é feito via permissions.
  responses:
    OKResponseResourceList:
      description: Dados de status dos recursos obtidos com sucesso.
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/xFapiInteractionId'
        x-v:
          $ref: '#/components/headers/X-V'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseResourceList'
    202ResponseResource:
      description: Requisição foi recebida.
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/xFapiInteractionId'
        x-v:
          $ref: '#/components/headers/X-V'
    BadRequest:
      description: 'A requisição foi malformada, omitindo atributos obrigatórios, seja no payload ou através de atributos na URL.'
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseErrorWithAbleAdditionalProperties'
    Forbidden:
      description: O token tem escopo incorreto ou uma política de segurança foi violada
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseErrorWithAbleAdditionalProperties'
    InternalServerError:
      description: Ocorreu um erro no gateway da API ou no microsserviço
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseErrorWithAbleAdditionalProperties'
    GatewayTimeout:
      description: GATEWAY TIMEOUT - A requisição não foi atendida dentro do tempo limite estabelecido
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseErrorWithAbleAdditionalProperties'
    MethodNotAllowed:
      description: O consumidor tentou acessar o recurso com um método não suportado
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseErrorWithAbleAdditionalProperties'
    NotAcceptable:
      description: A solicitação continha um cabeçalho Accept diferente dos tipos de mídia permitidos ou um conjunto de caracteres diferente de UTF-8
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseErrorWithAbleAdditionalProperties'
    NotFound:
      description: O recurso solicitado não existe ou não foi implementado
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseErrorWithAbleAdditionalProperties'
    TooManyRequests:
      description: 'A operação foi recusada, pois muitas solicitações foram feitas dentro de um determinado período ou o limite global de requisições concorrentes foi atingido'
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseErrorWithAbleAdditionalProperties'
    Unauthorized:
      description: Cabeçalho de autenticação ausente/inválido ou token inválido
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseErrorWithAbleAdditionalProperties'
    SiteIsOverloaded:
      description: 'O site está sobrecarregado e a operação foi recusada, pois foi atingido o limite máximo de TPS global, neste momento.'
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseErrorWithAbleAdditionalProperties'
    UnprocessableEntity:
      description: 'A sintaxe da requisição esta correta, mas não foi possível processar as instruções presentes.'
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseErrorWithAbleAdditionalProperties'
    Default:
      description: Erro inesperado.
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseErrorWithAbleAdditionalProperties'