openapi: 3.0.0
info:
  title: API Exchange - Open Finance Brasil
  description: |
    API de Câmbio do Open Finance Brasil – Fase 4.
    API que retorna informações de Câmbio.
  version: 1.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/opendata-exchange/v1'
    description: Servidor de Produção
  - url: 'https://apih.banco.com.br/open-banking/opendata-exchange/v1'
    description: Servidor de Homologação
tags:
  - name: Exchange Online Rate
    description: Operações para obter as informações de Câmbio para taxa online.
  - name: Exchange VET Value
    description: Operações para obter as informações de Câmbio para valor do VET.
paths:
  /online-rates:
    get:
      tags:
        - Exchange Online Rate
      summary: Conjunto de informações de Câmbio para taxa online.
      operationId: exchangeGetOnlineRate
      description: |-
        As instituições autorizadas a operar em câmbio que disponibilizam em seus canais digitais a possibilidade de contratação ou a informação de taxa de câmbio devem retornar as condições no momento da consulta, sendo admitida uma defasagem máxima de atualização de 5 minutos em relação a seus canais digitais.

        Já as demais instituições participantes do Open Finance autorizadas a operar em câmbio podem adotar as janelas de consulta da PTAX como frequência mínima de atualização das informações retornadas neste serviço.
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          $ref: '#/components/responses/OKResponseExchangeOnlineRate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '529':
          $ref: '#/components/responses/SiteIsOverloaded'
  /vet-values:
    get:
      tags:
        - Exchange VET Value
      summary: Conjunto de informações de Câmbio para valor do VET.
      operationId: exchangeGetVetValue
      description: 'Método para disponibilizar os VETs praticados pela instituição nas operações de câmbio, agrupados por tipo de operação (compra ou venda), moeda, forma de entrega, faixas de valores e público-alvo (pessoa física, pessoa jurídica ou ambos).'
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          $ref: '#/components/responses/OKResponseExchangeVetValue'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '529':
          $ref: '#/components/responses/SiteIsOverloaded'
components:
  schemas:
    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'
      additionalProperties: false
    OpenDataMeta:
      type: object
      description: Meta informações referente à API requisitada.
      required:
        - totalRecords
        - totalPages
      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
      additionalProperties: false
    OKResponseExchangeOnlineRate:
      type: object
      required:
        - data
        - links
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ExchangeOnlineRate'
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/OpenDataMeta'
      additionalProperties: false
    OKResponseExchangeVetValue:
      type: object
      required:
        - data
        - links
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ExchangeVetValue'
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/OpenDataMeta'
      additionalProperties: false
    ExchangeOnlineRate:
      type: object
      description: Conjunto de informações referentes às informações de câmbio
      required:
        - participant
        - foreignCurrency
        - deliveryForeignCurrency
        - transactionType
        - transactionCategory
        - value
        - targetAudience
        - valueUpdateDateTime
        - disclaimer
      properties:
        participant:
          $ref: '#/components/schemas/Participant'
        foreignCurrency:
          $ref: '#/components/schemas/CurrencyCode'
        deliveryForeignCurrency:
          $ref: '#/components/schemas/EnumExchangeDeliveryForeignCurrency'
        transactionType:
          $ref: '#/components/schemas/EnumExchangeTransactionType'
        transactionCategory:
          $ref: '#/components/schemas/EnumExchangeTransactionCategory'
        targetAudience:
          $ref: '#/components/schemas/EnumDistinctTargetAudienceExchange'
        value:
          type: string
          maxLength: 22
          minLength: 8
          pattern: '^\d{1,15}\.\d{6}$'
          example: '0.019800'
          description: Valor da operação.
        valueUpdateDateTime:
          type: string
          format: date-time
          maxLength: 20
          example: '2017-07-21T17:32:28Z'
          description: Data e hora da última atualização da cotação.
          pattern: '(^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\d|2[0123]):(?:[012345]\d):(?:[012345]\d)Z$)'
        disclaimer:
          type: string
          description: 'Disclaimer informando que a taxa apresentada é somente informativa, para a contratação de uma operação, deverá ser consultado o canal correspondente de cada instituição.'
          example: 'Informamos que esta taxa é estimada e exclusiva para fins de Open Finance,  não sendo válida para a contratação de operações de câmbio. Para obter a taxa para fechamento do câmbio, pedimos consultar os canais disponíveis para contratação.'
      example:
        participant:
          brand: Organização
          name: Organização A1
          cnpjNumber: '13456789000112'
          urlComplementaryList: 'https://empresaa1.com/companies'
        foreignCurrency: USD
        deliveryForeignCurrency: TELETRANSMISSAO_SWIFT
        transactionType: COMPRA
        transactionCategory: COMERCIO_EXTERIOR
        targetAudience: PESSOA_NATURAL
        value: '0.019800'
        valueUpdateDateTime: '2017-07-21T17:32:28Z'
        disclaimer: 'Informamos que esta taxa é estimada e exclusiva para fins de Open Finance,  não sendo válida para a contratação de operações de câmbio. Para obter a taxa para fechamento do câmbio, pedimos consultar os canais disponíveis para contratação.'
      additionalProperties: false
    ExchangeVetValue:
      type: object
      description: Conjunto de informações referentes às informações de câmbio
      required:
        - participant
        - transactionType
        - foreignCurrency
        - deliveryForeignCurrency
        - rangeTransactionCategory
        - vetAmount
        - targetAudience
      properties:
        participant:
          $ref: '#/components/schemas/Participant'
        transactionType:
          $ref: '#/components/schemas/EnumExchangeTransactionType'
        foreignCurrency:
          $ref: '#/components/schemas/CurrencyCode'
        deliveryForeignCurrency:
          $ref: '#/components/schemas/EnumExchangeDeliveryForeignCurrency'
        rangeTransactionCategory:
          $ref: '#/components/schemas/EnumExchangeRangeTransactionCategory'
        targetAudience:
          $ref: '#/components/schemas/EnumDistinctTargetAudienceExchange'
        vetAmount:
          $ref: '#/components/schemas/ExchangeNoIdentificationFrequencyDistribution'
      additionalProperties: false
    ExchangeNoIdentificationFrequencyDistribution:
      type: object
      description: |
        Distribuição por frequência.  
        É necessário que as Instituições Financeiras desconsiderem os valores de VET negativo no cálculo de vetAmount.
      required:
        - prices
        - minimum
        - maximum
      properties:
        prices:
          type: array
          description: Distribuição dos preços.
          items:
            $ref: '#/components/schemas/ExchangeFrequencyDistributionPrice'
          minItems: 4
          maxItems: 4
          example:
            - interval: 1_FAIXA
              value: '0.020300'
              operationRate: '0.500000'
            - interval: 2_FAIXA
              value: '0.030600'
              operationRate: '0.100000'
            - interval: 3_FAIXA
              value: '0.034300'
              operationRate: '0.300000'
            - interval: 4_FAIXA
              value: '0.246800'
              operationRate: '0.100000'
        minimum:
          type: string
          description: Valor mínimo.
          minLength: 8
          maxLength: 22
          pattern: '^\d{1,15}\.\d{6}$'
          example: '0.010000'
        maximum:
          type: string
          description: Valor máximo.
          minLength: 8
          maxLength: 22
          pattern: '^\d{1,15}\.\d{6}$'
          example: '0.300000'
      additionalProperties: false
    ExchangeFrequencyDistributionPrice:
      type: object
      required:
        - interval
        - value
        - operationRate
      properties:
        interval:
          $ref: '#/components/schemas/EnumInterval'
        value:
          type: string
          description: Mediana.
          example: '0.020300'
          minLength: 8
          maxLength: 22
          pattern: '^\d{1,15}\.\d{6}$'
        operationRate:
          type: string
          description: Percentual de Operação.
          example: '0.500000'
          minLength: 8
          maxLength: 8
          pattern: '^\d{1}\.\d{6}$'
      additionalProperties: false
    OnlineRate:
      type: object
      description: Taxa disponibilizada (taxa online) pelas instituições no formato D+0/D+2 (valor U$500 operações câmbio pronto) separado por moeda dólar e euro compra e venda PF/PJ.
      required:
        - foreignCurrency
        - deliveryForeignCurrency
        - transactionType
        - transactionCategory
        - value
        - targetAudience
        - valueUpdateDateTime
      properties:
        foreignCurrency:
          $ref: '#/components/schemas/CurrencyCode'
        deliveryForeignCurrency:
          $ref: '#/components/schemas/EnumExchangeDeliveryForeignCurrency'
        transactionType:
          $ref: '#/components/schemas/EnumExchangeTransactionType'
        transactionCategory:
          $ref: '#/components/schemas/EnumExchangeTransactionCategory'
        targetAudience:
          $ref: '#/components/schemas/EnumDistinctTargetAudienceExchange'
        value:
          type: string
          maxLength: 7
          minLength: 3
          pattern: '^\d{1}\.\d{1,5}$'
          example: '5.5023'
          description: Valor da operação.
        valueUpdateDateTime:
          type: string
          format: date-time
          maxLength: 20
          example: '2017-07-21T17:32:28Z'
          description: Data e hora da última atualização da cotação.
          pattern: '(^(\d{4})-(1[0-2]|0?[1-9])-(3[01]|[12][0-9]|0?[1-9])T(?:[01]\d|2[0123]):(?:[012345]\d):(?:[012345]\d)Z$)'
      additionalProperties: false
    EnumExchangeDeliveryForeignCurrency:
      type: string
      description: 'A classificação da forma de operação, conforme Resolução BCB nº 277 de 31/12/2022 ou outro normativo que a revogue. (Vide Enum)<br><ul><li>ESPECIE</li><li>CARTAO_PRE_PAGO</li><li>TELETRANSMISSAO_SWIFT</li></ul>'
      enum:
        - ESPECIE
        - CARTAO_PRE_PAGO
        - TELETRANSMISSAO_SWIFT
      example: CARTAO_PRE_PAGO
    EnumExchangeRangeTransactionCategory:
      type: string
      description: |
        Faixa de valor da operação (equivalente em USD), conforme Instrução

        Normativa BCB 184, de 12 Novembro de 2021.
      enum:
        - '0,01_200'
        - '200,01_500'
        - '500,01_1.000'
        - '1.000,01_3.000'
        - '3.000,01_10.000'
        - '10.000,01_30.000'
        - '30.000,01_100.000'
      example: '0,01_200'
    EnumExchangeTransactionCategory:
      type: string
      description: 'A classificação do tipo de operação, conforme Resolução BCB nº 277 de 31/12/2022 ou outro normativo que a revogue.'
      enum:
        - COMERCIO_EXTERIOR
        - TRANSPORTE
        - SEGUROS
        - VIAGENS_INTERNACIONAIS
        - TRANSFERENCIAS_UNILATERAIS
        - SERVICOS_DIVERSOS
        - RENDAS_CAPITAIS
        - CAPITAIS_BRASILEIROS
        - CAPITAIS_ESTRANGEIROS
        - PRESTACAO_SERVICO_PAGAMENTO_OU_TRANSFERENCIA_INTERNACIONAL_EFX
      example: COMERCIO_EXTERIOR
    EnumExchangeTransactionType:
      type: string
      description: |
        Determina se o Banco está comprando ou vendendo a moeda estrangeira nas operações
        spot,  que se liquidam em até dois dias (não aplica-se a operações futuras. (Vide Enum)
        - Compra
        - Venda
      enum:
        - COMPRA
        - VENDA
      example: COMPRA
    EnumDistinctTargetAudienceExchange:
      type: string
      description: 'Público alvo. Em casos em que a instituição não possua taxas de câmbio diferenciadas para pessoa natural e jurídica utilizar a opção:PESSOA_NATURAL_JURIDICA.'
      enum:
        - PESSOA_NATURAL
        - PESSOA_JURIDICA
        - PESSOA_NATURAL_JURIDICA
      example: PESSOA_JURIDICA
    EnumInterval:
      type: string
      description: Faixas de frequência
      enum:
        - 1_FAIXA
        - 2_FAIXA
        - 3_FAIXA
        - 4_FAIXA
      example: 1_FAIXA
    CnpjNumber:
      type: string
      description: 'O CNPJ corresponde ao número de inscrição no Cadastro de Pessoa Jurídica. Deve-se ter apenas os números do CNPJ, sem máscara.'
      maxLength: 14
      pattern: '^[0-9A-Z]{12}[0-9]{2}$'
      example: '13456789000112'
    Participant:
      type: object
      description: Conjunto de informações relativas ao participante do produto de Open Finance
      required:
        - brand
        - name
        - cnpjNumber
      properties:
        brand:
          type: string
          description: 'Nome da marca reportada pelo participante do Open Finance. O conceito a que se refere a ''marca'' é em essência uma promessa da empresa em fornecer uma série específica de atributos, benefícios e serviços uniformes aos clientes.'
          pattern: '[\w\W\s]*'
          maxLength: 80
          example: Organização
        name:
          type: string
          description: Nome do participante do Open Finance.
          pattern: '[\w\W\s]*'
          maxLength: 80
          example: Organização A1
        cnpjNumber:
          $ref: '#/components/schemas/CnpjNumber'
        urlComplementaryList:
          type: string
          format: url
          description: |
            Espera-se que valor de retorno, após acesso ao link ‘urlComplementaryList’, deve ser array de objeto com a estrutura abaixo:

            - ‘name’ com o valor contido no campo ‘LegalEntityName’ conforme cadastro no diretório;

            - 'cnpjNumber' com o valor contido no campo CNPJ (‘RegistrationNumber’) correspondente a esta instituição;

            - Ambos do tipo string;

            - Ambos obrigatórios.
          maxLength: 1024
          example: 'https://empresaa1.com/companies'
      additionalProperties: false
    CurrencyCode:
      type: string
      pattern: '^[A-Z]{3}$'
      maxLength: 3
      description: 'Moeda referente ao valor monetário, seguindo o modelo ISO-4217.'
      example: BRL
    OpenDataResponseError:
      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:
          $ref: '#/components/schemas/OpenDataMeta'
      additionalProperties: false
  parameters:
    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.
      schema:
        type: integer
        default: 25
        minimum: 1
        format: int32
        maximum: 1000
  responses:
    OKResponseExchangeOnlineRate:
      description: Dados de operações de câmbio da instituição obtidos com sucesso.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OKResponseExchangeOnlineRate'
    OKResponseExchangeVetValue:
      description: Dados de operações de câmbio da instituição obtidos com sucesso.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OKResponseExchangeVetValue'
    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/OpenDataResponseError'
    NotFound:
      description: O recurso solicitado não existe ou não foi implementado
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OpenDataResponseError'
    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/OpenDataResponseError'
    TooManyRequests:
      description: 'A operação foi recusada, pois muitas solicitações foram feitas dentro de um determinado período ou o limite de requisições concorrentes foi atingido.'
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OpenDataResponseError'
    InternalServerError:
      description: Ocorreu um erro no gateway da API ou no microsserviço
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OpenDataResponseError'
    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
              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'