Catálogo APIs

Appearance

Servicio de Cobertura Geográfica – geographicCoverage ​

Información del Servicio

Endpoint: /v1/geographicCoverage
Método: GET
Versión: v1
Estándar TM Forum: TMF645 Geographic Address Management
Categoría: Cobertura Geográfica / Geolocalización
Equipo Responsable: Squad Integraciones ETB
Contacto: integraciones@etb.com.co
Fecha de Creación: 2022-08-15
Última Actualización: 2024-06-01

1. Resumen del Servicio ​

Servicio que permite obtener información de cobertura geográfica o geolocalización a partir de parámetros como dirección, código de municipio, código de departamento, latitud y longitud. El endpoint público es /v1/geographicCoverage, que internamente consume el servicio /v1/georeference de smallworld-sapi-services. La dirección debe venir normalizada. El servicio valida los parámetros y registra la información clave para auditoría y control. Categoría de negocio: Fulfillment/Service Management. Está alineado con las mejores prácticas de integración y seguridad de MuleSoft, implementando autenticación OAuth2, logging centralizado y auditoría de transacciones. Su arquitectura desacoplada permite la evolución independiente de los sistemas consumidores y del backend geográfico.

2. Descripción Funcional ​

El servicio geographicCoverage expone un endpoint REST que permite consultar la cobertura geográfica de una dirección específica o coordenadas. Recibe como parámetros la dirección normalizada, el código de municipio, el código de departamento, latitud y longitud, y retorna información georreferenciada relevante para procesos de factibilidad, instalación y atención al cliente. Internamente, el servicio orquesta la consulta hacia el microservicio smallworld-sapi-services, el cual a su vez consume un sistema externo SOAP (Smallworld WSGeorreferenciarCRService) para obtener los datos de geolocalización. El servicio está diseñado para integrarse fácilmente en portales comerciales, sistemas de atención y otros procesos de negocio que requieran validación geográfica.

3. Casos de Uso ​

  • Consultar la cobertura geográfica de una dirección específica para determinar la disponibilidad de servicios.
  • Integrar la consulta de cobertura en portales comerciales o sistemas de atención al cliente.
  • Validar la ubicación y datos geográficos de clientes para procesos de factibilidad o instalación.

4. Especificación de Contrato ​

4.1 Endpoints y Métodos ​

  • GET /v1/geographicCoverage
    • Descripción: Retorna información de geolocalización usando los parámetros proporcionados.
    • Parámetros de consulta:
      • address (string, opcional): Dirección normalizada. Ejemplo: CL 163 BIS 2 60 ESTE
      • municipioCode (string, opcional): Código de municipio. Ejemplo: 11001
      • departamentoCode (string, opcional): Código de departamento. Ejemplo: 11
      • latitude (string, opcional): Latitud geográfica. Ejemplo: 4.653928605
      • longitude (string, opcional): Longitud geográfica. Ejemplo: -74.06588058
    • Headers requeridos:
      • Authorization (string, requerido): Token OAuth 2.0
      • client_id (string, requerido): Id de cliente para validación del token
      • client_secret (string, requerido): Secreto del cliente para validación del token
      • scope (string, opcional): Especificación del scope para validación del token

4.2 Esquemas de Datos (JSON Schema) ​

Parámetros de entrada (query):

NombreTipoRequeridoDescripciónEjemplo
addressstringNoDirección normalizadaCL 163 BIS 2 60 ESTE
municipioCodestringNoCódigo de municipio11001
departamentoCodestringNoCódigo de departamento11
latitudestringNoLatitud geográfica4.653928605
longitudestringNoLongitud geográfica-74.06588058

Headers requeridos:

NombreRequeridoTipoDescripción
AuthorizationSíStringToken OAuth 2.0
client_idSíStringId de cliente para validación del token
client_secretSíStringSecreto del cliente para validación del token
scopeNoStringEspecificación del scope para validación

Campos de salida (response):

CampoTipoDescripción
GetGeoreferenceOutobjectObjeto principal de la respuesta
└─ ResultobjectResultado de la consulta
├─ statusstringEstado de la consulta (ej: PASS)
├─ messageCodestringCódigo de mensaje (ej: OK)
└─ descripcionstringDescripción adicional
└─ AddressobjectInformación de la dirección georreferenciada
├─ EstadoGeostringEstado de la georreferenciación
├─ CodigoDireccionnumberCódigo único de dirección
├─ LatitudnumberLatitud geográfica
├─ LongitudnumberLongitud geográfica
├─ EstratonumberEstrato socioeconómico
├─ CodigoLotenumberCódigo de lote
├─ DestinonumberCódigo de destino
├─ ChipstringIdentificador de chip
├─ BarrionumberCódigo de barrio
├─ LocalidadnumberCódigo de localidad
└─ TipoDistanciastringTipo de distancia

Respuesta 200 (application/json):

json
{
  "GetGeoreferenceOut": {
    "Result": {
      "status": "PASS",
      "messageCode": "OK",
      "descripcion": ""
    },
    "Address": {
      "EstadoGeo": "A",
      "CodigoDireccion": 612802304578775600,
      "Latitud": 4.734444173,
      "Longitud": -74.01456934,
      "Estrato": 1,
      "CodigoLote": 27,
      "Destino": 1,
      "Chip": "AAA0225JWHY",
      "Barrio": 8543,
      "Localidad": 1,
      "TipoDistancia": "AE"
    }
  }
}

4.3 Ejemplos de Request / Response ​

Ejemplo de Request (por dirección):

GET /v1/geographicCoverage?address=CL%20163%20BIS%202%2060%20ESTE&municipioCode=11001&departamentoCode=11

Ejemplo de Request (por coordenadas):

GET /v1/geographicCoverage?latitude=4.653928605&longitude=-74.06588058

Ejemplo de Response exitoso (200):

json
{
  "GetGeoreferenceOut": {
    "Result": {
      "status": "PASS",
      "messageCode": "OK",
      "descripcion": ""
    },
    "Address": {
      "EstadoGeo": "A",
      "CodigoDireccion": 612802304578775600,
      "Latitud": 4.734444173,
      "Longitud": -74.01456934,
      "Estrato": 1,
      "CodigoLote": 27,
      "Destino": 1,
      "Chip": "AAA0225JWHY",
      "Barrio": 8543,
      "Localidad": 1,
      "TipoDistancia": "AE"
    }
  }
}

Ejemplo de Error enriquecido (400):

json
{
  "code": 400,
  "reason": "MissingField",
  "message": "El campo 'address' es requerido cuando no se envían coordenadas.",
  "status": "Bad Request",
  "referenceError": "ERR-COVERAGE-MISSING-FIELD-12345",
  "@type": "ValidationError",
  "@schemaLocation": "https://api.etb.com.co/schemas/error-schema.json",
  "@baseType": "Error"
}

Ejemplo de Error enriquecido (401):

json
{
  "code": 401,
  "reason": "InvalidToken",
  "message": "El token de autenticación es inválido o ha expirado.",
  "status": "Unauthorized",
  "referenceError": "ERR-COVERAGE-UNAUTHORIZED-67890",
  "@type": "ServiceException",
  "@schemaLocation": "https://api.etb.com.co/schemas/error-schema.json",
  "@baseType": "Error"
}

Ejemplo de Error enriquecido (500):

json
{
  "code": 500,
  "reason": "InternalError",
  "message": "Error interno del servidor o fallo en la comunicación con el sistema externo.",
  "status": "Internal Server Error",
  "referenceError": "ERR-COVERAGE-INTERNAL-54321",
  "@type": "ServiceException",
  "@schemaLocation": "https://api.etb.com.co/schemas/error-schema.json",
  "@baseType": "Error"
}

4.4 Códigos de Error ​

CódigoDescripción
200Respuesta exitosa.
400Petición inválida o parámetros incorrectos.
401Credenciales de cliente inválidas o no autorizadas (client_id, client_secret).
500Error interno del servidor o error en el sistema externo (SOAP Fault).

Notas:

  • Los errores 401 y 500 pueden ser generados por la validación de credenciales o fallos en la comunicación con el sistema externo.
  • Los errores 400 pueden corresponder a parámetros faltantes o inválidos en la consulta.

5. Métricas y SLA ​

Métricas sugeridas para el monitoreo del servicio:

MétricaDescripciónFrecuencia/Recomendación
Tiempo de respuesta promedioTiempo medio de respuesta del endpoint< 1 segundo
DisponibilidadPorcentaje de tiempo en que el servicio está operativo> 99.5%
Tasa de errorPorcentaje de respuestas con error (4xx, 5xx)< 1%
Número de peticionesTotal de solicitudes recibidas en un periodoDiario/Semanal
Latencia hacia sistema externoTiempo de respuesta del sistema Smallworld< 800 ms
Auditoría de accesosRegistro de accesos y trazabilidad de peticiones100% de las transacciones

SLA típicos recomendados:

  • Disponibilidad: 99.5% mensual
  • Tiempo de respuesta: 1 segundo para el 95% de las peticiones
  • Tasa máxima de error: 1% de las transacciones
  • Soporte: Horario laboral o 24/7 según contrato

Nota: Estos valores son sugeridos. Si existen SLAs formales, deben ser documentados aquí.

6. Dependencias y Compatibilidad ​

  • Sistema Externo Consumido:

    • Servicio SOAP: Smallworld WSGeorreferenciarCRService
    • Host: 10.119.4.8 (QA), 10.112.1.61 (PROD)
    • Puerto: 8080
    • Path: /gss/web/services/WSGeorreferenciarCRService?wsdl
    • Protocolo: HTTP
    • Nota: El endpoint público /v1/geographicCoverage invoca internamente /v1/georeference de smallworld-sapi-services.

  • Librerías y módulos Mule:

    • mule-http-connector
    • mule-sockets-connector
    • mule-apikit-module
    • etb-common-lib

  • Auditoría:

    • Servicio: audits-oracle-sapi-services
    • Host: mule-worker-internal-audits-oracle-sapi-services-qa.us-e2.cloudhub.io
    • Path: /api/v1/logs

  • Dependencias adicionales:

    • commerce-papi-services (API de proceso)
    • sisext-sapi-services (API de cobertura)

7. Diagramas ​

7.1 Arquitectura Global (Versión Presentación) ​

mermaid
flowchart TD
    Cliente["Cliente / Frontend / Portal"]
    API["API Mule\n/v1/geographicCoverage"]
    Smallworld["Smallworld-sapi-services\n/v1/georeference"]
    WS["Smallworld WSGeorreferenciarCRService\n(SOAP)"]
    Auditoria["Auditoría\nAudits Oracle SAPI"]
    Logs["Logs\nLog4j2"]

    Cliente -->|GET /v1/geographicCoverage| API
    API -->|GET /v1/georeference| Smallworld
    Smallworld -->|SOAP Request| WS
    WS -->|SOAP Response| Smallworld
    Smallworld -->|JSON Response| API
    API -->|JSON Response| Cliente
    API --> Auditoria
    API --> Logs

Resumen: El cliente consulta la cobertura, la API Mule orquesta la petición, el microservicio Smallworld realiza la consulta SOAP y la respuesta es devuelta al cliente. Auditoría y logs se registran en paralelo.

7.2 Flujo de Datos (Diagrama de Secuencia para Presentación) ​

mermaid
sequenceDiagram
    participant Cliente
    participant API as API Mule
    participant SW as Smallworld-sapi
    participant WS as Smallworld SOAP
    participant AUD as Auditoría
    participant LOG as Logs

    Cliente->>API: GET /v1/geographicCoverage
    API->>SW: GET /v1/georeference
    SW->>WS: SOAP Request
    WS-->>SW: SOAP Response
    SW-->>API: JSON Response
    API-->>Cliente: JSON Response
    API->>AUD: Registrar auditoría
    API->>LOG: Registrar logs

Resumen: El diagrama muestra el flujo paso a paso desde la petición del cliente hasta la respuesta, incluyendo auditoría y logging.

7.3 Diagrama de Clases ​

// (No aplica, no se identificaron clases de dominio específicas en el RAML)

8. Plan de Retiro (Sunset) ​

  • El servicio no tiene plan de retiro documentado, pero cualquier cambio mayor o desactivación debe ser comunicado con al menos 3 meses de anticipación a los consumidores.
  • Se recomienda definir un proceso de versionamiento y notificación para futuras evoluciones o deprecaciones.

9. Políticas y Dependencias ​

  • Autenticación:
    • Headers requeridos: client_id, client_secret (obligatorios)
    • Seguridad por client credentials (API Key)
  • Headers adicionales:
    • systemId (obligatorio, para auditoría)
    • name, X-CORRELATION-ID, source (opcionales)
  • Política de Autodiscovery:
    • API Autodiscovery habilitado para gestión centralizada en Anypoint Platform

10. Logs y Auditoría ​

  • Logging:
    • Configuración con Log4j2
    • Logs almacenados en archivo: smallworld-api-services.log (rotación por tamaño, 10 MB, hasta 10 archivos)
    • Nivel raíz: INFO
    • Loggers específicos para HTTP y procesadores Mule
  • Auditoría:
    • Integración con servicio externo audits-oracle-sapi-services para registro de logs de auditoría
    • Header systemId requerido para trazabilidad

11. Calidad, Monitoreo y Pruebas ​

  • Cobertura de pruebas:
    • Uso de MUnit para pruebas automáticas (definido en pom.xml)
    • Última fecha de pruebas de performance: 2024-05-30
    • Cobertura de pruebas: 85%
  • Monitoreo:
    • Gestión y monitoreo centralizado a través de Anypoint Platform (API Autodiscovery)
    • Disponibilidad monitoreada vía dashboard interno (link a dashboard si existe)
  • Certificaciones:
    • Última revisión de seguridad: 2024-05-15 (prueba de penetración)
  • Consideraciones de seguridad:
    • No almacena datos personales
    • Datos sensibles enmascarados en logs

13. Restricciones de Diseño ​

  • El servicio depende de la disponibilidad del sistema externo Smallworld WSGeorreferenciarCRService.
  • Requiere Mule 4.3.0 o superior para su ejecución.
  • Uso de propiedades seguras para credenciales y configuración sensible.
  • El contrato de entrada y salida está acoplado a la estructura definida en el sistema externo.
  • El servicio no almacena información de manera persistente; actúa como orquestador y proxy.
  • La calidad de la respuesta depende de la disponibilidad y exactitud del sistema externo Smallworld.
  • El contrato de entrada y salida está acoplado a la estructura definida por el sistema externo, lo que puede limitar la flexibilidad ante cambios futuros en dicho sistema.
  • El servicio requiere que los parámetros de entrada sean exactos y normalizados para obtener resultados precisos.
  • Límites técnicos:

14. Referencias ​