GLS Pickup Client

1. Descripción general

gls-pickup-client es una librería cliente reutilizable (JAR) que encapsula la llamada a la API de GLS para consultar los puntos de recogida (parcel shops / pickup points) más próximos a una dirección dada. El proyecto no expone ningún endpoint REST propio; se publica en el registro de artefactos Maven interno y es consumido por otros microservicios del ecosistema Hawkers que necesiten ofrecer al cliente final la opción de recogida en punto GLS (por ejemplo, en checkout o en gestión de envíos).

La librería no implementa autenticación ni caché: se limita a construir un RestClient apuntando a la URL de GLS y a exponer la operación de búsqueda de puntos próximos mediante una interfaz declarativa @HttpExchange.

2. Información técnica

Propiedad	Valor
`artifactId`	`gls-pickup-client`
`groupId`	`com.hawkersco`
`version`	`1.0.25-SNAPSHOT`
Java	25
Spring Boot	4.0.6
Tipo de artefacto	JAR (librería, no ejecutable)
Módulos	Proyecto único (no multi-módulo)

3. Arquitectura y diseño

Estructura del proyecto:

com.hawkersco.glspickupclient
├── client/
│   └── GlsPickupClient.java              # Interfaz @HttpExchange con la operación de búsqueda
├── config/
│   ├── GlsPickupClientAutoConfiguration.java  # @AutoConfiguration principal
│   └── GlsPickupClientConfig.java             # @Configuration auxiliar (vacía)
└── dao/
    ├── PickupPointGlsRequest.java        # POJO JAXB de request (parámetros de consulta)
    └── PickupPointGlsResponse.java       # POJO JAXB de response (lista de ParcelShop)

Flujo principal

sequenceDiagram
    participant Consumidor as Microservicio consumidor
    participant GlsPickupClient
    participant GlsAPI as API GLS

    Consumidor->>GlsPickupClient: getNearPickupPoints(direccion, redes, pais)
    GlsPickupClient->>GlsAPI: GET /GetParcelShopProximosV3?direccion=...&redes=...&pais=...
    GlsAPI-->>GlsPickupClient: XML (Resultado / ParcelShop*)
    GlsPickupClient-->>Consumidor: ResponseEntity<String>

La autoconfiguración (GlsPickupClientAutoConfiguration) se activa condicionalmente con @ConditionalOnProperty(prefix = "gls.client", name = "url"), por lo que solo registra el bean GlsPickupClient si la URL de GLS está configurada.

El registro de la autoconfiguración se realiza mediante el fichero estándar de Spring Boot:

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

GlsPickupClientConfig es una clase @Configuration vacía; no aporta beans adicionales actualmente.

4. Dependencias principales

Dependencia	Versión	Propósito
`spring-boot-starter`	(gestionada SB4)	Base de Spring Boot (contexto, autoconfiguración)
`spring-web`	(gestionada SB4)	`RestClient` + `@HttpExchange` / `HttpServiceProxyFactory`
`jakarta.xml.bind:jakarta.xml.bind-api`	(gestionada SB4)	Anotaciones JAXB para el mapeo XML del request/response de GLS
`org.projectlombok:lombok`	1.18.46	Generación de boilerplate en los DAO (getters, setters, constructores)
`spring-boot-test`	(gestionada SB4)	Testing (scope `test`)

5. API / Endpoints

No aplica a este proyecto. gls-pickup-client es una librería cliente JAR que no expone endpoints REST propios. La operación que encapsula sobre la API de GLS se detalla en la sección 6.

6. Integraciones externas

API de GLS (puntos de recogida)

Método cliente	Endpoint remoto	Dirección	Descripción
`getNearPickupPoints`	`GET /GetParcelShopProximosV3`	Saliente	Consulta los parcel shops / puntos de recogida próximos a una dirección

Parámetros de la llamada:

Parámetro	Tipo	Descripción
`direccion`	String	Dirección o referencia de ubicación a consultar
`redes`	String	Redes GLS a considerar en la búsqueda
`pais`	String	Código/nombre de país

Respuesta (XML, mapeada con JAXB en PickupPointGlsResponse):

<Resultado>
    <ParcelShop>
        <IdRed>...</IdRed>
        <Codigo>...</Codigo>
        <Nombre>...</Nombre>
        <Direccion>...</Direccion>
        <Poblacion>...</Poblacion>
        <CodigoPostal>...</CodigoPostal>
        <Pais>...</Pais>
        <Latitud>...</Latitud>
        <Longitud>...</Longitud>
        <HorarioLunes>...</HorarioLunes>
        <HorarioMartes>...</HorarioMartes>
        <HorarioMiercoles>...</HorarioMiercoles>
        <HorarioJueves>...</HorarioJueves>
        <HorarioViernes>...</HorarioViernes>
        <HorarioSabado>...</HorarioSabado>
        <Distancia>...</Distancia>
    </ParcelShop>
    <!-- ... más elementos ParcelShop ... -->
</Resultado>

El método getNearPickupPoints devuelve ResponseEntity<String> (el XML crudo); la deserialización a PickupPointGlsResponse mediante JAXB queda a cargo del servicio consumidor. La clase PickupPointGlsRequest está anotada para mapear el request como XML, pero el método del cliente envía los parámetros como query params, no como body XML serializado (ver sección 13).

Protocolo: HTTP REST (GET). Formato de respuesta: XML (accept: application/xml). Autenticación: Ninguna implementada en el cliente.

7. Configuración

application.properties está vacío en la librería. La única propiedad requerida debe ser suministrada por la aplicación consumidora:

Propiedad	Descripción	Ejemplo de valor
`gls.client.url`	URL base de la API de GLS (activa la autoconfiguración)	`${GLS_CLIENT_URL}`

Variables de entorno recomendadas

Variable	Propiedad mapeada
`GLS_CLIENT_URL`	`gls.client.url`

Importante: Si gls.client.url no está definida, el bean GlsPickupClient no se registra (condición @ConditionalOnProperty).

8. Persistencia

No aplica a este proyecto. La librería no accede a ninguna base de datos ni mantiene estado en memoria.

9. Procesos programados y mensajería

No aplica a este proyecto. No existen jobs @Scheduled, listeners de colas/topics ni runners batch.

10. Ejecución en local

gls-pickup-client es una librería JAR, no una aplicación ejecutable. No tiene servidor embebido ni endpoint de health, pese a incluir una clase @SpringBootApplication (ver sección 13).

Requisitos previos

Java 25
Maven 3.x
Acceso al registro de artefactos Maven interno (europe-west3-maven.pkg.dev/pi-saldum/pi-repo-maven) para resolver/publicar dependencias.

Compilar e instalar en repositorio local

# Compilar sin tests
mvn -B -DskipTests clean install

# Compilar con tests (cuando existan)
mvn clean install

Uso como dependencia en un microservicio consumidor

<dependency>
    <groupId>com.hawkersco</groupId>
    <artifactId>gls-pickup-client</artifactId>
    <version>1.0.25-SNAPSHOT</version>
</dependency>

La autoconfiguración se activa automáticamente al declarar gls.client.url en la aplicación consumidora.

11. Despliegue

El pipeline de Jenkins (Jenkinsfile) consta de dos etapas:

Checkout — descarga el código del repositorio.
Publish to Artifact Registry — ejecuta mvn deploy -DskipTests para publicar el JAR en Google Artifact Registry.

Parámetro	Valor
JDK	JDK25 (tool Jenkins)
Maven	Maven3 (tool Jenkins)
Repositorio	`europe-west3-maven.pkg.dev/pi-saldum/pi-repo-maven` (Artifact Registry GCP)

No existe Dockerfile ni despliegue como servicio independiente; el artefacto es un JAR publicado en el registro Maven.

Job de Jenkins:

https://jenkins-pi.hawkersco.net/job/gls-pickup-client/

12. Manejo de errores y logging

La librería no implementa ninguna estrategia propia de manejo de excepciones ni logging estructurado. Las excepciones de red o HTTP propagadas por RestClient (como RestClientException) son responsabilidad del servicio consumidor. No hay configuración de logback ni de niveles de log específicos.

13. Notas y consideraciones

GlsPickupClientApplication.java: Existe una clase principal @SpringBootApplication en el paquete raíz, lo cual es inusual para una librería cliente. No aporta funcionalidad operativa; probablemente sea un artefacto residual de la generación inicial del proyecto con Spring Initializr (mismo patrón observado en otros clientes del ecosistema, p. ej. auro-client).
GlsPickupClientConfig vacía: La clase @Configuration no registra ningún bean actualmente. Pendiente de verificar si está reservada para configuración futura o si es residual.
Desalineación entre PickupPointGlsRequest y la llamada real: El DAO PickupPointGlsRequest (y su clase interna GetParcelShopProximosV3) está anotado con JAXB para serializar un request XML con campo direccion de tipo long, pero el método getNearPickupPoints del cliente envía los parámetros (direccion como String) como query params en una petición GET, no como cuerpo XML. El DAO de request no se referencia desde GlsPickupClient, por lo que su uso real no está claro — pendiente de verificar si algún consumidor lo utiliza directamente para construir la query.
Cabecera Content-Type en petición GET: GlsPickupClientAutoConfiguration fija Content-Type: application/x-www-form-urlencoded como cabecera por defecto del RestClient, cabecera que normalmente no aplica a peticiones GET sin cuerpo. Comportamiento heredado, no documentado como intencional en el código.
Respuesta como String sin deserializar: getNearPickupPoints devuelve ResponseEntity<String> con el XML crudo; pese a existir PickupPointGlsResponse mapeado con JAXB, el cliente no realiza la deserialización automáticamente — queda a cargo del consumidor.
Sin tests implementados: El directorio src/test/ no existe. La dependencia spring-boot-test está declarada pero no hay ninguna prueba. Pendiente implementar cobertura.
Sin autenticación: A diferencia de otros clientes del ecosistema (p. ej. auro-client), este cliente no implementa ningún mecanismo de autenticación (token, API key, etc.) hacia la API de GLS.

1. Descripción general​

2. Información técnica​

3. Arquitectura y diseño​

Flujo principal​

4. Dependencias principales​

5. API / Endpoints​

6. Integraciones externas​

API de GLS (puntos de recogida)​

7. Configuración​

Variables de entorno recomendadas​

8. Persistencia​

9. Procesos programados y mensajería​

10. Ejecución en local​

Requisitos previos​

Compilar e instalar en repositorio local​

Uso como dependencia en un microservicio consumidor​

11. Despliegue​

12. Manejo de errores y logging​

13. Notas y consideraciones​