ADR 0009 §2 ya había anticipado esto: la shipping option actual es un
placeholder de negocio ($15.000 COP fijo), no un cálculo real por
peso/volumen -- y el modelo de direcciones del checkout (IDs DIVIPOLA
en vez de texto libre en lib/data/colombia.ts) ya se había construido
pensando en esta integración. Este commit la implementa.
Investigación en vivo (no solo documentación -- misma disciplina que
ya costó varios rehechos con las pasarelas de pago): la SPA de docs
públicas (apidoc.envioclickpro.com.co) no renderiza sin sesión, pero
está generada con apiDoc, así que se bajó y leyó directo su
api_data.json/api_project.json (spec completa real), y se probó
/quotation en vivo con la API key real del usuario -- 200 OK con
tarifas reales de PIBOX/COORDINADORA/ENVIA/RAPPI/TCC. Esto corrigió
varios datos mal asumidos de un plugin de WordPress desactualizado
usado como referencia inicial (API v1): la URL base real es
api.envioclickpro.com.co/api/v2 (no api.envioclickpro.com a secas), y
el header de auth real es "Authorization" a secas, no
"AuthorizationKey".
Hallazgo crítico evitado leyendo el código fuente de
@medusajs/utils/dist/common/define-config.js: defineConfig() ya
registra por defecto un módulo de fulfillment con el provider
manual_manual, aunque medusa-config.ts no lo mencione explícitamente
-- pero transformModules() indexa por serviceName y el último que
llega pisa al anterior (no mezcla providers). Agregar un bloque propio
de fulfillment sin incluir también manual_manual ahí habría roto en
silencio el envío manual que ya usa la shipping option existente.
Verificado cargando la config compilada real: ambos providers quedan
registrados juntos.
- src/modules/envioclick-fulfillment/: AbstractFulfillmentProviderService.
calculatePrice() cotiza en vivo durante el checkout -- Medusa advierte
explícitamente que un error acá bloquea el checkout completo, así que
NUNCA se deja propagar una excepción: cualquier falla (red, dirección
sin id DIVIPOLA, EnvíoClick caído) cae al precio fijo de $15.000 que
ya se usaba, para no romper la compra. createFulfillment() vuelve a
cotizar en el momento de generar la guía real en vez de reusar el
idRate mostrado en checkout (más correcto: CalculatedShippingOptionPrice
no tiene forma de persistir ese id entre llamadas, confirmado leyendo
el tipo real, y un idRate viejo podría estar vencido si el fulfillment
pasa horas/días después). cancelFulfillment() sí cancela de verdad
(cancellation/batch/order existe y está confirmado, a diferencia del
refund de ePayco que quedó sin implementar).
- Solo 1 paquete por cotización/guía (límite real de la API, confirmado:
"min 1, max 1") -- el carrito se agrega a un solo paquete. Como hoy
NINGÚN producto tiene peso/dimensiones cargados (confirmado en vivo:
18 productos activos, 0 con weight), se usa un paquete de fallback
conservador completo en vez de mezclar datos reales con inventados a
medias -- la cotización no va a ser precisa hasta que se carguen esos
datos (tarea de datos, no de código, fuera de alcance de este commit).
- Frontend: cambio chico pero necesario en checkout-client.tsx/
medusa-cart.ts -- el checkout mandaba el nombre de la ciudad a Medusa,
nunca el id DIVIPOLA (aunque el form sí lo tenía disponible). Hay
municipios con el mismo nombre en distintos departamentos de Colombia,
así que el nombre solo no alcanza para identificar la ciudad sin
ambigüedad -- se guarda el id real en la metadata de la dirección
(Medusa sí tiene ese campo), que el fulfillment provider lee para
derivar el código DANE real que pide EnvíoClick (5 dígitos + "000" de
relleno, confirmado contra su propio ejemplo: "11001000" = Bogotá).
Pendiente de verificar con una llamada real (no se quiso generar una
guía de prueba en la cuenta real del usuario sin avisar): /shipment_sandbox
y cancellation/batch/order, verificados contra la spec oficial real
pero no probados en vivo todavía.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01THZFwPzrwv6VAbuwmaf5vR
devopsandClaude Sonnet 5
c507da8abc