Lazada Client

1. Descripción general

lazada-client es una librería reutilizable (JAR) que provee los modelos de datos (POJOs) para integrarse con la Lazada Open Platform (LazOP) API, orientada principalmente a la gestión de productos e inventario en el marketplace Lazada. A diferencia de otros clientes del ecosistema (auro-client, justeat-client...), este proyecto no implementa una capa @HttpExchange/RestClient ni una autoconfiguración de Spring propia: la comunicación HTTP y la autenticación con Lazada se delegan íntegramente al SDK oficial com.lazop:lazop, declarado como dependencia. Los POJOs de este proyecto mapean las estructuras de request/response de dicho SDK para su uso por los microservicios consumidores.

Dentro del ecosistema Hawkers, esta librería es consumida por los microservicios/runners que sincronizan catálogo, precios y stock con el marketplace Lazada (multi-país: Malasia, Indonesia, Vietnam, Filipinas, Singapur, Tailandia).

2. Información técnica

Propiedad	Valor
`artifactId`	`lazada-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.lazadaclient
├── LazadaClientApplication.java              # Clase @SpringBootApplication (residual, sin lógica)
└── pojos/
    ├── TokenReq.java                          # Modelo de respuesta de autenticación OAuth (multi-país)
    ├── LazadaProductsResponse.java            # Respuesta de consulta de productos (jerarquía Data→Product→Skus)
    ├── LazadaProductsGlobalResponse.java       # Respuesta "global" con IDs de producto por país Lazada
    ├── LazadaProductsUpdateStockRequest.java   # Request XML (JAXB) para actualización de stock
    ├── LazadaSkuStock.java                     # Modelo simplificado de stock por SKU
    ├── UpdatePriceQuantityRequest.java         # Request para actualización de precio/cantidad
    └── UpdatePriceQuantityResponse.java        # Respuesta de la actualización de precio/cantidad

No existen paquetes client/ ni config/: no hay ninguna clase @AutoConfiguration, @Configuration ni interfaz @HttpExchange en el proyecto. El consumo real de la API Lazada (autenticación OAuth, firma de peticiones, llamadas HTTP) se realiza a través del SDK externo com.lazop:lazop:1.2.0, que el microservicio consumidor invoca directamente, usando los POJOs de esta librería para (de)serializar los payloads.

Flujo previsto (basado en el uso de `TokenReq` y los POJOs de producto/stock)

sequenceDiagram
    participant Consumidor as Microservicio consumidor
    participant LazopSDK as SDK com.lazop:lazop
    participant API as API Lazada (LazOP)

    Consumidor->>LazopSDK: petición firmada (access_token, app_key/secret gestionados por el SDK)
    LazopSDK->>API: llamada HTTP (productos, stock, precio)
    API-->>LazopSDK: respuesta JSON/XML
    LazopSDK-->>Consumidor: respuesta deserializada con los POJOs de lazada-client

Pendiente de verificar: el detalle exacto de cómo el SDK lazop construye y firma las peticiones no es observable desde este repositorio (vive en la dependencia externa com.lazop:lazop).

4. Dependencias principales

Dependencia	Versión	Propósito
`spring-boot-starter`	(gestionada SB4)	Base de Spring Boot (contexto, autoconfiguración)
`com.lazop:lazop`	1.2.0	SDK oficial de Lazada Open Platform: autenticación, firma y llamadas HTTP a la API Lazada
`jakarta.xml.bind:jakarta.xml.bind-api`	4.0.1	Anotaciones JAXB para el mapeo XML de `LazadaProductsUpdateStockRequest`
`com.fasterxml.jackson.core:jackson-annotations`	(gestionada SB4)	Anotaciones `@JsonProperty` en los POJOs (mapeo snake_case ↔ camelCase)
`com.google.code.gson:gson`	(gestionada SB4)	Anotaciones `@SerializedName` en los POJOs (soporte dual con Jackson)
`org.projectlombok:lombok`	(gestionada, compilador fija 1.18.46)	Generación de boilerplate en los POJOs (getters, setters, constructores)
`spring-boot-starter-test`	(gestionada SB4)	Testing (scope `test`)

5. API / Endpoints

No aplica a este proyecto. lazada-client es una librería de modelos de datos que no expone endpoints REST propios ni define una interfaz de cliente HTTP explícita; las llamadas a la API de Lazada se realizan mediante el SDK externo com.lazop:lazop.

6. Integraciones externas

API Lazada Open Platform (LazOP)

La integración se realiza indirectamente a través del SDK com.lazop:lazop. Los POJOs de este proyecto reflejan las siguientes operaciones de negocio:

POJO	Rol	Dirección
`TokenReq`	Respuesta de autenticación OAuth (access/refresh token, multi-país)	Entrante
`LazadaProductsResponse`	Respuesta de consulta de productos (skus, atributos, inventario multi-almacén)	Entrante
`LazadaProductsGlobalResponse`	Respuesta con identificadores de producto por país (`LAZADA_MY`, `LAZADA_ID`, `LAZADA_VN`, `LAZADA_PH`, `LAZADA_SG`, `LAZADA_TH`)	Entrante
`LazadaProductsUpdateStockRequest`	Request XML para actualizar el stock vendible (`SellableQuantity`) de uno o varios SKUs	Saliente
`LazadaSkuStock`	Modelo simplificado de stock por SKU (`sku`, `product_id`, `lazada_id`, `qty`)	—
`UpdatePriceQuantityRequest`	Request para actualizar precio (`price`, `salePrice`, fechas de oferta) y cantidad de uno o varios SKUs	Saliente
`UpdatePriceQuantityResponse`	Respuesta de la operación de actualización de precio/cantidad	Entrante

Ejemplo de request XML LazadaProductsUpdateStockRequest (formato esperado por la API de stock de Lazada):

<Request>
    <Product>
        <Skus>
            <Sku>
                <ItemId>123456789</ItemId>
                <SkuId>987654321</SkuId>
                <SellerSku>SKU-001</SellerSku>
                <SellableQuantity>10</SellableQuantity>
            </Sku>
        </Skus>
    </Product>
</Request>

Protocolo: HTTPS REST (JSON para la mayoría de operaciones, XML para actualización de stock). Autenticación: OAuth (access token / refresh token), gestionada por el SDK lazop; el modelo TokenReq refleja la respuesta de dicho flujo.

7. Configuración

El fichero src/main/resources/application.properties existe pero está vacío. No se han encontrado propiedades de configuración propias del proyecto (@Value, @ConfigurationProperties, @ConditionalOnProperty) en el código fuente.

Las credenciales de la integración con Lazada (app_key, app_secret, access_token, país/endpoint por marketplace) son gestionadas por el SDK com.lazop:lazop y deben ser configuradas por el microservicio consumidor según lo que exija dicho SDK — pendiente de verificar en la documentación oficial del SDK lazop, ya que no es observable desde este repositorio.

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

lazada-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), tanto para resolver dependencias como para el propio SDK com.lazop:lazop.

Compilar e instalar en repositorio local

# Compilar sin tests
./mvnw clean install -DskipTests

# Compilar con tests
./mvnw clean install

# Ejecutar tests
./mvnw test

Uso como dependencia en un microservicio consumidor

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

El servicio consumidor debe además declarar e inicializar el SDK com.lazop:lazop por su cuenta para realizar las llamadas HTTP reales a Lazada; esta librería solo aporta los modelos de datos.

11. Despliegue

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

Checkout — descarga el código del repositorio.
Publish to Artifact Registry — antes de compilar, elimina la copia local cacheada del SDK com.lazop:lazop (rm -rf ~/.m2/repository/com/lazop/lazop) para forzar su re-resolución desde el registro remoto, y luego 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/lazada-client/

12. Manejo de errores y logging

La librería no implementa ninguna estrategia propia de manejo de excepciones ni logging estructurado; al no tener capa de cliente HTTP propia, cualquier excepción de red, autenticación o deserialización se origina y propaga desde el SDK com.lazop:lazop, siendo responsabilidad del servicio consumidor gestionarla. No hay configuración de logback ni de niveles de log específicos en este proyecto.

13. Notas y consideraciones

Sin capa de cliente HTTP propia: A diferencia del resto de clientes del ecosistema (auro-client, hk-timeslogistics-client, justeat-client, labelary-client), lazada-client no define ninguna interfaz @HttpExchange ni @AutoConfiguration; toda la comunicación HTTP se delega en el SDK externo com.lazop:lazop. Esto implica que el "cliente" real no vive en este repositorio, lo que puede generar confusión sobre dónde se implementa la lógica de llamada a la API.
Limpieza forzada del SDK en Jenkins: El Jenkinsfile elimina explícitamente la copia cacheada de com.lazop:lazop en ~/.m2 antes de cada build (rm -rf ~/.m2/repository/com/lazop/lazop). Esto sugiere problemas previos de caché con versiones desactualizadas o corruptas de este artefacto de terceros — comportamiento no estándar respecto a otros Jenkinsfile del ecosistema, que no incluyen este paso.
Doble serialización (Jackson + Gson) salvo en el request de precio/cantidad: La mayoría de POJOs anota los campos con @JsonProperty y @SerializedName simultáneamente, salvo UpdatePriceQuantityRequest, cuyos campos (itemID, skuID, salePrice, etc.) no llevan ninguna anotación de mapeo explícita — la serialización dependerá de la convención por defecto de la librería usada (Jackson/Gson) en el consumidor, lo que puede producir una serialización inconsistente (itemID vs. itemId/item_id esperado por la API) si no se configura explícitamente. Pendiente de verificar contra el formato real esperado por Lazada.
Mezcla JSON/XML en la misma librería: LazadaProductsUpdateStockRequest usa anotaciones JAXB para serializar XML, mientras el resto de POJOs usa JSON (Jackson/Gson). Esto refleja que la API de Lazada expone algunas operaciones en XML (actualización de stock) y otras en JSON, y el consumidor debe saber qué formato usar para cada llamada.
LazadaClientApplication.java: Existe una clase principal @SpringBootApplication en el paquete raíz, sin método main ni funcionalidad operativa — patrón residual observado también en otros clientes del ecosistema, probablemente generado por Spring Initializr.
application.properties vacío: No aporta ninguna configuración; toda la configuración de credenciales/país de Lazada queda fuera del alcance de este repositorio.
Único test: carga de contexto: LazadaClientApplicationTests.java contiene únicamente el test contextLoads() generado por defecto por Spring Initializr (@SpringBootTest, método vacío). No existe ninguna prueba real sobre los POJOs ni sobre la integración con el SDK lazop.

1. Descripción general​

2. Información técnica​

3. Arquitectura y diseño​

Flujo previsto (basado en el uso de TokenReq y los POJOs de producto/stock)​

4. Dependencias principales​

5. API / Endpoints​

6. Integraciones externas​

API Lazada Open Platform (LazOP)​

7. Configuración​

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​