BEbelvo
Exchanges

Retrieve exchanges for a link

{% admonition type="warning" name="Coming Soon" %} This endpoint is currently undergoing development. As such, minor changes or bugs may occur. If you encounter any issues, please contact your Belvo representative. {% /admonition %}

Retrieve exchange operations for an existing link. By default, we retrieve exchange data for the last 365 days.

Note: When you retrieve exchanges, we automatically retrieve the exchange history for each exchange operation found.

post/api/br/exchanges/

Request

Query parameters

omitstring

Omit certain fields from being returned in the response. For more information, see our <a href="https://developers.belvo.com/docs/searching-and-filtering" target="_blank">Filtering responses</a> DevPortal article.

fieldsstring

Return only the specified fields in the response. For more information, see our <a href="https://developers.belvo.com/docs/searching-and-filtering" target="_blank">Filtering responses</a> DevPortal article.

Request body

linkstring uuid required

The link.id you want to retrieve information for.

date_fromstring date

The starting date for which you want to retrieve exchange data, in YYYY-MM-DD format. If not provided, we retrieve data for the last 365 days.

date_tostring date

The ending date for which you want to retrieve exchange data, in YYYY-MM-DD format. If not provided, we retrieve data up to today.

save_databoolean

Indicates whether or not to persist the data in Belvo. By default, this is set to true and we return a 201 Created response.

When set to false, the data won't be persisted and we return a 200 OK response.

Example request

{
  "link": "c81a1dea-6dd6-4999-8b9f-541ee8197058",
  "date_from": "2022-01-01",
  "date_to": "2022-12-31",
  "save_data": true
}

Response

OK - Exchanges Retrieved (when save_data=false)

idstring uuid required

Belvo's unique identifier for the current item.

linkstring uuid nullable required

The link.id the data belongs to.

created_atstring date-time required

The ISO-8601 timestamp of when the data point was created in Belvo's database.

collected_atstring date-time required

The ISO-8601 timestamp when the data point was collected.

operation_identifierstring required

The network's unique identifier for the exchange operation.

operation_numberstring nullable

The 12-digit operation registration number from the Brazil Central Bank (Bacen). This can be null if the operation has not yet been registered.

operation_type'COMPRA' | 'VENDA' required

The type of exchange operation.

We return one of the following enum values:

  • COMPRA - Buy (client is buying foreign currency)
  • VENDA - Sell (client is selling foreign currency)
operation_requested_atstring date-time required

The ISO-8601 timestamp when the exchange operation was contracted.

authorized_institution_identifierinteger required

The CNPJ of the institution authorized to conduct the operation.

authorized_institution_namestring required

The name of the authorized institution.

intermediary_institution_identifierinteger nullable

The CNPJ of the intermediary institution, if one was used.

intermediary_institution_namestring nullable

The name of the intermediary institution. Must be present if intermediary_institution_identifier is available.

operation_due_datestring date required

The currently scheduled settlement date for the operation, in YYYY-MM-DD format.

Note: This field is updated if any changes are made to the exchange operation.

local_operation_tax_amountnumber float required

The exchange rate applied to the operation.

local_operation_tax_currencystring required

The three-letter currency code (ISO-4217) for the exchange rate.

local_operation_value_amountnumber float required

The total value of the operation in local currency.

local_operation_value_currencystring required

The three-letter currency code (ISO-4217) for the local currency.

foreign_operation_value_amountnumber float required

The total value of the operation in the foreign currency.

foreign_operation_value_currencystring required

The three-letter currency code (ISO-4217) for the foreign currency.

operation_outstanding_balance_amountnumber float nullable

The outstanding balance to be settled, in the foreign currency. In the case that the exchange operation is scheduled to be settled within two days of the operation_requested_at, this value can be null.

operation_outstanding_balance_currencystring nullable

The currency of the outstanding balance. Required if operation_outstanding_balance_amount is not null.

tev_amount_amountnumber float nullable

The "All-in Rate" (Valor Efetivo Total/Total Effective Cost), representing the total cost of the operation. Required when the operation is scheduled to be settled within two days of the operation_requested_at and does not exceed $100,000 USD.

tev_amount_currencystring nullable

The currency of the VET (always BRL). Required if tev_amount_amount is not null.

local_currency_advance_percentagenumber float nullable

The percentage of the foreign currency value that was granted to the client in advance. In the case that the exchange operation is scheduled to be settled within two days of the operation_requested_at, this value can be null.

settlement_method'CONTA_DEPOSITO_MOEDA_ESTRANGEIRA_PAIS' | 'CONTA_DEPOSITO_OU_PAGAMENTO_EXPORTADOR_INSTITUICAO_EXTERIOR' | 'ESPECIE_CHEQUES_VIAGEM' | 'CARTAO_PREPAGO' | 'TELETRANSMISSAO' | 'SEM_MOVIMENTACAO_VALORES' | 'DEMAIS' | 'CARTA_CREDITO_A_VISTA' | 'CARTA_CREDITO_A_PRAZO' | 'CONTA_DEPOSITO' | 'CHEQUE' | 'TITULOS_VALORES' | 'SIMBOLICA' | 'CONTA_DEPOSITO_EXPORTADOR_MANTIDA_NO_EXTERIOR' | 'CONVENIO_PAGAMENTOS_E_CREDITOS_RECIPROCOS' | 'OUTRO_NAO_MAPEADO_OFB' | 'null' nullable required

The method of delivery for the foreign currency.

We return one of the following enum values:

  • CARTA_CREDITO_A_VISTA (Code 10) - Sight letter of credit
  • CARTA_CREDITO_A_PRAZO (Code 15) - Term letter of credit
  • CONTA_DEPOSITO (Code 20) - Deposit account
  • CONTA_DEPOSITO_MOEDA_ESTRANGEIRA_PAIS (Code 21) - Foreign currency deposit account in country
  • CONTA_DEPOSITO_EXPORTADOR_MANTIDA_NO_EXTERIOR (Code 22) - Exporter's deposit account maintained abroad
  • CONTA_DEPOSITO_OU_PAGAMENTO_EXPORTADOR_INSTITUICAO_EXTERIOR (Code 23) - Deposit account or payment to exporter at foreign institution
  • CONVENIO_PAGAMENTOS_E_CREDITOS_RECIPROCOS (Code 25) - Reciprocal payments and credits agreement
  • CHEQUE (Code 30) - Check
  • ESPECIE_CHEQUES_VIAGEM (Code 50) - Cash or traveler's checks
  • CARTAO_PREPAGO (Code 55) - Prepaid card
  • TELETRANSMISSAO (Code 65) - Wire transfer
  • TITULOS_VALORES (Code 75) - Securities/bonds
  • SIMBOLICA (Code 90) - Symbolic
  • SEM_MOVIMENTACAO_VALORES (Code 91) - No movement of funds
  • DEMAIS (Code 99) - Others
  • OUTRO_NAO_MAPEADO_OFB - Other not mapped by Open Finance Brazil
  • null
operation_category_codestring required

The 5-digit Central Bank code that classifies the "nature" of the operation.

This code must comply with the nature codes referenced in Resolution 277 or Circular 3690, as applicable to the exchange contract.

Example response

[
  {
    "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
    "link": "30cb4806-6e00-48a4-91c9-ca55968576c8",
    "created_at": "2022-02-09T08:45:50.406032Z",
    "collected_at": "2022-02-09T08:45:50.406032Z",
    "operation_identifier": "92792126019929240",
    "operation_number": "393874649456",
    "operation_type": "COMPRA",
    "operation_requested_at": "2023-03-07T08:30:00Z",
    "authorized_institution_identifier": 11225860000140,
    "authorized_institution_name": "AGENCIA CORRETORA",
    "intermediary_institution_identifier": 11225860000140,
    "intermediary_institution_name": "AGENCIA CORRETORA",
    "operation_due_date": "2018-02-15",
    "local_operation_tax_amount": 1.3,
    "local_operation_tax_currency": "BRL",
    "local_operation_value_amount": 1000.04,
    "local_operation_value_currency": "BRL",
    "foreign_operation_value_amount": 1000.04,
    "foreign_operation_value_currency": "USD",
    "operation_outstanding_balance_amount": 1000.04,
    "operation_outstanding_balance_currency": "USD",
    "tev_amount_amount": 1000.000004,
    "tev_amount_currency": "BRL",
    "local_currency_advance_percentage": 0.12,
    "settlement_method": "CARTA_CREDITO_A_PRAZO",
    "operation_category_code": "90302"
  }
]

Changes

No recorded changes to this operation across all 5 revisions of this API.