openapi: 3.0.0
info:
  title: API Consents - Open Finance Brasil
  description: |
    API que trata da criação, consulta e revogação de consentimentos para o Open Finance Brasil Fase 2 - customer-data.  
    Não possui segregação entre pessoa natural e pessoa jurídica.    

    # Orientações importantes
    A API Consents trata dos consentimentos exclusivamente para a fase 2 do Open Finance Brasil.
    - As informações da instituição receptora não trafegam na API Consents – a autenticação da receptora se dá através do [DCR](https://openfinancebrasil.atlassian.net/wiki/spaces/OF/pages/17378307/Dynamic+Client+Registration).   
    - Na chamada para a criação do consentimento deve-se utilizar um token gerado via `client_credentials`.
    - Após o `POST` de criação do consentimento, o `STATUS` devolvido na resposta deverá ser `AWAITING_AUTHORISATION`.
    - O `STATUS` será alterado para `AUTHORISED` somente após autenticação e confirmação por parte do usuário na instituição transmissora dos dados.
    - Alteração obrigatória do status `AWAITING_AUTHORISATION` para `REVOKED` após 60 minutos.
    - Todas as datas trafegadas nesta API seguem o padrão da [RFC3339](https://tools.ietf.org/html/rfc3339) e formato "zulu".
    - A descrição do fluxo de consentimento encontra-se disponível no [Portal do desenvolvedor](https://openfinancebrasil.atlassian.net/wiki/spaces/OF/pages/17369300/Dados+Cadastrais+e+Transacionais#Fluxo-b%C3%A1sico-de-consentimento).
    - O arquivo com o mapeamento completo entre `Roles`, `scopes` e `permissions` está disponibilizado no Portal do desenvolvedor, no mesmo item acima - descrição do fluxo de consentimento.
    - A receptora deve enviar obrigatoriamente, no pedido de criação de consentimento, todas as permissions dos agrupamentos de dados as quais ela deseja consentimento, conforme tabela abaixo:
      
      ```
      |----------------------|-------------------------------|----------------------------------------------------------|
      | CATEGORIA DE DADOS   | AGRUPAMENTO                   | PERMISSIONS                                              |
      |----------------------|-------------------------------|----------------------------------------------------------|
      | Cadastro             | Dados Cadastrais PF           | CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ                  |
      |                      |                               | RESOURCES_READ                                           |
      |----------------------|-------------------------------|----------------------------------------------------------|
      | Cadastro             | Informações complementares PF | CUSTOMERS_PERSONAL_ADITTIONALINFO_READ                   |
      |                      |                               | RESOURCES_READ                                           |
      |----------------------|-------------------------------|----------------------------------------------------------|
      | Cadastro             | Dados Cadastrais PJ           | CUSTOMERS_BUSINESS_IDENTIFICATIONS_READ                  |
      |                      |                               | RESOURCES_READ                                           |
      |----------------------|-------------------------------|----------------------------------------------------------|
      | Cadastro             | Informações complementares PJ | CUSTOMERS_BUSINESS_ADITTIONALINFO_READ                   |
      |                      |                               | RESOURCES_READ                                           |
      |----------------------|-------------------------------|----------------------------------------------------------|
      | Contas               | Saldos                        | ACCOUNTS_READ                                            |
      |                      |                               | ACCOUNTS_BALANCES_READ                                   |
      |                      |                               | RESOURCES_READ                                           |
      |----------------------|-------------------------------|----------------------------------------------------------|
      | Contas               | Limites                       | ACCOUNTS_READ                                            |
      |                      |                               | ACCOUNTS_OVERDRAFT_LIMITS_READ                           |
      |                      |                               | RESOURCES_READ                                           |
      |----------------------|-------------------------------|----------------------------------------------------------|
      | Contas               | Extratos                      | ACCOUNTS_READ                                            |
      |                      |                               | ACCOUNTS_TRANSACTIONS_READ                               |
      |                      |                               | RESOURCES_READ                                           |
      |----------------------|-------------------------------|----------------------------------------------------------|
      | Cartão de Crédito    | Limites                       | CREDIT_CARDS_ACCOUNTS_READ                               |
      |                      |                               | CREDIT_CARDS_ACCOUNTS_LIMITS_READ                        |
      |                      |                               | RESOURCES_READ                                           |
      |----------------------|-------------------------------|----------------------------------------------------------|
      | Cartão de Crédito    | Transações                    | CREDIT_CARDS_ACCOUNTS_READ                               |
      |                      |                               | CREDIT_CARDS_ACCOUNTS_TRANSACTIONS_READ                  |
      |                      |                               | RESOURCES_READ                                           |
      |----------------------|-------------------------------|----------------------------------------------------------|
      | Cartão de Crédito    | Faturas                       | CREDIT_CARDS_ACCOUNTS_READ                               |
      |                      |                               | CREDIT_CARDS_ACCOUNTS_BILLS_READ                         |
      |                      |                               | CREDIT_CARDS_ACCOUNTS_BILLS_TRANSACTIONS_READ            |
      |                      |                               | RESOURCES_READ                                           |
      |----------------------|-------------------------------|----------------------------------------------------------|
      | Operações de Crédito | Dados do Contrato             | LOANS_READ                                               |
      |                      |                               | LOANS_WARRANTIES_READ                                    |
      |                      |                               | LOANS_SCHEDULED_INSTALMENTS_READ                         |
      |                      |                               | LOANS_PAYMENTS_READ                                      |
      |                      |                               | FINANCINGS_READ                                          |
      |                      |                               | FINANCINGS_WARRANTIES_READ                               |
      |                      |                               | FINANCINGS_SCHEDULED_INSTALMENTS_READ                    |
      |                      |                               | FINANCINGS_PAYMENTS_READ                                 |
      |                      |                               | UNARRANGED_ACCOUNTS_OVERDRAFT_READ                       |
      |                      |                               | UNARRANGED_ACCOUNTS_OVERDRAFT_WARRANTIES_READ            |
      |                      |                               | UNARRANGED_ACCOUNTS_OVERDRAFT_SCHEDULED_INSTALMENTS_READ |
      |                      |                               | UNARRANGED_ACCOUNTS_OVERDRAFT_PAYMENTS_READ              |
      |                      |                               | INVOICE_FINANCINGS_READ                                  |
      |                      |                               | INVOICE_FINANCINGS_WARRANTIES_READ                       |
      |                      |                               | INVOICE_FINANCINGS_SCHEDULED_INSTALMENTS_READ            |
      |                      |                               | INVOICE_FINANCINGS_PAYMENTS_READ                         |
      |                      |                               | RESOURCES_READ                                           |
      |----------------------|-------------------------------|----------------------------------------------------------|
      ```
    - A instituição transmissora deve validar o preenchimento correto desses agrupamentos no momento da geração do consentimento.
    - Caso a instiuição receptora envie permissões divergentes ao agrupamento especificado na tabela, a transmissora deve rejeitar o pedido da receptora dando retorno HTTP Status Code 400.
    - A transmissora deve retornar, da lista de permissions requisitadas, apenas o subconjunto de permissions por ela suportada, removendo da lista as permissions de produtos não suportados e retornando HTTP Status Code 201. Caso não restem permissões funcionais, a instituição transmissora deve retornar o erro HTTP Code "422 Unprocessable Entity".
  version: 2.0.1
  license:
    name: Apache 2.0
    url: 'http://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/consents/v2'
    description: Servidor de Produção
  - url: 'https://apih.banco.com.br/open-banking/consents/v2'
    description: Servidor de Homologação
tags:
  - name: Consents
    description: 'Operações para criação, consulta e revogação do consentimento dado pelo cliente.'
paths:
  /consents:
    post:
      tags:
        - Consents
      summary: Criar novo pedido de consentimento.
      operationId: consentsPostConsents
      description: Método para a criação de um novo consentimento.
      parameters:
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/xFapiAuthDate'
        - $ref: '#/components/parameters/xFapiCustomerIpAddress'
        - $ref: '#/components/parameters/xFapiInteractionId'
        - $ref: '#/components/parameters/xCustomerUserAgent'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConsent'
        description: Payload para criação do consentimento.
        required: true
      responses:
        '201':
          $ref: '#/components/responses/201ConsentsCreated'
        '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'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '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:
          description: Erro inesperado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
      security:
        - OAuth2Security:
            - consents
  '/consents/{consentId}':
    get:
      tags:
        - Consents
      summary: Obter detalhes do consentimento identificado por consentId.
      operationId: consentsGetConsentsConsentId
      description: Método para obter detalhes do consentimento identificado por consentId.
      parameters:
        - $ref: '#/components/parameters/consentId'
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/xFapiAuthDate'
        - $ref: '#/components/parameters/xFapiCustomerIpAddress'
        - $ref: '#/components/parameters/xFapiInteractionId'
        - $ref: '#/components/parameters/xCustomerUserAgent'
      responses:
        '200':
          $ref: '#/components/responses/200ConsentsConsentIdRead'
        '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'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        '529':
          $ref: '#/components/responses/SiteIsOverloaded'
        default:
          description: Erro inesperado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
      security:
        - OAuth2Security:
            - consents
    delete:
      tags:
        - Consents
      summary: Deletar / Revogar o consentimento identificado por consentId.
      operationId: consentsDeleteConsentsConsentId
      description: Método para deletar / revogar o consentimento identificado por consentId.
      parameters:
        - $ref: '#/components/parameters/consentId'
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/xFapiAuthDate'
        - $ref: '#/components/parameters/xFapiCustomerIpAddress'
        - $ref: '#/components/parameters/xFapiInteractionId'
        - $ref: '#/components/parameters/xCustomerUserAgent'
      responses:
        '204':
          $ref: '#/components/responses/204ConsentsConsentIdDeleted'
        '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'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        '529':
          $ref: '#/components/responses/SiteIsOverloaded'
        default:
          description: Erro inesperado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseError'
      security:
        - OAuth2Security:
            - consents
components:
  schemas:
    Links:
      type: object
      description: Referências para outros recusos da API requisitada.
      required:
        - self
      properties:
        self:
          type: string
          format: uri
          maxLength: 2000
          description: URI completo que gerou a resposta atual.
          example: 'https://api.banco.com.br/open-banking/api/v1/resource'
          pattern: '^(https:\/\/)?(www\.)?[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&\/\/=]*)$'
        first:
          type: string
          format: uri
          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'
          pattern: '^(https:\/\/)?(www\.)?[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&\/\/=]*)$'
        prev:
          type: string
          format: uri
          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'
          pattern: '^(https:\/\/)?(www\.)?[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&\/\/=]*)$'
        next:
          type: string
          format: uri
          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'
          pattern: '^(https:\/\/)?(www\.)?[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&\/\/=]*)$'
        last:
          type: string
          format: uri
          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'
          pattern: '^(https:\/\/)?(www\.)?[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&\/\/=]*)$'
    Meta:
      type: object
      description: Meta informações referente à API requisitada.
      required:
        - totalRecords
        - totalPages
        - requestDateTime
      properties:
        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
        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'
    CreateConsent:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - permissions
            - loggedUser
            - expirationDateTime
          properties:
            loggedUser:
              $ref: '#/components/schemas/LoggedUser'
            businessEntity:
              $ref: '#/components/schemas/BusinessEntity'
            permissions:
              type: array
              items:
                description: 'Especifica os tipos de permissões de acesso às APIs no escopo do Open Finance Brasil - Fase 2, de acordo com os blocos de consentimento fornecidos pelo usuário e necessários ao acesso a cada endpoint das APIs.'
                type: string
                enum:
                  - ACCOUNTS_READ
                  - ACCOUNTS_BALANCES_READ
                  - ACCOUNTS_TRANSACTIONS_READ
                  - ACCOUNTS_OVERDRAFT_LIMITS_READ
                  - CREDIT_CARDS_ACCOUNTS_READ
                  - CREDIT_CARDS_ACCOUNTS_BILLS_READ
                  - CREDIT_CARDS_ACCOUNTS_BILLS_TRANSACTIONS_READ
                  - CREDIT_CARDS_ACCOUNTS_LIMITS_READ
                  - CREDIT_CARDS_ACCOUNTS_TRANSACTIONS_READ
                  - CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ
                  - CUSTOMERS_PERSONAL_ADITTIONALINFO_READ
                  - CUSTOMERS_BUSINESS_IDENTIFICATIONS_READ
                  - CUSTOMERS_BUSINESS_ADITTIONALINFO_READ
                  - FINANCINGS_READ
                  - FINANCINGS_SCHEDULED_INSTALMENTS_READ
                  - FINANCINGS_PAYMENTS_READ
                  - FINANCINGS_WARRANTIES_READ
                  - INVOICE_FINANCINGS_READ
                  - INVOICE_FINANCINGS_SCHEDULED_INSTALMENTS_READ
                  - INVOICE_FINANCINGS_PAYMENTS_READ
                  - INVOICE_FINANCINGS_WARRANTIES_READ
                  - LOANS_READ
                  - LOANS_SCHEDULED_INSTALMENTS_READ
                  - LOANS_PAYMENTS_READ
                  - LOANS_WARRANTIES_READ
                  - UNARRANGED_ACCOUNTS_OVERDRAFT_READ
                  - UNARRANGED_ACCOUNTS_OVERDRAFT_SCHEDULED_INSTALMENTS_READ
                  - UNARRANGED_ACCOUNTS_OVERDRAFT_PAYMENTS_READ
                  - UNARRANGED_ACCOUNTS_OVERDRAFT_WARRANTIES_READ
                  - RESOURCES_READ
              minItems: 1
              maxItems: 30
              example:
                - ACCOUNTS_READ
                - ACCOUNTS_OVERDRAFT_LIMITS_READ
                - RESOURCES_READ
            expirationDateTime:
              description: 'Data e hora de expiração da permissão. De preenchimento obrigatório, reflete a data limite de validade do consentimento. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format).'
              type: string
              maxLength: 20
              format: date-time
              example: '2021-05-21T08:30:00Z'
    EnumRejectedBy:
      type: string
      description: |
        Informar usuário responsável pela rejeição.   
        1. USER usuário   
        2. ASPSP instituição transmissora   
        3. TPP instituição receptora   
      enum:
        - USER
        - ASPSP
        - TPP
      example: USER
    EnumReasonCode:
      type: string
      description: |
        Define o código da razão pela qual o consentimento foi rejeitado.

        - CONSENT_EXPIRED – consentimento que ultrapassou o tempo limite para autorização.   
        - CUSTOMER_MANUALLY_REJECTED – cliente efetuou a rejeição do consentimento manualmente através de interação nas instituições participantes.   
        - CUSTOMER_MANUALLY_REVOKED – cliente efetuou a revogação após a autorização do consentimento.   
        - CONSENT_MAX_DATE_REACHED – consentimento que ultrapassou o tempo limite de compartilhamento.   
        - CONSENT_TECHNICAL_ISSUE – consentimento que foi rejeitado devido a um problema técnico que impossibilita seu uso pela instituição receptora, por exemplo: falha associada a troca do AuthCode pelo AccessToken, durante o processo de Hybid Flow.   
        - INTERNAL_SECURITY_REASON – consentimento que foi rejeitado devido as políticas de segurança aplicada pela instituição transmissora.
      enum:
        - CONSENT_EXPIRED
        - CUSTOMER_MANUALLY_REJECTED
        - CUSTOMER_MANUALLY_REVOKED
        - CONSENT_MAX_DATE_REACHED
        - CONSENT_TECHNICAL_ISSUE
        - INTERNAL_SECURITY_REASON
      example: CONSENT_EXPIRED
    RejectedReason:
      type: object
      description: Define a razão pela qual o consentimento foi rejeitado.
      required:
        - code
      properties:
        code:
          $ref: '#/components/schemas/EnumReasonCode'
        additionalInformation:
          type: string
          description: Contém informações adicionais a critério da transmissora.
          maxLength: 140
          pattern: '[\w\W\s]*'
          example: Tempo de confirmação da múltipla alçada excedido.
    ResponseConsent:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - consentId
            - creationDateTime
            - status
            - statusUpdateDateTime
            - permissions
            - expirationDateTime
          properties:
            consentId:
              description: |
                O consentId é o identificador único do consentimento e deverá ser um URN - Uniform Resource Name.  
                Um URN, conforme definido na [RFC8141](https://tools.ietf.org/html/rfc8141) é um Uniform Resource 
                Identifier - URI - que é atribuído sob o URI scheme "urn" e um namespace URN específico, com a intenção de que o URN 
                seja um identificador de recurso persistente e independente da localização.  
                Considerando a string urn:bancoex:C1DD33123 como exemplo para consentId temos:
                - o namespace(urn)
                - o identificador associado ao namespace da instituição transnmissora (bancoex) 
                - o identificador específico dentro do namespace (C1DD33123).  
                Informações mais detalhadas sobre a construção de namespaces devem ser consultadas na [RFC8141](https://tools.ietf.org/html/rfc8141).
              type: string
              pattern: '^urn:[a-zA-Z0-9][a-zA-Z0-9-]{0,31}:[a-zA-Z0-9()+,\-.:=@;$_!*''%\/?#]+$'
              maxLength: 256
              example: 'urn:bancoex:C1DD33123'
            creationDateTime:
              description: 'Data e hora em que o recurso foi criado. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format).'
              type: string
              format: date-time
              example: '2021-05-21T08:30:00Z'
              maxLength: 20
            status:
              description: Estado atual do consentimento cadastrado.
              type: string
              enum:
                - AUTHORISED
                - AWAITING_AUTHORISATION
                - REJECTED
              example: AWAITING_AUTHORISATION
            statusUpdateDateTime:
              description: 'Data e hora em que o recurso foi atualizado. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format).'
              type: string
              format: date-time
              example: '2021-05-21T08:30:00Z'
              maxLength: 20
            permissions:
              type: array
              maxItems: 30
              minItems: 1
              description: 'Especifica os tipos de permissões de acesso às APIs no escopo do Open Finance Brasil - Fase 2, de acordo com os blocos de consentimento fornecidos pelo usuário e necessários ao acesso a cada endpoint das APIs.'
              items:
                type: string
                enum:
                  - ACCOUNTS_READ
                  - ACCOUNTS_BALANCES_READ
                  - ACCOUNTS_TRANSACTIONS_READ
                  - ACCOUNTS_OVERDRAFT_LIMITS_READ
                  - CREDIT_CARDS_ACCOUNTS_READ
                  - CREDIT_CARDS_ACCOUNTS_BILLS_READ
                  - CREDIT_CARDS_ACCOUNTS_BILLS_TRANSACTIONS_READ
                  - CREDIT_CARDS_ACCOUNTS_LIMITS_READ
                  - CREDIT_CARDS_ACCOUNTS_TRANSACTIONS_READ
                  - CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ
                  - CUSTOMERS_PERSONAL_ADITTIONALINFO_READ
                  - CUSTOMERS_BUSINESS_IDENTIFICATIONS_READ
                  - CUSTOMERS_BUSINESS_ADITTIONALINFO_READ
                  - FINANCINGS_READ
                  - FINANCINGS_SCHEDULED_INSTALMENTS_READ
                  - FINANCINGS_PAYMENTS_READ
                  - FINANCINGS_WARRANTIES_READ
                  - INVOICE_FINANCINGS_READ
                  - INVOICE_FINANCINGS_SCHEDULED_INSTALMENTS_READ
                  - INVOICE_FINANCINGS_PAYMENTS_READ
                  - INVOICE_FINANCINGS_WARRANTIES_READ
                  - LOANS_READ
                  - LOANS_SCHEDULED_INSTALMENTS_READ
                  - LOANS_PAYMENTS_READ
                  - LOANS_WARRANTIES_READ
                  - UNARRANGED_ACCOUNTS_OVERDRAFT_READ
                  - UNARRANGED_ACCOUNTS_OVERDRAFT_SCHEDULED_INSTALMENTS_READ
                  - UNARRANGED_ACCOUNTS_OVERDRAFT_PAYMENTS_READ
                  - UNARRANGED_ACCOUNTS_OVERDRAFT_WARRANTIES_READ
                  - RESOURCES_READ
              example:
                - ACCOUNTS_READ
                - ACCOUNTS_OVERDRAFT_LIMITS_READ
                - RESOURCES_READ
            expirationDateTime:
              description: 'Data e hora de expiração da permissão. De preenchimento obrigatório, reflete a data limite de validade do consentimento. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format).'
              type: string
              format: date-time
              example: '2021-05-21T08:30:00Z'
              maxLength: 20
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/Meta'
    ResponseConsentRead:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - consentId
            - creationDateTime
            - status
            - statusUpdateDateTime
            - permissions
            - expirationDateTime
          properties:
            consentId:
              description: |
                O consentId é o identificador único do consentimento e deverá ser um URN - Uniform Resource Name.  
                Um URN, conforme definido na [RFC8141](https://tools.ietf.org/html/rfc8141) é um Uniform Resource 
                Identifier - URI - que é atribuído sob o URI scheme "urn" e um namespace URN específico, com a intenção de que o URN 
                seja um identificador de recurso persistente e independente da localização.  
                Considerando a string urn:bancoex:C1DD33123 como exemplo para consentId temos:
                - o namespace(urn)
                - o identificador associado ao namespace da instituição transnmissora (bancoex) 
                - o identificador específico dentro do namespace (C1DD33123).  
                Informações mais detalhadas sobre a construção de namespaces devem ser consultadas na [RFC8141](https://tools.ietf.org/html/rfc8141).
              type: string
              pattern: '^urn:[a-zA-Z0-9][a-zA-Z0-9-]{0,31}:[a-zA-Z0-9()+,\-.:=@;$_!*''%\/?#]+$'
              maxLength: 256
              example: 'urn:bancoex:C1DD33123'
            creationDateTime:
              description: 'Data e hora em que o recurso foi criado. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format).'
              type: string
              format: date-time
              example: '2021-05-21T08:30:00Z'
              maxLength: 20
            status:
              description: Estado atual do consentimento cadastrado.
              type: string
              enum:
                - AUTHORISED
                - AWAITING_AUTHORISATION
                - REJECTED
              example: AWAITING_AUTHORISATION
            statusUpdateDateTime:
              description: 'Data e hora em que o recurso foi atualizado. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format).'
              type: string
              format: date-time
              example: '2021-05-21T08:30:00Z'
              maxLength: 20
            permissions:
              type: array
              maxItems: 30
              minItems: 1
              description: 'Especifica os tipos de permissões de acesso às APIs no escopo do Open Finance Brasil - Fase 2, de acordo com os blocos de consentimento fornecidos pelo usuário e necessários ao acesso a cada endpoint das APIs.'
              items:
                type: string
                enum:
                  - ACCOUNTS_READ
                  - ACCOUNTS_BALANCES_READ
                  - ACCOUNTS_TRANSACTIONS_READ
                  - ACCOUNTS_OVERDRAFT_LIMITS_READ
                  - CREDIT_CARDS_ACCOUNTS_READ
                  - CREDIT_CARDS_ACCOUNTS_BILLS_READ
                  - CREDIT_CARDS_ACCOUNTS_BILLS_TRANSACTIONS_READ
                  - CREDIT_CARDS_ACCOUNTS_LIMITS_READ
                  - CREDIT_CARDS_ACCOUNTS_TRANSACTIONS_READ
                  - CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ
                  - CUSTOMERS_PERSONAL_ADITTIONALINFO_READ
                  - CUSTOMERS_BUSINESS_IDENTIFICATIONS_READ
                  - CUSTOMERS_BUSINESS_ADITTIONALINFO_READ
                  - FINANCINGS_READ
                  - FINANCINGS_SCHEDULED_INSTALMENTS_READ
                  - FINANCINGS_PAYMENTS_READ
                  - FINANCINGS_WARRANTIES_READ
                  - INVOICE_FINANCINGS_READ
                  - INVOICE_FINANCINGS_SCHEDULED_INSTALMENTS_READ
                  - INVOICE_FINANCINGS_PAYMENTS_READ
                  - INVOICE_FINANCINGS_WARRANTIES_READ
                  - LOANS_READ
                  - LOANS_SCHEDULED_INSTALMENTS_READ
                  - LOANS_PAYMENTS_READ
                  - LOANS_WARRANTIES_READ
                  - UNARRANGED_ACCOUNTS_OVERDRAFT_READ
                  - UNARRANGED_ACCOUNTS_OVERDRAFT_SCHEDULED_INSTALMENTS_READ
                  - UNARRANGED_ACCOUNTS_OVERDRAFT_PAYMENTS_READ
                  - UNARRANGED_ACCOUNTS_OVERDRAFT_WARRANTIES_READ
                  - RESOURCES_READ
              example:
                - ACCOUNTS_READ
                - ACCOUNTS_OVERDRAFT_LIMITS_READ
                - RESOURCES_READ
            expirationDateTime:
              description: 'Data e hora de expiração da permissão. De preenchimento obrigatório, reflete a data limite de validade do consentimento. Uma string com data e hora conforme especificação RFC-3339, sempre com a utilização de timezone UTC(UTC time format).'
              type: string
              format: date-time
              example: '2021-05-21T08:30:00Z'
              maxLength: 20
            rejection:
              type: object
              description: Objeto a ser retornado caso o consentimento seja rejeitado.
              required:
                - rejectedBy
                - reason
              properties:
                rejectedBy:
                  $ref: '#/components/schemas/EnumRejectedBy'
                reason:
                  $ref: '#/components/schemas/RejectedReason'
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/Meta'
    ResponseError:
      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'
    ResponseErrorMetaSingle:
      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:
          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'
    LoggedUser:
      type: object
      description: Usuário (pessoa natural) que encontra-se logado na instituição receptora e que iniciará o processo de consentimento para compartilhamento de dados.
      required:
        - document
      properties:
        document:
          type: object
          required:
            - identification
            - rel
          properties:
            identification:
              type: string
              maxLength: 11
              description: Número do documento de identificação oficial do usuário.
              example: '11111111111'
              pattern: '^\d{11}$'
            rel:
              type: string
              maxLength: 3
              description: Tipo do documento de identificação oficial do usuário.
              example: CPF
              pattern: '^[A-Z]{3}$'
    BusinessEntity:
      type: object
      description: 'Titular, pessoa jurídica a quem se referem os dados que são objeto de compartilhamento.'
      required:
        - document
      properties:
        document:
          type: object
          required:
            - identification
            - rel
          properties:
            identification:
              type: string
              maxLength: 14
              description: Número do documento de identificação oficial do titular pessoa jurídica.
              example: '11111111111111'
              pattern: '^\d{14}$'
            rel:
              type: string
              maxLength: 4
              description: Tipo do documento de identificação oficial do titular pessoa jurídica.
              example: CNPJ
              pattern: '^[A-Z]{4}$'
  parameters:
    consentId:
      name: consentId
      in: path
      description: |
        O consentId é o identificador único do consentimento e deverá ser um URN - Uniform Resource Name.  
        Um URN, conforme definido na [RFC8141](https://tools.ietf.org/html/rfc8141) é um Uniform Resource 
        Identifier - URI - que é atribuído sob o URI scheme "urn" e um namespace URN específico, com a intenção de que o URN 
        seja um identificador de recurso persistente e independente da localização.  
        Considerando a string urn:bancoex:C1DD33123 como exemplo para consentId temos:
        - o namespace(urn)
        - o identificador associado ao namespace da instituição transnmissora (bancoex) 
        - o identificador específico dentro do namespace (C1DD33123).  
        Informações mais detalhadas sobre a construção de namespaces devem ser consultadas na [RFC8141](https://tools.ietf.org/html/rfc8141).
      required: true
      schema:
        type: string
        pattern: '^urn:[a-zA-Z0-9][a-zA-Z0-9-]{0,31}:[a-zA-Z0-9()+,\-.:=@;$_!*''%\/?#]+$'
        maxLength: 256
    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
    xCustomerUserAgent:
      name: x-customer-user-agent
      in: header
      description: Indica o user-agent que o usuário utiliza.
      required: false
      schema:
        type: string
        pattern: '[\w\W\s]*'
        minLength: 1
        maxLength: 100
    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: '[\w\W\s]*'
        minLength: 1
        maxLength: 100
    xFapiInteractionId:
      name: x-fapi-interaction-id
      in: header
      description: 'Um UID [RFC4122](https://tools.ietf.org/html/rfc4122) usado como um ID de correlação. Se fornecido, o transmissor deve "reproduzir" esse valor no cabeçalho de resposta.'
      required: false
      schema:
        type: string
        pattern: '^[a-zA-Z0-9][a-zA-Z0-9\-]{0,99}$'
        minLength: 1
        maxLength: 100
  securitySchemes:
    OAuth2Security:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: 'https://authserver.example/token'
          scopes:
            consents: Criação do consentimento.
  responses:
    UnsupportedMediaType:
      description: O formato do payload não é um formato suportado.
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseError'
    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/ResponseError'
    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/ResponseError'
    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/ResponseError'
    InternalServerError:
      description: Ocorreu um erro no gateway da API ou no microsserviço
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseError'
    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/ResponseError'
    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/ResponseError'
    NotFound:
      description: O recurso solicitado não existe ou não foi implementado
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseError'
    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/ResponseError'
    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/ResponseError'
    Unauthorized:
      description: Cabeçalho de autenticação ausente/inválido ou token inválido
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/ResponseError'
    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:
            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
                  additionalProperties: false
              meta:
                type: object
                description: Meta informações referente à API requisitada.
                required:
                  - totalRecords
                  - totalPages
                  - requestDateTime
                properties:
                  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
                  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'
                additionalProperties: false
            additionalProperties: false
    201ConsentsCreated:
      description: Consentimento criado com sucesso.
      headers:
        x-fapi-interaction-id:
          description: |
            Um UID [RFC4122](https://tools.ietf.org/html/rfc4122) usado como um ID de correlação.  
            Se fornecido, o transmissor deve "reproduzir" esse valor no cabeçalho de resposta.          
          schema:
            type: string
            pattern: '^[a-zA-Z0-9][a-zA-Z0-9\-]{0,99}$'
            minLength: 1
            maxLength: 100
            example: 73cac523-d3ae-2289-b106-330a6218710d
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseConsent'
    200ConsentsConsentIdRead:
      description: Consentimento consultado com sucesso.
      headers:
        x-fapi-interaction-id:
          description: |
            Um UID [RFC4122](https://tools.ietf.org/html/rfc4122) usado como um ID de correlação.  
            Se fornecido, o transmissor deve "reproduzir" esse valor no cabeçalho de resposta.          
          schema:
            type: string
            pattern: '^[a-zA-Z0-9][a-zA-Z0-9\-]{0,99}$'
            minLength: 1
            maxLength: 100
            example: 92cac523-d3ae-2289-b106-330a6218710d
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseConsentRead'
    204ConsentsConsentIdDeleted:
      description: Consentimento revogado com sucesso.
      headers:
        x-fapi-interaction-id:
          description: |
            Um UID [RFC4122](https://tools.ietf.org/html/rfc4122) usado como um ID de correlação.  
            Se fornecido, o transmissor deve "reproduzir" esse valor no cabeçalho de resposta.          
          schema:
            type: string
            pattern: '^[a-zA-Z0-9][a-zA-Z0-9\-]{0,99}$'
            minLength: 1
            maxLength: 100
            example: 85bac523-d3ae-2289-b106-330a6218710d