Country Service

Download OpenAPI specification:Download

E-mail: documentation@emporix.com

Holds a localized list of countries and regions to which the business may sell.

Key Features:

  • Provides a list of countries and regions

Key Benefits:

  • Holds a localized list of countries and regions to which the business may sell

Countries

Retrieving all countries

Retrieves all countries assigned to the tenant. You can filter, sort and paginate the results with query parameters.

SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

The tenant that the caller is acting upon.

Please note that this value is always lowercase.

query Parameters
pageNumber
integer >= 1
Default: 1

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

pageSize
integer >= 1
Default: 60

The number of documents being retrieved on the page.

sort
string

Fields to sort the response data by following order of the parameters from left to right. Can contain multiple fields in 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. While sorting by a localised field the following rule is taken into account: 1. If a localized field contains information about a language then the language should be used. For example name.en:ASC. In that case en language will be used for sorting the name property. The language suffix takes precedence over Accept-Language header. 2. If a localized field does not contain information about language then Accept-Language header will be used. For example name:ASC and Accept-Language: de. In that case de will be used for sorting the name property 3. If a localized field does not contain information about language and Accept-Language header contains * then default language from configuration service will be used as a language. For example name:ASC and Accept-Language: * and default language is pl then pl will be used as a language for name property 4. If a localized field does not contains information about language and Accept-Language header does not exists in the request then default language from configuration service will be used.

Example: sort=name,code:desc
name
string

Country names. When specified, only countries containing the specified names will be returned.

Important: See how the Accept-Language header influences this parameter:

  • If The Accept-Language header is set to *, you need to specify a language in this parameter.

    For example, if the Accept-Language header is set to * and you want to find English names containing the word "Isle", this parameter should be set to "name.en=Isle"

  • If the Accept-Language header is set to a particular language or not specified, you do not need to specify a language in this parameter.

    For example, if the Accept-Language header is set to en and you want to find names containing the word "Isle", this parameter should be set to "name=Isle"

Note: When filtering the results with this field, the contains operator is used. The operator is case-insensitive.

code
string

Country codes. When specified, only countries containing the specified code will be returned.

Note: When filtering the results with this field, the contains operator is used. The operator is case-insensitive.

active
string

Country active status, expressed as true or false. When specified, only countries with the active status will be returned.

Note: When filtering the results with this field, the equals operator is used.

regions
string

Country region codes. When specified, only countries containing the specified region codes will be returned.

Note: When filtering the results with this field, the contains operator is used.

header Parameters
Accept-Language
string

List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.

  • If the header is set to a particular language or a list of languages, all localized fields are retrieved as maps with the first matched language only.
  • If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
  • If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.
Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
X-Total-Count
boolean
Default: false

In order to get information how many entities meet a filter requirements, X-Total-Count header has been introduced. The header is optional and its default value is false. It the header is provided and it is true then total count is returned in the X-Total-Count response header. In both cases (X-Total-Count true, false or not provided), the response body has the same format (array of entities). In other words, the information about total count is returned on demand, depending of an existence of X-Total-Count header in a request. Therefore, the X-Total-Count header is not returned if an API consumer didn’t ask for it.

X-Version
required
string

The X-Version header with value v2 is required for the endpoint.

Responses
200

The request was successful. A list of countries is returned.

400

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

500

Internal Service Error occurred.

get/{tenant}/countries
Request samples 
Response samples 
application/json
[
  • {
    }
]
Retrieving a country
Retrieves a country by the specified code.


SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
The tenant that the caller is acting upon.


Please note that this value is always lowercase.


 
countryCode
required
string
Two-letter country code.


 
header Parameters
Accept-Language
string
List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.


Note: If not specified, localized fields will be retrieved in English.


 
 Example:  fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
X-Version
required
string
The X-Version header with value v2 is required for the endpoint.


 
Responses 
200
The request was successful. The requested country is returned.


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


404
The requested resource does not exist.


500
Internal Service Error occurred.


get/{tenant}/countries/{countryCode}
Request samples 
Response samples 
application/json
{
  • "code": "PL",
  • "name": {
    },
  • "regions": [
    ],
  • "metadata": {
    }
}
Update a country
Updates a country. It is possible to update active field only. The field indicates whether the given country is active for the tenant or not. Only active countries are visible in the system.


Required scopes


    

  • country.country_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
The tenant that the caller is acting upon.


Please note that this value is always lowercase.


 
countryCode
required
string
Two-letter country code.


 
header Parameters
X-Version
required
string
The X-Version header with value v2 is required for the endpoint.


 
Request Body schema: application/json
active
boolean
The field indicates whether the given country is active for the tenant or not. Only active countries are visible in the system.


 
object
 
Responses 
204
No Content


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


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


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


404
The requested resource does not exist.


500
Internal Service Error occurred.


patch/{tenant}/countries/{countryCode}
Request samples 
application/json
{
  • "active": true,
  • "metadata": {
    }
}
Response samples 
application/json
{
  • "status": "Bad Request",
  • "code": 400,
  • "message": "Tenant in the header is not matching with the one provided in the URI."
}
Regions
Get all regions
Get the filtered list of regions. The endpoint fully supports paging, sorting and filtering mechanism.  


SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
The tenant that the caller is acting upon.


Please note that this value is always lowercase.


 
query Parameters
pageNumber
integer  >= 1 
 Default:  1
The page number to be retrieved where the size of the pages must be specified by the pageSize parameter.
The number of the first page is 1.


 
pageSize
integer  >= 1 
 Default:  60
The number of documents being retrieved on the page.


 
sort
string
Fields to sort the response data by following order of the parameters from left to right. Can contain multiple fields in 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. While sorting by a localised field the following rule is taken into account:  1. If a localized field contains information about a language then the language should be used. For example name.en:ASC. In that case en language will be used for sorting the name property. The language suffix takes precedence over Accept-Language header.  2. If a localized field does not contain information about language then Accept-Language header will be used. For example name:ASC and Accept-Language: de. In that case de will be used for sorting the name property  3. If a localized field does not contain information about language and Accept-Language header contains * then default language from configuration service will be used as a language. For example name:ASC and Accept-Language: * and default language is pl then pl will be used as a language for name property  4. If a localized field does not contains information about language and Accept-Language header does not exists in the request then default language from configuration service will  be used.  


 
 Example:  sort=name,code:desc
name
string
Region names. When specified, only regions containing the specified names will be returned.


Important: See how the Accept-Language header influences this parameter:


    

  • If The Accept-Language header is set to *, you need to specify a language in this parameter.
    

    For example, if the Accept-Language header is set to * and you want to find English names containing the word "America", this parameter should be set to "name.en=America"
    

    • 

  • If the Accept-Language header is set to a particular language or not specified, you do not need to specify a language in this parameter.
    

    For example, if the Accept-Language header is set to en and you want to find names containing the word "America", this parameter should be set to "name=America"
    

    • 



Note: When filtering the results with this field, the contains operator is used. The operator is case-insensitive.


 
code
string
Region codes. When specified, only regions containing the specified codes will be returned.


Note: When filtering the results with this field, the contains operator is used.


 
header Parameters
Accept-Language
string
List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.


    

  • If the header is set to a particular language or a list of languages, all localized fields are retrieved as maps with the first matched language only.
    • 

  • If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
    • 

  • If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.
    • 



 
 Example:  fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
X-Total-Count
boolean
 Default:  false
In order to get information how many entities meet a filter requirements, X-Total-Count header has been introduced. The header is optional and its default value is false. It the header is provided and it is true then total count is returned in the X-Total-Count response header. In both cases (X-Total-Count true, false or not provided), the response body has the same format (array of entities). In other words, the information about total count is returned on demand, depending of an existence of X-Total-Count header in a request. Therefore, the X-Total-Count header is not returned if an API consumer didn’t ask for it.


 
X-Version
required
string
The X-Version header with value v2 is required for the endpoint.


 
Responses 
200
The request was successful. A list of regions is returned.


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


500
Internal Service Error occurred.


get/{tenant}/regions
Request samples 
Response samples 
application/json
[
  • {
    }
]
Retrieving a region
Retrieves a region by the specified code.


SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
The tenant that the caller is acting upon.


Please note that this value is always lowercase.


 
regionCode
required
string
The region code.


 
header Parameters
Accept-Language
string
List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.


    

  • If the header is set to a particular language or a list of languages, all localized fields are retrieved as maps with the first matched language only.
    • 

  • If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
    • 

  • If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.
    • 



 
 Example:  fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
X-Version
required
string
The X-Version header with value v2 is required for the endpoint.


 
Responses 
200
The request was successful. The requested region is returned.


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


404
The requested resource does not exist.


500
Internal Service Error occurred.


get/{tenant}/regions/{regionCode}
Request samples 
Response samples 
application/json
{
  • "code": "Europe",
  • "name": {
    },
  • "metadata": {
    }
}