API Ciudades v1
Descripción general
Recurso de la capa de experiencia encargado de recuperar información de ciudades desde el API BotService. Registra las solicitudes y respuestas, y captura datos clave para auditoría y control.
Categoría de Negocio: Movilidad
Capa de experiencia
Endpoint y método
GET [https://bot-xapi-services-qa.us-e2.cloudhub.io/v1/parameters/cities](https://bot-xapi-services-qa.us-e2.cloudhub.io/v1/parameters/cities)Especificación (enlace si existe)
Estable
Descripción funcional
Consulta el listado de ciudades disponibles y sus datos asociados, integrándose con BotService para registrar auditoría de consumo.
Capa de proceso
No aplica.
Capa de sistema
Endpoint y método
POST [https://bot-sapi-services-dev.us-e2.cloudhub.io/bot/parameters/cities/v1](https://bot-sapi-services-dev.us-e2.cloudhub.io/bot/parameters/cities/v1)Especificación
Descripción funcional
Consulta el servicio BotService para obtener información de ciudades, procesando solicitudes cifradas hacia:
[http://botdev.portallteqa.p.azurewebsites.net/api/parameters/v1/getcities](http://botdev.portallteqa.p.azurewebsites.net/api/parameters/v1/getcities)Ejemplos de Request/Response
Solicitud (request)
json
GET https://bot-xapi-services-qa.us-e2.cloudhub.io/v1/parameters/citiesRespuesta exitosa (200)
json
{
"responseHeader": {
"system": {
"name": "Tienda",
"correlationID": "TIENDA-2025-06-11-10-16-57-e3060a3b-29b89d79-c880b647-c4bf4dfe",
"processingServer": "Tienda"
},
"service": {
"status": "OK",
"responseDate": "2025-06-15T15:49:46.1028033Z",
"statusDetail": [
{
"errorCode": "OK_01",
"errorDetailCode": "Se consultaron las ciudades exitosamente",
"errorMessage": "La solicitud TIENDA-2025-06-11-10-16-57-e3060a3b-29b89d79-c880b647-c4bf4dfe fue exitosa"
}
]
},
"property": []
},
"responseBody": [
{
"city": "CHIGORODO",
"cityDANE": "05172",
"cobertures": {
"coberture": true,
"delivery": [
{
"daysOL": 6,
"hoursOL": 0,
"type": "BASICA"
}
],
"operator": "DHL"
},
"country": "Colombia",
"countryISO": "CO",
"departament": "ANTIOQUIA",
"departmentDANE": "05"
}
]
}Respuesta de error (4xx/5xx)
json
{
"status": 409,
"code": "INVALID_FIELD",
"message": {
"message": ""
},
"messageServer": "ERROR at Row:1:Column:212 No such column 'Segmento' on entity 'Account'.",
"cause": [
{
"origin": "bot-xapi-services",
"message": "org.mule.extension.http.api.request.validator.ResponseValidatorTypedException"
}
]
}json
{
"status": 500,
"code": "INTERNAL_SERVER_ERROR",
"message": {
"message": "HTTP GET on resource 'http://0.0.0.0:8080/XXXXX/services/xxxxxx' failed: internal server error (500)."
},
"messageServer": "Descripcion del error. Detalle de porque fallo.",
"cause": [
{
"origin": "bot-xapi-services",
"message": "org.mule.extension.http.api.request.validator.ResponseValidatorTypedException"
}
]
}Esquemas de datos
Respuesta exitosa (200)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| responseHeader.system.name | String | Sí | Nombre del sistema que responde. |
| responseHeader.system.correlationID | Number | Sí | ID de correlación. |
| responseHeader.system.processingServer | String | No | Servidor de procesamiento. |
| responseHeader.service.status | String | Sí | Estado de la respuesta. |
| responseHeader.service.responseDate | String | Sí | Fecha y hora de la respuesta. |
| responseHeader.service.statusDetail.errorCode | String | Sí | Código del resultado. |
| responseHeader.service.statusDetail.errorDetailCode | String | Sí | Detalle del código. |
| responseHeader.service.statusDetail.errorMessage | String | No | Mensaje descriptivo. |
| responseHeader.property | Object | No | Propiedades adicionales. |
| responseBody.city | String | Sí | Nombre de la ciudad. |
| responseBody.cityDANE | String | Sí | Código DANE de la ciudad. |
| responseBody.cobertures.coberture | String | Sí | Estado de cobertura. |
| responseBody.cobertures.delivery.daysOL | String | Sí | Días de entrega. |
| responseBody.cobertures.delivery.hoursOL | String | Sí | Horas de entrega. |
| responseBody.cobertures.delivery.type | String | Sí | Tipo de entrega. |
| responseBody.cobertures.operator | String | Sí | Operador logístico. |
| responseBody.country | String | Sí | País. |
| responseBody.countryISO | String | Sí | Código ISO del país. |
| responseBody.departament | String | Sí | Departamento. |
| responseBody.departmentDANE | String | No | Código DANE del departamento. |
Respuesta de error (4xx/5xx)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| code | String | Sí | Código HTTP asociado al error. |
| status | Number | Sí | Código estandarizado del error. |
| message.message | String | No | Mensaje comprensible para humanos. |
| messageServer | String | Sí | Descripción técnica del error. |
| cause.origin | String | Sí | Nombre de la API o capa generadora del error. |
| cause.message | String | Sí | Descripción técnica del error. |
Diagramas
Diagrama de flujo
Espacio reservado para el diagrama de flujo.
Diagrama de secuencia
Espacio reservado para el diagrama de secuencia.
Políticas de seguridad
Autenticación
- OAuth 2.0 Access Token Enforcement Using External Provider.
- Validación de token, vigencia y scope asociado al client_id.
- Respuesta de “Acceso denegado” si el token es inválido o no autorizado.
SLAs
- Puede incluir límite de 1000 req/min por cliente.
- Tiempos de respuesta sujetos a acuerdos establecidos.
Rate Limits
Anypoint Security:
- Longitud máxima de ruta: 4096 bytes.
- Longitud máxima de encabezado: 16384 bytes.
CloudHub 2.0:
- Tamaño máximo de URI: 4 KB.
- Longitud máxima del encabezado HTTP: 32 KB.
Errores comunes
- 409 INVALID_FIELD: Campo inválido en la solicitud.
- 500 INTERNAL_SERVER_ERROR: Error interno al procesar la solicitud.
Dependencias
Recepción de peticiones desde sistemas externos.
Envío a la capa de sistema:
https://bot-sapi-services-dev.us-e2.cloudhub.io/bot/parameters/cities/v1Comunicación con BotService:
http://botdev.portallteqa.p.azurewebsites.net/api/parameters/v1/getcities
Historial de cambios
| Versión | Fecha | Descripción |
|---|---|---|
| 1.0.0 | 16/06/2025 | Versión inicial con operación cities |