Merge docs/adr0009-correccion-plugin-payu into main

Verificado el codigo/README real de los dos unicos paquetes de Medusa
que aparecen buscando 'PayU' (@tax1driver/medusa-payu y
medusa-plugin-payu de rigby-sh, este ultimo archivado desde
2025-03-21): ambos usan la terminologia de la API de PayU Polonia/CEE
(clientId/posId/secondKey, OAuth), no la de PayU LatAm
(apiLogin/apiKey/accountId, developers.payulatam.com, la que cubre
Colombia). 'PayU' es una marca compartida por dos productos distintos.

La decision de negocio (PayU como proveedor) se mantiene -- cambia la
via tecnica: integracion via modulo de pago custom
(AbstractPaymentProvider de Medusa) contra la API real de PayU LatAm,
mismo tipo de esfuerzo que EnvioClick, no instalacion de plugin.

De paso, documenta las shipping options ya creadas y verificadas en
produccion (stock location, fulfillment set, service zone Colombia,
shipping option de 5.000 COP) incluyendo el paso no documentado que
las dejaba invisibles para el Store API (vinculo a sales channel).

workloads/docs-portal/docs/decisiones/0009-checkout-real.md

@@ -126,28 +126,29 @@ Verificado contra fuentes reales el mismo día (no memoria):
   los métodos que se pidieron (PSE + Nequi "y demás bancos") sin que
   la cuenta bancaria propia del comercio sea Bancolombia.
 
-**Decisión:** PayU, vía el plugin comunitario `@tax1driver/medusa-payu`
-(compatibilidad declarada con Medusa 2.4.0+, cubre nuestra versión
-2.18.0). Wompi queda descartado por el requisito de registro
-Bancolombia/Nequi, no por limitación técnica del plugin en sí.
+**Decisión:** PayU como proveedor de pago (negocio) se mantiene. La vía
+técnica cambió el 2026-08-29 — ver nota de implementación al final de
+este documento: ningún plugin comunitario de Medusa sirve para PayU
+LatAm, hace falta un módulo de pago custom. Wompi queda descartado por
+el requisito de registro Bancolombia/Nequi, no por limitación técnica.
 
 **Pendiente antes de implementar (no resoluble en este ADR):**
 
 - Registro real de comercio en PayU (persona natural o jurídica —
   jurídica pide NIT, representante legal y estados financieros
-  básicos) y credenciales reales (API keys, merchant ID, webhook
-  config) — nunca generadas ni asumidas por mí.
-- Verificar el código fuente real de `@tax1driver/medusa-payu` en el
-  tag exacto a instalar antes de confiar en su documentación, misma
-  disciplina que ya destapó desviaciones reales en el plugin de
-  Meilisearch (ADR 0006).
+  básicos) y credenciales reales (`apiLogin`, `apiKey`, `merchantId`,
+  `accountId` — terminología real de la API de PayU LatAm, ver nota de
+  implementación) — nunca generadas ni asumidas por mí.
+- Escribir el módulo de pago custom para PayU LatAm (no instalar un
+  plugin — no existe ninguno real para esta API, ver nota de
+  implementación).
 
 ## Opciones consideradas
 
 | Opción | A favor | En contra |
 |---|---|---|
 | **Stripe** | Integración core de Medusa, mejor documentada, configuración mínima | No acepta comercios registrados en Colombia — bloqueador de negocio, no técnico |
-| **PayU** (`@tax1driver/medusa-payu`) — **elegido** | Compatibilidad declarada explícitamente con Medusa 2.4.0+ (cubre 2.18.0); solo exige cuenta bancaria colombiana a nombre del comercio, sin banco específico (encaja con Davivienda/Lulo Bank/Banco de Bogotá); soporta PSE + Nequi + Daviplata para el cliente sin importar el banco del comercio | Plugin comunitario, no de primera clase; requiere la misma verificación de código fuente que ya se le hizo al plugin de Meilisearch antes de confiar en él |
+| **PayU** — **elegido** (proveedor de negocio; integración técnica ahora es custom, ver nota de implementación) | Solo exige cuenta bancaria colombiana a nombre del comercio, sin banco específico (encaja con Davivienda/Lulo Bank/Banco de Bogotá); soporta PSE + Nequi + Daviplata para el cliente sin importar el banco del comercio | Ningún plugin de Medusa real sirve para su API LatAm (`apiLogin`/`apiKey`/`accountId`) — los dos paquetes que parecían encajar por nombre son en realidad para PayU Polonia/CEE (`clientId`/`posId`/`secondKey`), uno de ellos archivado; requiere módulo de pago custom |
 | **Wompi** (`medusa-payment-wompi-col`) | Liquidación directa en COP vía Bancolombia | Exige cuenta Bancolombia o, como mínimo, Nequi solo para **registrarse** como comercio — ninguno de los bancos disponibles (Davivienda/Lulo Bank/Banco de Bogotá) califica sin abrir una cuenta nueva; además, sin versión de Medusa documentada ni actividad reciente visible en el plugin |
 | **Seguir con WhatsApp** (no pago en línea) | Cero riesgo nuevo, cero dependencia externa | No resuelve el objetivo real (transacción completa sin intervención manual); no es checkout, es lo que ya existe hoy |
 
@@ -156,17 +157,14 @@ Bancolombia/Nequi, no por limitación técnica del plugin en sí.
 - Las shipping options son un prerequisito independiente del proveedor
   y deben configurarse primero — sin ellas ningún flujo de checkout
   completa, sea cual sea el pago.
-- Al ser `@tax1driver/medusa-payu` un plugin comunitario (no de
-  primera clase como Stripe), exige la misma disciplina de
-  verificación que ya destapó desviaciones reales en el plugin de
-  Meilisearch (ADR 0006, nota de implementación): leer el código
-  fuente en el tag exacto que se va a instalar, no el README genérico
-  ni asumir que "compatibilidad declarada" significa "verificado en
-  este proyecto".
-- Los webhooks de pago (registrados por el plugin en
-  `/hooks/payment/payu`) deben validarse en vivo contra la cadena de
-  red real del lab antes de confiar en el flujo, dado el precedente de
-  `incidente-cloudflared-504-quic-2026-08.md`.
+- El pago de PayU se implementa como módulo custom (`AbstractPaymentProvider`
+  de Medusa) contra la API real de PayU LatAm, no como instalación de
+  un plugin de terceros — más superficie propia para mantener, mismo
+  patrón de esfuerzo que ya se identificó para EnvíoClick en §2.
+- Los webhooks de pago (a definir en el módulo custom, apuntando a la
+  URL de notificación real de PayU LatAm) deben validarse en vivo
+  contra la cadena de red real del lab antes de confiar en el flujo,
+  dado el precedente de `incidente-cloudflared-504-quic-2026-08.md`.
 - Se acepta como deuda: si en el futuro se abre una cuenta Bancolombia
   o Nequi, Wompi (liquidación más directa en COP) vuelve a ser una
   opción válida a reevaluar — no se descarta por limitación técnica,
@@ -174,3 +172,56 @@ Bancolombia/Nequi, no por limitación técnica del plugin en sí.
 - Revertir esta decisión implica deshabilitar el provider en la región
   y volver al botón de WhatsApp — el carrito y el catálogo no cambian
   de forma, solo el paso final.
+
+## Nota de implementación (2026-08-29): shipping options creadas
+
+Bloqueador de §1 resuelto en producción, verificado extremo a extremo
+contra el Store API real (no solo creado en Admin):
+
+- Stock location "Bodega principal ARI Shopping" (`sloc_01M15G3D1336V8WQW3VZQRP6AN`).
+- Fulfillment set + zona de servicio "Colombia" (`geo_zone` tipo país, `co`).
+- Provider `manual_manual` habilitado en la ubicación.
+- Shipping option "Envío nacional estándar", tarifa fija $15.000 COP
+  (placeholder de negocio dentro del rango real de mercado
+  $12.000–$18.000 que dio el usuario, no un cálculo por peso/volumen —
+  eso es justamente lo que EnvíoClick resolvería más adelante),
+  vinculada al Default Shipping Profile y a la región Colombia/COP.
+- **Paso no documentado en ningún lado y que rompía todo en silencio:**
+  la stock location tiene que estar vinculada al Sales Channel
+  (`/admin/stock-locations/{id}/sales-channels`) para que el Store API
+  devuelva la shipping option — sin esto, `GET /store/shipping-options`
+  devolvía `[]` vacío pese a que el fulfillment set, la zona de
+  servicio y el provider ya estaban bien configurados. Confirmado con
+  un carrito de prueba real (dirección `co` + `cart_id`) antes y
+  después del vínculo.
+
+## Nota de implementación 2 (2026-08-29): corrección — no existe plugin real para PayU LatAm
+
+Antes de instalar nada se verificó el código/README real de los dos
+únicos paquetes de Medusa que aparecen buscando "PayU" — misma
+disciplina que ya aplicó ADR 0006 al plugin de Meilisearch, esta vez
+con un resultado distinto: **ninguno de los dos sirve.**
+
+- `@tax1driver/medusa-payu`: opciones de configuración `clientId`,
+  `clientSecret`, `merchantPosId`, `secondKey` — terminología exacta
+  de la API de **PayU Polonia/CEE** (OAuth + `posId`), no de PayU
+  LatAm.
+- `medusa-plugin-payu` (`rigby-sh/medusa-plugin-payu`): mismo problema
+  (`clientId`, `posId`, sandbox en `secure.snd.payu.com`, dominio de
+  PayU Europa) y además **archivado desde 2025-03-21** — sin
+  mantenimiento.
+- La API real que se necesita, PayU LatAm
+  (`developers.payulatam.com`, la que cubre Colombia junto con
+  Argentina/Brasil/Chile/México/Panamá/Perú), autentica con
+  `apiLogin`/`apiKey` en el objeto merchant y `accountId` en el
+  objeto order — un modelo de autenticación distinto, no solo nombres
+  de campo distintos.
+
+"PayU" es una marca compartida por dos productos/API históricamente
+separados (LatAm vs. Europa/CEE); un paquete que dice "PayU" a secas
+sin especificar LatAm es, con alta probabilidad, para el producto
+europeo. **Consecuencia:** la integración de pago se implementa como
+módulo custom de Medusa (`AbstractPaymentProvider`) contra
+`developers.payulatam.com` directamente — mismo tipo de esfuerzo que
+ya se había anticipado para EnvíoClick en §2, no una instalación de
+plugin como asumía la decisión original de este ADR.