OWD Client

1. Descripción general

owd-client es una librería cliente reutilizable (JAR) que encapsula la comunicación con la API OWD (Order Warehouse Distributor), operador logístico de terceros 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 conteo de inventario o enviar pedidos al almacén gestionado por OWD.

Toda la comunicación con OWD es en formato XML (no JSON), serializado con JAXB, sobre un único endpoint remoto.

2. Información técnica

Propiedad	Valor
`artifactId`	`owd-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.owdclient
├── OwdClientApplication.java              # Clase @SpringBootApplication; excluye DataSourceAutoConfiguration explícitamente
├── client/
│   └── OwdClient.java                     # Interfaz @HttpExchange: getInventoryCount, sendOrder
├── config/
│   └── OwdClientAutoConfiguration.java    # @AutoConfiguration principal
└── models/
    ├── OwdInventoryCountReq.java           # Request JAXB: <OWD_API_REQUEST> con credenciales + <OWD_INVENTORY_COUNT_REQUEST> anidado (vacío)
    └── OwdInventoryCountRes.java           # Response JAXB: <OWD_API_RESPONSE> → Count → FacilityCount

Flujo principal

sequenceDiagram
    participant Consumidor as Microservicio consumidor
    participant Client as OwdClient
    participant API as API OWD

    Consumidor->>Client: getInventoryCount(OwdInventoryCountReq) / sendOrder(xmlPedido)
    Client->>API: POST /api/api.jsp (text/xml)
    API-->>Client: ResponseEntity<String> (XML crudo)
    Client-->>Consumidor: ResponseEntity<String>

La autoconfiguración (OwdClientAutoConfiguration) se activa condicionalmente con @ConditionalOnProperty(prefix = "owd.auth.client", name = "url"), registrando el bean OwdClient con un RestClient simple (sin interceptores) apuntando a owd.auth.client.url.

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

Ambos métodos de OwdClient (getInventoryCount y sendOrder) apuntan al mismo endpoint remoto (/api/api.jsp) — OWD discrimina la operación por el contenido del XML enviado, no por la ruta. getInventoryCount recibe un objeto tipado (OwdInventoryCountReq), mientras que sendOrder recibe el XML del pedido ya construido como String crudo (no existe ningún POJO JAXB de request para pedidos en este proyecto).

OwdClientApplication excluye explícitamente DataSourceAutoConfiguration mediante excludeName (usando el nombre completo de la clase en el paquete org.springframework.boot.jdbc.autoconfigure, ya que en Spring Boot 4 dicho módulo se separó y no está en el classpath de esta librería).

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 de request/response
`org.projectlombok:lombok`	(gestionada; `annotationProcessorPath` del compilador fija 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. owd-client es una librería cliente JAR que no expone endpoints REST propios. Las operaciones que encapsula sobre la API de OWD se detallan en la sección 6.

6. Integraciones externas

API OWD (Order Warehouse Distributor)

Método cliente	HTTP	Ruta remota	Dirección	Descripción
`getInventoryCount`	POST	`/api/api.jsp`	Saliente	Consulta el conteo de inventario (stock por parte/facility)
`sendOrder`	POST	`/api/api.jsp`	Saliente	Envía un pedido al almacén OWD (XML crudo construido por el consumidor)

Ejemplo de request getInventoryCount (OwdInventoryCountReq):

<OWD_API_REQUEST api_version="1.0" client_id="HAWKERS" client_authorization="********" testing="false">
    <OWD_INVENTORY_COUNT_REQUEST/>
</OWD_API_REQUEST>

Nótese que OwdInventoryCountRequest (la clase anidada mapeada a <OWD_INVENTORY_COUNT_REQUEST>) no declara ningún campo — se serializa siempre como una etiqueta vacía, sin parámetros de filtro (p. ej. por parte o facility). Pendiente de verificar si la API OWD admite atributos/hijos opcionales dentro de este elemento que no estén modelados en el POJO.

Ejemplo de respuesta getInventoryCount (OwdInventoryCountRes):

<OWD_API_RESPONSE results="ok">
    <OWD_INVENTORY_COUNT_RESPONSE>
        <COUNT part_reference="SKU-001" results="120">
            <FACILITY_COUNT facility_code="WH01" quantity_on_hand="80" expected_count="10"
                             expected_asn_count="5" expected_asn_next_date="2026-07-15"/>
            <FACILITY_COUNT facility_code="WH02" quantity_on_hand="40" expected_count="0"
                             expected_asn_count="0" expected_asn_next_date=""/>
        </COUNT>
    </OWD_INVENTORY_COUNT_RESPONSE>
</OWD_API_RESPONSE>

sendOrder no dispone de POJO JAXB propio: el consumidor debe construir manualmente el XML del pedido (formato no documentado en este repositorio) y pasarlo como String al método.

Protocolo: HTTP con cuerpo y respuesta XML (text/xml, @HttpExchange(contentType = TEXT_XML_VALUE, accept = TEXT_XML_VALUE)). Autenticación: credenciales embebidas como atributos XML en el propio request (client_id, client_authorization), sin cabeceras HTTP de autenticació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
`owd.auth.client.url`	URL base de la API OWD (activa la autoconfiguración)	`${OWD_CLIENT_URL}`

Las credenciales (client_id, client_authorization) no se configuran como propiedades Spring: se embeben manualmente por el consumidor como atributos del XML (OwdInventoryCountReq.clientId / clientAuthorization) o dentro del XML crudo de sendOrder.

Variables de entorno recomendadas

Variable	Propiedad mapeada
`OWD_CLIENT_URL`	`owd.auth.client.url`

Importante: Si owd.auth.client.url no está definida, el bean OwdClient 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. DataSourceAutoConfiguration está excluida explícitamente en OwdClientApplication.

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

owd-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 -B -DskipTests clean install

# Compilar con tests
./mvnw clean verify

# Empaquetar
./mvnw package

Uso como dependencia en un microservicio consumidor

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

La autoconfiguración se activa automáticamente al declarar owd.auth.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/owd-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 RestClientResponseException) son responsabilidad del servicio consumidor, ya que ningún método de OwdClient declara throws explícito. Al devolver siempre ResponseEntity<String> con el XML crudo, la detección de errores de negocio (p. ej. results="error" en la respuesta) requiere que el propio consumidor parsee la respuesta. No hay configuración de logback ni de niveles de log específicos en la librería.

13. Notas y consideraciones

OwdInventoryCountRequest sin campos: La clase anidada OwdInventoryCountReq.OwdInventoryCountRequest, mapeada al elemento <OWD_INVENTORY_COUNT_REQUEST>, está completamente vacía (sin atributos ni elementos hijos). El request de inventario se compone únicamente de las credenciales del elemento raíz (client_id, client_authorization, api_version, testing); no hay forma de filtrar la consulta por SKU, facility o rango de fechas desde este modelo. Pendiente de verificar si la API OWD ignora filtros o si el modelo está incompleto respecto al contrato real de la API.
sendOrder sin modelo JAXB propio: A diferencia de getInventoryCount, la operación de envío de pedidos no cuenta con ningún POJO de request en models/ — el consumidor debe construir el XML completo manualmente como String, sin ayuda de tipado ni de la librería. Esto traslada el conocimiento del formato exacto del pedido OWD íntegramente al consumidor.
Mismo endpoint para operaciones distintas: getInventoryCount y sendOrder comparten la misma ruta (/api/api.jsp); la distinción de operación la determina el contenido del XML enviado, no la URL — patrón típico de integraciones legacy tipo "API gateway de un único endpoint".
Autenticación embebida en el XML, sin cabeceras HTTP: Las credenciales (client_id, client_authorization) viajan como atributos del elemento raíz del XML de request, no como cabeceras HTTP — cualquier log de la petición HTTP en bruto expondría estas credenciales si no se trata el cuerpo con cuidado.
Exclusión explícita de DataSourceAutoConfiguration: OwdClientApplication excluye org.springframework.boot.jdbc.autoconfigure.DataSourceAutoConfiguration por nombre de clase (excludeName), reflejando el cambio de Spring Boot 4 donde el autoconfigure de JDBC se movió a un módulo separado no presente en el classpath de esta librería — patrón no observado en otros clientes del ecosistema documentados hasta ahora, que simplemente no incluyen ningún starter de datos.
Sin tests implementados: No existe directorio src/test/ en el proyecto.
OwdClientApplication.java: Clase principal de Spring Boot en el paquete raíz, sin funcionalidad operativa más allá de la exclusión de autoconfiguración de datos. 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 OWD (Order Warehouse Distributor)​

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​