Locations

Hierarchical catalogues of countries, states, cities and postal codes to build the fiscal address.

These endpoints act as a read-only catalogue for building the fiscalAddress object of the client organisation registration request. Each level of the hierarchy resolves from the previous one: country → state → city → postal code. The codes you send in fiscalAddress.countryCode, stateCode and cityCode must come from this catalogue; otherwise, registration responds with 404.

Common conventions

• Sandbox base URL: https://api-sandbox.zertiban.com
• Headers required on every call:
  • Authorization: Bearer {access_token}
  • x-tenant-id: {businessUuid}

1. List countries

GET/location/v1/countries

Returns every country supported by Zertiban. No parameters.

curl https://api-sandbox.zertiban.com/location/v1/countries \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Response (200):

{
  "countries": [
    { "code": "ES", "name": "Spain" },
    { "code": "PT", "name": "Portugal" }
  ]
}

Field	Description
countries[i].code	ISO 3166 alpha-2 code. This is the value you send as countryCode.
countries[i].name	Country name.

2. States of a country

GET/location/v1/countries/{countryCode}/states

Returns the states or provinces of the given country.

Path parameters:

Parameter	Type	Description
countryCode	String	ISO 3166 alpha-2 code (e.g. ES).

curl https://api-sandbox.zertiban.com/location/v1/countries/ES/states \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Response (200):

{
  "states": [
    { "code": "ES-AS", "name": "Asturias" },
    { "code": "ES-MD", "name": "Madrid" }
  ]
}

Field	Description
states[i].code	State code (ISO 3166-2). This is the value you send as stateCode.
states[i].name	State or province name.

3. Cities of a state

GET/location/v1/countries/{countryCode}/states/{stateCode}/cities

Returns the cities of the given state within the country.

Path parameters:

Parameter	Type	Description
countryCode	String	ISO 3166 alpha-2 code (e.g. ES).
stateCode	String	State code (e.g. ES-AS).

curl https://api-sandbox.zertiban.com/location/v1/countries/ES/states/ES-AS/cities \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Response (200):

{
  "cities": [
    { "code": "ES-AS-OV", "name": "Oviedo" },
    { "code": "ES-AS-GI", "name": "Gijón" }
  ]
}

Field	Description
cities[i].code	City code. This is the value you send as cityCode.
cities[i].name	City name.

4. Postal codes of a city

GET/location/v1/countries/{countryCode}/states/{stateCode}/cities/{cityCode}/postal-codes

Returns the postal codes valid within the given city. Use it to present suggestions or to validate the postalCode that will go into fiscalAddress.

Path parameters:

Parameter	Type	Description
countryCode	String	ISO 3166 alpha-2 code (e.g. ES).
stateCode	String	State code (e.g. ES-AS).
cityCode	String	City code (e.g. ES-AS-OV).

curl https://api-sandbox.zertiban.com/location/v1/countries/ES/states/ES-AS/cities/ES-AS-OV/postal-codes \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Response (200):

{
  "postalCodes": [{ "code": "33010" }, { "code": "33011" }]
}

5. Full location resolution

GET/location/v1/locations

Resolves the full location from country, state, city and postal code. Use it to validate in a single step that the combination you are about to send in fiscalAddress is consistent.

Query parameters (all required):

Parameter	Type	Description
country	String	ISO 3166 alpha-2 code (e.g. ES).
state_code	String	State code (e.g. ES-AS).
city_code	String	City code (e.g. ES-AS-OV).
postal_code	String	Postal code (e.g. 33010).

curl "https://api-sandbox.zertiban.com/location/v1/locations?country=ES&state_code=ES-AS&city_code=ES-AS-OV&postal_code=33010" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Response (200):

{
  "country": { "code": "ES", "name": "Spain" },
  "state": { "code": "ES-AS", "name": "Asturias" },
  "city": { "code": "ES-AS-OV", "name": "Oviedo" },
  "postalCode": { "code": "33010" }
}

A 404 on this call means the combination does not exist (for example, a postal code that does not belong to the city). If it happens, revalidate each level with the previous endpoints.

Summary table

Method	Endpoint	Description
GET	/location/v1/countries	List countries
GET	/location/v1/countries/{countryCode}/states	States of a country
GET	/location/v1/countries/{countryCode}/states/{stateCode}/cities	Cities of a state
GET	/location/v1/countries/{countryCode}/states/{stateCode}/cities/{cityCode}/postal-codes	Postal codes of a city
GET	/location/v1/locations?country=&state_code=&city_code=&postal_code=	Full location resolution

Common errors

Code	Typical cause
400	A required parameter is missing from the full-location call.
401	Expired token or invalid credentials.
403	Incorrect x-tenant-id or insufficient permissions.
404	The requested country / state / city / postal-code combination does not exist.