Localizaciones

Catálogos jerárquicos de países, estados, ciudades y códigos postales para construir el domicilio fiscal.

Estos endpoints sirven como catálogo de solo lectura para construir el objeto fiscalAddress de la petición de alta de una organización cliente. Cada nivel de la jerarquía se resuelve a partir del anterior: país → estado → ciudad → código postal. Los códigos que envías en fiscalAddress.countryCode, stateCode y cityCode deben provenir de este catálogo; si no, el alta responde 404.

Convenciones comunes

• Base URL Sandbox: https://api-sandbox.zertiban.com
• Headers requeridos en todas las llamadas:
  • Authorization: Bearer {access_token}
  • x-tenant-id: {businessUuid}

1. Listar países

GET/location/v1/countries

Devuelve todos los países soportados por Zertiban. Sin parámetros.

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

Respuesta (200):

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

Campo	Descripción
countries[i].code	Código ISO 3166 alpha-2. Este es el valor que envías como countryCode.
countries[i].name	Nombre del país.

2. Estados de un país

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

Devuelve los estados o provincias del país indicado.

Path parameters:

Parámetro	Tipo	Descripción
countryCode	String	Código ISO 3166 alpha-2 (ej. ES).

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

Respuesta (200):

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

Campo	Descripción
states[i].code	Código del estado (ISO 3166-2). Este es el valor que envías como stateCode.
states[i].name	Nombre del estado o provincia.

3. Ciudades de un estado

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

Devuelve las ciudades del estado indicado dentro del país.

Path parameters:

Parámetro	Tipo	Descripción
countryCode	String	Código ISO 3166 alpha-2 (ej. ES).
stateCode	String	Código del estado (ej. 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}"

Respuesta (200):

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

Campo	Descripción
cities[i].code	Código de la ciudad. Este es el valor que envías como cityCode.
cities[i].name	Nombre de la ciudad.

4. Códigos postales de una ciudad

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

Devuelve los códigos postales válidos dentro de la ciudad indicada. Útil para presentar sugerencias o validar el postalCode que se enviará en fiscalAddress.

Path parameters:

Parámetro	Tipo	Descripción
countryCode	String	Código ISO 3166 alpha-2 (ej. ES).
stateCode	String	Código del estado (ej. ES-AS).
cityCode	String	Código de la ciudad (ej. 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}"

Respuesta (200):

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

5. Resolución completa de una localización

GET/location/v1/locations

Resuelve la localización completa a partir de país, estado, ciudad y código postal. Ideal para validar en un solo paso que la combinación que vas a enviar en fiscalAddress es consistente.

Query parameters (todos obligatorios):

Parámetro	Tipo	Descripción
country	String	Código ISO 3166 alpha-2 (ej. ES).
state_code	String	Código del estado (ej. ES-AS).
city_code	String	Código de la ciudad (ej. ES-AS-OV).
postal_code	String	Código postal (ej. 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}"

Respuesta (200):

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

Un 404 en esta llamada indica que la combinación no existe (por ejemplo, un código postal que no pertenece a esa ciudad). En ese caso, revalida cada nivel con los endpoints anteriores.

Tabla resumen

Método	Endpoint	Descripción
GET	/location/v1/countries	Listar países
GET	/location/v1/countries/{countryCode}/states	Estados de un país
GET	/location/v1/countries/{countryCode}/states/{stateCode}/cities	Ciudades de un estado
GET	/location/v1/countries/{countryCode}/states/{stateCode}/cities/{cityCode}/postal-codes	Códigos postales de una ciudad
GET	/location/v1/locations?country=&state_code=&city_code=&postal_code=	Resolución completa de la ubicación

Errores frecuentes

Código	Causa típica
400	Falta algún parámetro obligatorio en la resolución completa.
401	Token expirado o credenciales inválidas.
403	x-tenant-id incorrecto o permisos insuficientes.
404	No existe la combinación de país, estado, ciudad y/o código postal solicitada.