Currency exchange

Retrieving all exchange rates

get

Retrieves all exchange rates. You can filter and sort the results by the fields, for example source or target currency.


Required scopes

  • currency.currency_read

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Note: This value must always be provided in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Query parameters
pageNumberinteger · min: 1Optional

The page number to be retrieved where the size of the pages is specified by the pageSize parameter. The number of the first page is 1.

Default: 1
pageSizeinteger · min: 1Optional

The number of documents being retrieved on one page.

Default: 60
sortstringOptional

Fields to sort the response data by following order of the parameters from left to right. Can contain multiple fields in the following format: field name:sort direction separated by a comma. The colon with sort direction parameter is redundant and descending order is taken only if it is equal to desc or DESC. Ascending order is considered in any other case. Sorting by name parameter works properly only if the Accept-Language header is set to a specific language or is empty with default language specified in the configuration service.

Example: name,code:desc
sourceCurrencystringOptional

Returns all exchange definitions for which the source currency matches the pattern. The contains operation is used for the parameter.

targetCurrencystringOptional

Returns all exchange definitions for which the target currency matches the pattern. The contains operation is used for the parameter.

Header parameters
X-Total-CountbooleanOptional

The flag indicates if the total count of items should be returned. The total count will be returned as a value of the X-Total-Count header.

Default: false
Responses
200
OK
application/json
get
GET /currency/{tenant}/exchanges HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
[
  {
    "code": "PLN_EUR",
    "sourceCurrency": "PLN",
    "targetCurrency": "EUR",
    "rate": "0.21"
  },
  {
    "code": "PLN_USD",
    "sourceCurrency": "PLN",
    "targetCurrency": "USD",
    "rate": "0.23"
  },
  {
    "code": "EUR_USD",
    "sourceCurrency": "EUR",
    "targetCurrency": "USD",
    "rate": "1.1"
  },
  {
    "code": "USD_EUR",
    "sourceCurrency": "USD",
    "targetCurrency": "EUR",
    "rate": "0.91"
  }
]

Creating a new exchange rate

post

Creates a new exchange rate between two currencies.

Note: Both the source and target currency codes must be compliant with the ISO-4217 standard (see https://www.iso.org/iso-4217-currency-codes.html) and must be defined in the system.


Required scopes

  • currency.currency_manage

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Note: This value must always be provided in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Body
sourceCurrencystringRequired

The source currency code. The currency symbol must consist of three capital letters and must be a valid ISO-4217 code (https://www.iso.org/iso-4217-currency-codes.html) defined in the system.

targetCurrencystringRequired

The target currency code. The currency symbol must consist of three capital letters and must be a valid ISO-4217 code (https://www.iso.org/iso-4217-currency-codes.html) defined in the system.

ratestringRequired

Represents the exchange rate.

The value of the field is represented by a number where the cent part is separated by a comma. For example 1.09. The cent part is not limited just to two digits. A rate with any precision can be returned. For example: 1.091934212

Responses
201
Created
application/json
post
POST /currency/{tenant}/exchanges HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 61

{
  "sourceCurrency": "USD",
  "targetCurrency": "EUR",
  "rate": "0.91"
}
{
  "code": "text"
}

Retrieving an exchange rate by code

get

Retrieves a currency exchange rate definition by code.


Required scopes

  • currency.currency_read

Authorizations
Path parameters
codestringRequired

Identifier of the exchange rate definition. The identifier consists of source currency, underscore, and a target currency.

tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Note: This value must always be provided in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Responses
200
Exchange rate returned
application/json
get
GET /currency/{tenant}/exchanges/{code} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
{
  "code": "USD_EUR",
  "sourceCurrency": "USD",
  "targetCurrency": "EUR",
  "rate": "0.91"
}

Updating an exchange rate by code

put

Updates an existing exchange rate by code.

Note: The exchange rate code, source, and target currencies are immutable, so they cannot be changed in this request. Only the rate field can be changed.


Required scopes

  • currency.currency_manage

Authorizations
Path parameters
codestringRequired

Identifier of the exchange rate definition. The identifier consists of source currency, underscore, and a target currency.

tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Note: This value must always be provided in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Body
ratestringRequired

Represents the exchange rate.

The value of the field is represented by a number where the cent part is separated by a comma. For example, 1.09. The cent part is not limited just to two digits. A rate with any precision can be returned. For example: 1.09193421

Responses
204
Exchange rate updated
put
PUT /currency/{tenant}/exchanges/{code} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 40

{
  "rate": "0.91",
  "metadata": {
    "version": 1
  }
}

No content

Deleting an exchange rate

delete

Deletes the exchange rate definition by the provided code. If given definition does not exist in the system, the http code 204 will be returned.


Required scopes

  • currency.currency_manage

Authorizations
Path parameters
codestringRequired

Identifier of the exchange rate definition. The identifier consists of source currency, underscore, and a target currency.

tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Note: This value must always be provided in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Responses
204
Exchange rate deleted
delete
DELETE /currency/{tenant}/exchanges/{code} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Was this helpful?