marketplaces-api-rest

1. Descripción general

Según el pom.xml, el proyecto se describe como "Marketplaces api rest". Es una fachada REST muy fina que recibe notificaciones webhook de Mercado Libre, las persiste tal cual (sin procesar) en base de datos, y delega toda la lógica de negocio a librerías internas de Hawkers para su procesamiento asíncrono posterior por otro sistema.

2. Información técnica

Campo	Valor
`artifactId`	`marketplaces-api-rest`
`groupId`	`com.hawkersco`
`version`	`1.0.25`
Java	25
Spring Boot	4.0.6
Tipo de artefacto	`jar` (ejecutable, API web de larga duración)
Módulos	No aplica (proyecto de módulo único)

3. Arquitectura y diseño

MarketplacesApiRestApplication — punto de entrada; configura Tomcat para permitir barras codificadas (ALLOW_ENCODED_SLASH).
.controller — MarketplacesApiRestController, único controlador con 3 endpoints.
.config — MarketplacesApiRestConfig (bean MeliNotificationService + PersistenceManagedTypes vía PersistenceManagedTypesScanner sobre com.hawkersco.logisticscommons.dao).

flowchart TD
    A[Mercado Libre] -->|"POST /api/notifications (sin autenticar)"| B[MarketplacesApiRestController]
    B -->|guarda rawData, isProcessed=false| C[(logistics · MeliNotification)]
    C -.->|procesamiento asíncrono posterior| D[Otro sistema del ecosistema]

El controlador se limita a recibir el cuerpo JSON crudo de la notificación, construir una entidad MeliNotification (con isProcessed=false) y persistirla — no hay parseo, validación de esquema ni verificación de firma/origen de la petición.

4. Dependencias principales

Dependencia	Propósito
`spring-boot-starter-web`	API REST
`com.hawkersco:logistics-commons`	Entidad `MeliNotification` y `MeliNotificationService`
`com.hawkersco:pi-function-commons`	`DateUtils`

No hay dependencia spring-boot-starter-security ni ninguna librería de autenticación.

5. API / Endpoints

Todos bajo el prefijo /api salvo el health check raíz.

Método	Ruta	Descripción	Autenticación
`GET`	`/api`	Health check	Pública
`GET`	`/api/check-domain`	Comprobación de dominio	Pública
`POST`	`/api/notifications`	Recibe y persiste una notificación cruda de marketplace	Ninguna (ver hallazgo de seguridad)

6. Integraciones externas

Sistema	Protocolo	Dirección	Detalle
Mercado Libre (webhook)	HTTP POST entrante	Entrante	Notificaciones de eventos del marketplace
PostgreSQL (`logistics`)	JDBC	Saliente	Persistencia de la tabla `MeliNotification`

7. Configuración

En producción (application-pro.properties) las credenciales llegan por variables de entorno inyectadas como Secret de Kubernetes; en local (application.properties) el repositorio contiene actualmente valores reales hardcodeados (ver alerta de seguridad).

Clave	Descripción
`server.port`	Puerto de escucha (`80`)
`server.tomcat.relaxed-query-chars`	Permite caracteres especiales (`{`, `}`, `[`, `]`, `^`, `\|`) en parámetros de consulta, necesarios para ciertos payloads de marketplace
`spring.datasource.*`	Credenciales de la BD `logistics`

⚠️ Alerta de seguridad — endpoint de recepción sin ninguna verificación de origen

POST /api/notifications no aplica ninguna autenticación, verificación de firma ni validación de origen sobre las peticiones entrantes: cualquiera que conozca la URL puede enviar un cuerpo JSON arbitrario, que se persistirá en la BD como si fuera una notificación legítima de Mercado Libre, quedando a la espera de ser procesada por el sistema asíncrono posterior. No hay spring-boot-starter-security en el pom.xml ni ningún filtro/interceptor en el código. Mismo patrón de ausencia de autenticación ya detectado en logisfashion y en varios endpoints de logistics-change-status en este ecosistema.

Además, el fichero application.properties (perfil local) contiene la contraseña real en texto plano de la base de datos PostgreSQL logistics (la misma ya señalada como expuesta en múltiples proyectos de este ecosistema). No se ha reproducido en este documento. Se recomienda:

Añadir verificación de la firma/origen de las notificaciones de Mercado Libre (Meli firma sus webhooks; conviene validar el x-signature u origen IP conocido) antes de persistir el payload.
Rotar la contraseña de BD.
Sustituir el valor hardcodeado de application.properties por credenciales de un entorno de desarrollo aislado.

8. Persistencia

Base de datos PostgreSQL logistics (spring.jpa.hibernate.ddl-auto=none). Entidad relevante: MeliNotification (paquete com.hawkersco.logisticscommons.dao, escaneada vía PersistenceManagedTypesScanner, repositorio vía @EnableJpaRepositories). No hay Flyway/Liquibase en este repositorio.

9. Procesos programados y mensajería

No aplica a este proyecto. No hay @Scheduled ni CronJob — se despliega como Deployment de larga duración que atiende webhooks entrantes en tiempo real.

10. Ejecución en local

Requisitos previos: JDK 25, Maven, acceso a la BD logistics.

# Compilar
./mvnw clean install

# Compilar sin tests
./mvnw -B -DskipTests clean install

# Ejecutar la aplicación localmente
./mvnw spring-boot:run

# Ejecutar tests
./mvnw test

# Ejecutar un test concreto
./mvnw test -Dtest=MarketplacesApiRestApplicationTests

Verificación de que el servicio está operativo: GET /api o GET /api/check-domain (ambos públicos).

11. Despliegue

Imagen: construida con jib-maven-plugin (base eclipse-temurin:25-jre, containerizingMode=packaged), publicada en europe-west3-docker.pkg.dev/pi-saldum/pi-repo/marketplaces-api-rest:<tag>.
Orquestación: Kubernetes Deployment (una réplica) en el clúster GKE pi-cluster-hw, namespace pi, contenedor no privilegiado.
CI/CD (Jenkins): pipeline real de 3 etapas — Checkout → Build & Push → Deploy to GKE (con kubectl rollout status), consistente con lo descrito en el CLAUDE.md.

Job de Jenkins: https://jenkins-pi.hawkersco.net/job/marketplaces-api-rest/

12. Manejo de errores y logging

No hay un @RestControllerAdvice centralizado. El único punto de fallo controlado es el parseo de la fecha de creación (DateUtils.getDateNow), que ante un ParseException devuelve 400 Bad Request. El resto de la lógica no tiene manejo de errores explícito. Logging mediante java.util.logging.Logger estándar.

13. Notas y consideraciones

Ver alerta de seguridad en la sección 7: el endpoint de recepción de notificaciones no valida en absoluto el origen de la petición.
CLAUDE.md verificado y consistente con el código real: los 3 endpoints, el uso de PersistenceManagedTypesScanner, y el pipeline de Jenkins de 3 etapas coinciden con lo observado directamente en MarketplacesApiRestController y el Jenkinsfile.

1. Descripción general​

2. Información técnica​

3. Arquitectura y diseño​

4. Dependencias principales​

5. API / Endpoints​

6. Integraciones externas​

7. Configuración​

⚠️ Alerta de seguridad — endpoint de recepción sin ninguna verificación de origen​

8. Persistencia​

9. Procesos programados y mensajería​

10. Ejecución en local​

11. Despliegue​

12. Manejo de errores y logging​

13. Notas y consideraciones​