Liverpool Client

1. Descripción general

liverpool-client es una librería cliente reutilizable (JAR) que encapsula la comunicación con la API de gestión de pedidos del marketplace Liverpool. 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 listar pedidos, aceptarlos, actualizar su información de tracking/envío o descargar la documentación asociada.

Expone operaciones para:

Consultar pedidos por rango de fechas, código de estado o identificador de estado.
Aceptar un pedido (confirmando o rechazando sus líneas).
Actualizar la información de tracking de un pedido.
Marcar un pedido como enviado (ship).
Descargar la documentación (etiquetas/albaranes) de una lista de pedidos.

2. Información técnica

Propiedad	Valor
`artifactId`	`liverpool-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.liverpoolclient
├── LiverpoolClientApplication.java             # Clase @SpringBootApplication (residual, sin lógica)
├── client/
│   └── LiverpoolClient.java                    # Interfaz @HttpExchange con 7 operaciones de negocio
├── config/
│   └── LiverpoolClientAutoConfiguration.java   # @AutoConfiguration principal
└── models/
    ├── AcceptOrderRequest.java                 # Request de aceptación de pedido (líneas aceptadas/rechazadas)
    ├── TrackingLiverpool.java                   # Request de actualización de tracking
    ├── OrdersLiverpoolResponse.java             # Respuesta de listado de pedidos (jerarquía completa)
    └── LiverpoolUpdateOrderResponse.java        # Modelo de respuesta de actualización de pedido (no referenciado por LiverpoolClient)

Flujo principal

sequenceDiagram
    participant Consumidor as Microservicio consumidor
    participant Client as LiverpoolClient
    participant API as API Liverpool

    Consumidor->>Client: getOrders / acceptOrder / updateTracking / updateShip / downloadDocumentsByOrderList
    Client->>API: GET/PUT /api/orders... + header Authorization
    API-->>Client: ResponseEntity<OrdersLiverpoolResponse | String | byte[]>
    Client-->>Consumidor: ResponseEntity<T>

La autoconfiguración (LiverpoolClientAutoConfiguration) se activa condicionalmente con @ConditionalOnProperty(prefix = "liverpool.credentials", name = {"url", "key"}), registrando un único bean LiverpoolClient cuyo RestClient incorpora la cabecera estática Authorization (con el valor de liverpool.credentials.key) mediante defaultHeader en todas las peticiones.

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

LiverpoolClientApplication está anotada con @SpringBootApplication y además con @EnableAutoConfiguration explícito (redundante, ya que @SpringBootApplication ya lo incluye).

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

5. API / Endpoints

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

6. Integraciones externas

API de pedidos Liverpool

Método cliente	HTTP	Ruta remota	Dirección	Descripción
`getOrders`	GET	`/api/orders?start_date&max&offset`	Saliente	Lista pedidos paginados dentro de un rango de fechas
`getOrderListByStateCode`	GET	`/api/orders?order_state_codes&start_date&max&offset`	Saliente	Lista pedidos filtrados por código de estado
`getOrderListByStateId`	GET	`/api/orders?state_order_id&start_date&max&offset`	Saliente	Lista pedidos filtrados por identificador de estado
`acceptOrder`	PUT	`/api/orders/{orderId}/accept`	Saliente	Acepta (o rechaza) las líneas de un pedido
`updateTracking`	PUT	`/api/orders/{orderId}/tracking`	Saliente	Actualiza la información de tracking (transportista, número de guía)
`updateShip`	PUT	`/api/orders/{orderId}/ship`	Saliente	Marca un pedido como enviado
`downloadDocumentsByOrderList`	GET	`/api/orders/documents/download?order_ids&shop_id=2795`	Saliente	Descarga la documentación (etiquetas/albaranes) de una lista de pedidos, devuelve `byte[]`

Ejemplo de payload acceptOrder (AcceptOrderRequest):

{
  "order_lines": [
    { "id": "ORDLINE-001", "accepted": true },
    { "id": "ORDLINE-002", "accepted": false }
  ]
}

Ejemplo de payload updateTracking (TrackingLiverpool):

{
  "carrier_code": "DHL",
  "carrier_name": "DHL Express",
  "carrier_url": "https://dhl.example/tracking",
  "tracking_number": "1234567890"
}

Ejemplo de respuesta getOrders (OrdersLiverpoolResponse, resumida):

{
  "total_count": 42,
  "orders": [
    {
      "order_id": "ORD-000123",
      "order_state": "WAITING_ACCEPTANCE",
      "created_date": "2026-07-01T10:00:00Z",
      "channel": { "code": "MP", "label": "Marketplace" },
      "customer": {
        "customer_id": "CUST-001",
        "firstname": "Nombre",
        "lastname": "Apellido",
        "shipping_address": { "city": "CDMX", "country_iso_code": "MX", "...": "..." }
      },
      "order_lines": [
        {
          "order_line_id": "ORDLINE-001",
          "product_sku": "SKU-001",
          "product_title": "Camiseta básica",
          "quantity": 2,
          "price": 199.00,
          "order_line_state": "WAITING_ACCEPTANCE"
        }
      ],
      "total_price": 398.00
    }
  ]
}

Nota: el número shop_id=2795 en downloadDocumentsByOrderList está hardcodeado como parte fija de la ruta (no es un parámetro configurable en el cliente).

Protocolo: HTTPS REST (JSON, contentType = application/json; descarga de documentos devuelve binario). Autenticación: cabecera estática Authorization (sin flujo de token/refresh, valor inyectado directamente desde configuración).

7. Configuración

El fichero src/main/resources/application.properties existe pero está intencionalmente vacío. Las propiedades deben ser inyectadas por la aplicación consumidora.

Propiedades requeridas (prefijo `liverpool.credentials`)

Propiedad	Descripción	Ejemplo de valor
`liverpool.credentials.url`	URL base de la API Liverpool (activa la autoconfiguración)	`${LIVERPOOL_URL}`
`liverpool.credentials.key`	Valor completo de la cabecera `Authorization`	`${LIVERPOOL_AUTH_KEY}`

Importante: Si falta liverpool.credentials.url o liverpool.credentials.key, el bean LiverpoolClient no se registra (condición @ConditionalOnProperty con ambas claves).

Variables de entorno recomendadas

Variable	Propiedad mapeada
`LIVERPOOL_URL`	`liverpool.credentials.url`
`LIVERPOOL_AUTH_KEY`	`liverpool.credentials.key`

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

liverpool-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 sin tests
./mvnw clean install -DskipTests

# Compilar con tests
./mvnw clean install

# Ejecutar un test/método concreto
./mvnw test -Dtest=ClassName
./mvnw test -Dtest=ClassName#methodName

Uso como dependencia en un microservicio consumidor

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

La autoconfiguración se activa automáticamente al declarar liverpool.credentials.url y liverpool.credentials.key 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/liverpool-client/

12. Manejo de errores y logging

La librería no implementa ninguna estrategia propia de manejo de excepciones ni logging estructurado. Todos los métodos de LiverpoolClient declaran explícitamente throws RestClientResponseException, propagando al consumidor los errores HTTP devueltos por la API de Liverpool sin envolverlos en una excepción propia. No hay configuración de logback ni de niveles de log específicos en la librería.

13. Notas y consideraciones

LiverpoolUpdateOrderResponse no utilizado: El modelo LiverpoolUpdateOrderResponse (con campos en español como tipo_respuesta, respuesta, guia, mensajeria) no es referenciado por ningún método de LiverpoolClient — todos los métodos PUT devuelven ResponseEntity<String> en lugar de este tipo. Podría tratarse de un modelo pensado para una respuesta que el consumidor deserializa manualmente, o de un remanente de una integración distinta (los nombres de campo en español sugieren un proveedor de mensajería/paquetería, no la API de Liverpool en inglés). Pendiente de verificar su uso real.
shop_id=2795 hardcodeado: La ruta de downloadDocumentsByOrderList incluye el parámetro shop_id=2795 fijo en el @GetExchange, en lugar de recibirlo como parámetro del método. Si Hawkers operase con más de una tienda Liverpool, este cliente no soportaría esa multiplicidad sin modificar el código.
Autenticación sin flujo de token: A diferencia de otros clientes del ecosistema (auro-client, hk-timeslogistics-client) que resuelven un token Bearer con caché, este cliente inyecta el valor completo de Authorization de forma estática desde configuración — cualquier rotación de credencial requiere reiniciar el contexto Spring del consumidor.
@EnableAutoConfiguration redundante: LiverpoolClientApplication combina @SpringBootApplication (que ya incluye auto-configuración) con @EnableAutoConfiguration explícito, sin efecto adicional.
Campos Object en OrdersLiverpoolResponse: Numerosos campos (delivery_date, order_state_reason_code, quote_id, shipping_pudo_id, description, etc.) están tipados como Object en lugar de un tipo concreto, reflejando que la API de Liverpool los devuelve con tipo variable (string, null, número). Reduce la seguridad de tipos para el consumidor.
Sin tests implementados: El directorio src/test/ no existe. La dependencia spring-boot-starter-test está declarada pero no hay ninguna prueba, pese a que el CLAUDE.md del proyecto documenta comandos para ejecutar tests.
LiverpoolClientApplication.java: Existe una clase principal de Spring Boot en el paquete raíz, lo que es inusual para una librería. No tiene funcionalidad operativa y probablemente sea un 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 de pedidos Liverpool​

7. Configuración​

Propiedades requeridas (prefijo liverpool.credentials)​

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​