SprintLogistics Client

1. Descripción general

sprintlogistics-client es una librería cliente reutilizable (JAR) que encapsula la comunicación con la API v2 de SprintLogistics, operador logístico integrado en el ecosistema de microservicios de Hawkers. El proyecto no expone ningún endpoint REST propio; se publica en el registro de artefactos Maven interno y es consumido por otros microservicios que necesiten consultar el catálogo de productos, crear/consultar pedidos, consultar devoluciones y obtener el tracking de prueba de entrega (POD) en SprintLogistics.

La librería implementa un cliente dual por región: dos beans (SprintlogisticsV2Client y SprintlogisticsGbV2Client) que comparten exactamente el mismo contrato de operaciones (SprintlogisticsV2Operations) pero se configuran con URL y credenciales Basic Auth independientes, para cubrir el endpoint por defecto (España/UE) y el endpoint de Gran Bretaña (GB) respectivamente.

2. Información técnica

Propiedad	Valor
`artifactId`	`sprintlogistics-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.sprintlogisticsclient
├── SprintlogisticsClientApplication.java     # Clase @SpringBootApplication (residual, sin lógica)
├── client/
│   ├── SprintlogisticsV2Operations.java      # Interfaz @HttpExchange con el contrato completo de la API v2
│   ├── SprintlogisticsV2Client.java          # Interfaz marcadora (región ES/por defecto)
│   └── SprintlogisticsGbV2Client.java        # Interfaz marcadora (región GB)
├── config/
│   ├── SprintlogisticsV2Conf.java            # @AutoConfiguration de SprintlogisticsV2Client (Basic Auth)
│   └── SprintlogisticsGbV2Conf.java          # @AutoConfiguration de SprintlogisticsGbV2Client (Basic Auth)
└── model/
    ├── OrderPODTracking.java                  # Modelo de tracking POD, reutilizado por ambas versiones de API (v1 y v2 comparten esquema)
    ├── OrderSprintLogisticsRequest.java, OrderSprintLogisticsResponse.java,
    │   ProductSprintLogisticsResponse.java, ProductsSprintLogisticsResponse.java, StatusSprintLogistics.java
    │   # Modelos de la API v1; no referenciados por SprintlogisticsV2Operations (ver sección 13)
    └── v2/
        ├── OrdersSprintLogisticsV2Request.java / OrdersSprintLogisticsV2Response.java
        ├── ProductsSprintLogisticsV2Response.java
        └── ReturnsSprintLogisticsV2Response.java

Flujo principal

sequenceDiagram
    participant Consumidor as Microservicio consumidor
    participant Client as SprintlogisticsV2Client / SprintlogisticsGbV2Client
    participant API as API SprintLogistics v2 (ES o GB)

    Consumidor->>Client: getProducts / sendOrder / getOrders / getPodTracking / getReturns / ...
    Client->>API: request + Basic Auth (username:password)
    API-->>Client: ResponseEntity<T>
    Client-->>Consumidor: ResponseEntity<T>

SprintlogisticsV2Operations define el contrato completo de la API v2 como interfaz @HttpExchange; SprintlogisticsV2Client y SprintlogisticsGbV2Client son interfaces vacías que únicamente extienden SprintlogisticsV2Operations — mismo patrón de "interfaz marcadora" observado en showroom-client, que permite registrar dos beans Spring de tipos distintos a partir de un único contrato de métodos.

SprintlogisticsV2Conf (@ConditionalOnProperty sobre sprintlogistics-v2.api.url/username/password) y SprintlogisticsGbV2Conf (misma condición sobre el prefijo sprintlogistics-gb-v2.api) construyen cada uno un RestClient con Basic Auth (RestClient.builder().defaultHeaders(h -> h.setBasicAuth(username, password))).

El registro de ambas autoconfiguraciones se realiza mediante el fichero estándar de Spring Boot:

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

Nota sobre la documentación previa del proyecto: el CLAUDE.md de este repositorio describe clases SprintlogisticsClient/SprintlogisticsGbClient/SprintlogisticsConf/SprintlogisticsGbConf y propiedades sprintlogistics.api.*/sprintlogistics-gb.api.* (sin sufijo v2), así como operaciones como getOrderById(id) y getOrderByRef(ref) sin distinguir versión. El código actual usa exclusivamente las clases con sufijo v2 (SprintlogisticsV2Client, SprintlogisticsGbV2Client, SprintlogisticsV2Conf, SprintlogisticsGbV2Conf) y las propiedades sprintlogistics-v2.api.*/sprintlogistics-gb-v2.api.*; los métodos v1 fueron sustituidos (p. ej. getOrderByAwb "Replaces the v1 GET /api/orders/{orderId} operation", según el Javadoc del propio código). Este documento describe el comportamiento observado en el código actual (v2), no el descrito en CLAUDE.md.

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`
`com.fasterxml.jackson.core:jackson-databind`	(gestionada SB4)	Serialización/deserialización Jackson en los modelos
`com.google.code.gson:gson`	2.11.0	Anotaciones `@SerializedName` en los modelos (soporte dual con Jackson)
`org.projectlombok:lombok`	1.18.42 (dependencia; `annotationProcessorPath` del compilador usa 1.18.46)	Generación de boilerplate en los modelos
`spring-boot-starter-test`	(gestionada SB4)	Testing (scope `test`)

5. API / Endpoints

No aplica a este proyecto. sprintlogistics-client es una librería cliente JAR que no expone endpoints REST propios. Las operaciones que encapsula sobre la API v2 de SprintLogistics se detallan en la sección 6.

6. Integraciones externas

API v2 de SprintLogistics (`SprintlogisticsV2Operations`, común a ambas regiones)

Método	HTTP	Ruta remota	Descripción
`getProducts`	GET	`/api/product`	Lista paginada de productos del catálogo, con filtro opcional por fecha
`getProductBySku`	GET	`/api/product/productsbysku`	Consulta un producto por SKU
`sendOrder`	POST	`/api/orders/uniqueorder`	Crea un pedido único (idempotente por `CustomerRef1`); devuelve el body crudo
`sendOrderTyped`	POST	`/api/orders/uniqueorder`	Misma operación que `sendOrder`, pero deserializa la respuesta tipada
`getOrderByRef`	GET	`/api/orders/Ref`	Consulta un pedido por referencia de cliente (`CustomerRef1`)
`getOrderByAwb`	GET	`/api/orders/orderno`	Consulta un pedido por número de pedido Sprint (AWB)
`getPodTracking`	GET	`/api/shipment/GetPODTracking`	Tracking de prueba de entrega (POD), tipado
`getPodTrackingAlt`	GET	`/api/shipment/GetPODTracking`	Misma operación, devuelve el JSON crudo
`getReturns`	GET	`/api/returns`	Lista paginada de devoluciones
`getOrders`	GET	`/api/orders`	Lista paginada de pedidos filtrados por rango de fechas

Ejemplo de payload sendOrder/sendOrderTyped (OrdersSprintLogisticsV2Request, resumido):

{
  "CompanyName": "Hawkers",
  "Address1": "Calle Ejemplo 1",
  "City": "Madrid",
  "CountryCode": "ES",
  "CustomerRef1": "ORD-000123",
  "OrderSourceDate": "2026-07-01T10:00:00",
  "StockOrderItems": [
    { "SKU": "SKU-001", "Quantity": 2 }
  ]
}

Ejemplo de respuesta getPodTracking (OrderPODTracking, resumida):

{
  "Status": true,
  "Message": "",
  "Count": 1,
  "Tracking": {
    "Carrier": "SprintLogistics",
    "POD": { "PodName": "Firma cliente", "DeliveryDate": "2026-07-05", "DeliveryTime": "14:30" },
    "Tracking": [
      { "TrackedOn": "2026-07-04T09:00:00", "Location": "Madrid Hub", "Description": "En tránsito" }
    ]
  }
}

Protocolo: HTTPS REST (JSON, contentType = application/json). Autenticación: HTTP Basic Auth (usuario/contraseña por región), fijada como cabecera por defecto en el RestClient de cada autoconfiguración.

7. Configuración

No se incluye ningún application.properties/application.yml en la librería. Las propiedades deben ser inyectadas por la aplicación consumidora.

Propiedades requeridas

Propiedad	Descripción	Ejemplo de valor
`sprintlogistics-v2.api.url`	URL base de la API v2 SprintLogistics (región ES/por defecto)	`${SPRINTLOGISTICS_V2_URL}`
`sprintlogistics-v2.api.username`	Usuario Basic Auth (región ES/por defecto)	`${SPRINTLOGISTICS_V2_USERNAME}`
`sprintlogistics-v2.api.password`	Contraseña Basic Auth (región ES/por defecto)	`${SPRINTLOGISTICS_V2_PASSWORD}`
`sprintlogistics-gb-v2.api.url`	URL base de la API v2 SprintLogistics (región GB)	`${SPRINTLOGISTICS_GB_V2_URL}`
`sprintlogistics-gb-v2.api.username`	Usuario Basic Auth (región GB)	`${SPRINTLOGISTICS_GB_V2_USERNAME}`
`sprintlogistics-gb-v2.api.password`	Contraseña Basic Auth (región GB)	`${SPRINTLOGISTICS_GB_V2_PASSWORD}`

Importante: Cada bean se activa de forma independiente; un consumidor puede usar solo la región por defecto, solo GB, o ambas, según qué grupo de propiedades declare.

Variables de entorno recomendadas

Variable	Propiedad mapeada
`SPRINTLOGISTICS_V2_URL`	`sprintlogistics-v2.api.url`
`SPRINTLOGISTICS_V2_USERNAME`	`sprintlogistics-v2.api.username`
`SPRINTLOGISTICS_V2_PASSWORD`	`sprintlogistics-v2.api.password`
`SPRINTLOGISTICS_GB_V2_URL`	`sprintlogistics-gb-v2.api.url`
`SPRINTLOGISTICS_GB_V2_USERNAME`	`sprintlogistics-gb-v2.api.username`
`SPRINTLOGISTICS_GB_V2_PASSWORD`	`sprintlogistics-gb-v2.api.password`

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

sprintlogistics-client es una librería JAR, no una aplicación ejecutable. No tiene servidor embebido ni endpoint de health.

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 con tests
./mvnw clean install

# Empaquetar sin instalar
./mvnw clean package

# Compilar sin tests (como en CI)
./mvnw -DskipTests clean install

# Ejecutar tests
./mvnw test

Uso como dependencia en un microservicio consumidor

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

Cada uno de los dos beans (SprintlogisticsV2Client/SprintlogisticsGbV2Client) se activa independientemente según las propiedades declaradas por el consumidor.

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.

CLAUDE.md documenta un pipeline con etapas Build → KICS → SonarQube → Clean vía scripts, que no se corresponde con el Jenkinsfile actual del repositorio (dos etapas: Checkout y Publish to Artifact Registry). Se documenta el Jenkinsfile realmente presente.

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/sprintlogistics-client/

12. Manejo de errores y logging

La librería no implementa ninguna estrategia propia de manejo de excepciones ni logging estructurado. Ningún método de SprintlogisticsV2Operations declara throws explícito; las excepciones de red o HTTP propagadas por RestClient (como RestClientResponseException) son responsabilidad del servicio consumidor. No hay configuración de logback ni de niveles de log específicos en la librería.

13. Notas y consideraciones

Modelos v1 huérfanos en model/ (raíz): OrderSprintLogisticsRequest, OrderSprintLogisticsResponse, ProductSprintLogisticsResponse, ProductsSprintLogisticsResponse y StatusSprintLogistics no están referenciados por SprintlogisticsV2Operations ni por ninguna autoconfiguración — corresponden a la API v1, sustituida por la v2. Solo OrderPODTracking (también en la raíz de model/) sigue en uso porque, según el Javadoc del código, "the v2 response schema is identical to v1". Los cinco modelos huérfanos podrían eliminarse si ningún consumidor externo los referencia directamente, o mantenerse documentados como legado si aún hay integraciones activas contra la API v1 de SprintLogistics fuera de esta librería.
Documentación previa (CLAUDE.md) describe la generación anterior (v1) de la librería: nombres de clase, propiedades de configuración y operaciones documentadas no coinciden con el código v2 actual. Ver detalle en la sección 3.
sendOrder vs. sendOrderTyped: Ambos métodos invocan el mismo endpoint (POST /api/orders/uniqueorder) con el mismo payload; la única diferencia es el tipo de retorno (String crudo vs. OrdersSprintLogisticsV2Response tipado). El Javadoc indica que la API v2 devuelve la orden completa como ResultList[ApiOrderMasterViewModel], por lo que sendOrderTyped es la opción recomendada salvo que el consumidor necesite el JSON crudo por algún motivo específico.
getPodTracking vs. getPodTrackingAlt: Mismo patrón que el anterior — mismo endpoint, mismo parámetro, difieren solo en si la respuesta se deserializa a OrderPODTracking o se devuelve como String crudo.
Diferencia de tipo en StockOrderItem.Quantity entre v1 y v2: El Javadoc de OrdersSprintLogisticsV2Request indica explícitamente que, a diferencia del modelo de request v1, en v2 Quantity es un long (entero de 64 bits) en lugar de un entero simple — detalle relevante si algún consumidor migra código que antes usaba el modelo v1.
Basic Auth sin renovación ni caché: A diferencia de otros clientes del ecosistema que gestionan tokens OAuth2 con caché, aquí las credenciales Basic Auth se fijan una única vez al construir el RestClient — cualquier rotación de credencial requiere reiniciar el contexto Spring del consumidor.
Sin tests implementados: No se ha encontrado directorio src/test/ en el proyecto.
SprintlogisticsClientApplication.java: Clase principal de Spring Boot en el paquete raíz, sin funcionalidad operativa. Artefacto residual de la generación inicial del proyecto con Spring Initializr, mismo patrón observado en otros clientes del ecosistema.

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 v2 de SprintLogistics (SprintlogisticsV2Operations, común a ambas regiones)​

7. Configuración​

Propiedades requeridas​

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​