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

Required scopes

This endpoint requires the following scopes:

• : The scope allows you to retrieve currencies and currency exchanges.

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

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

401

Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.

application/json

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

application/json

500

Internal Service Error occurred.

application/json

get

/currency/{tenant}/exchanges

HTTPcURLJavaScriptPython

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 (https://www.iso.org/iso-4217-currency-codes.html) and must be defined in the system.

---

Required scopes

• currency.currency_manage

Required scopes

This endpoint requires the following scopes:

• : The scope allows you to create, update, and delete currencies and currency exchanges

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

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

application/json

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

400

Request was syntactically incorrect. Details will be provided in the response payload.

application/json

401

Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.

application/json

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

application/json

409

Conflict.

application/json

500

Internal Service Error occurred.

application/json

post

/currency/{tenant}/exchanges

HTTPcURLJavaScriptPython

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

Required scopes

This endpoint requires the following scopes:

• : The scope allows you to retrieve currencies and currency exchanges.

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

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

401

Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.

application/json

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

application/json

404

Resource has not been found.

application/json

500

Internal Service Error occurred.

application/json

get

/currency/{tenant}/exchanges/{code}

HTTPcURLJavaScriptPython

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

Required scopes

This endpoint requires the following scopes:

• : The scope allows you to create, update, and delete currencies and currency exchanges

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

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

application/json

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

400

Request was syntactically incorrect. Details will be provided in the response payload.

application/json

401

Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.

application/json

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

application/json

404

Resource has not been found.

application/json

409

Conflict.

application/json

500

Internal Service Error occurred.

application/json

put

/currency/{tenant}/exchanges/{code}

HTTPcURLJavaScriptPython

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

Required scopes

This endpoint requires the following scopes:

• : The scope allows you to create, update, and delete currencies and currency exchanges

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

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

401

Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.

application/json

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

application/json

500

Internal Service Error occurred.

application/json

delete

/currency/{tenant}/exchanges/{code}

HTTPcURLJavaScriptPython

DELETE /currency/{tenant}/exchanges/{code} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content