Skip to main content

Especificación de Integración: Interfaz de Pedidos GEPP → Oracle Cloud


1. Resumen Ejecutivo y Arquitectura General​

El presente documento define la especificación técnica y de negocio para el flujo de ingesta, homologación, enriquecimiento y transformación de órdenes de compra recibidas desde GEPP para su inserción en Oracle Cloud OM (Order Management / Order Hub) a través del middleware Omnicanal Nexus.

La integración adopta un modelo desacoplado mediante mensajería asíncrona (Pub/Sub) garantizando resiliencia operativa, reintentos automáticos y trazabilidad de extremo a extremo hacia el API REST de Oracle Cloud (salesOrdersForOrderHub).


2. Arquitectura de Mensajería Asíncrona (Pub/Sub)​

Para garantizar la entrega confiable y el desacoplamiento entre la recepción de la orden de compra y el procesamiento hacia Oracle Cloud, se implementa una topología de mensajería basada en tópicos:

TópicoPublisherConsumerPropósito / Ciclo de Vida
nexus.purchase-order.requestedOutbox Publisher (Purchase Order API)Fusion WorkerSolicitud de creación de OC validada y persistida. Dispara el procesamiento y homologación del pedido.
nexus.purchase-order.retryFusion Worker / Retry APIFusion WorkerCola de reintento automático con backoff exponencial o reintento manual ante fallos recuperables (e.g., timeout en Oracle).
nexus.purchase-order.dlqFusion WorkerOperador / Proceso de limpiezaDead Letter Queue para mensajes con intentos agotados o errores no recuperables (e.g., datos maestros inexistentes, SKU no mapeado).

3. Diagrama de Flujo del Proceso​

4. Matriz de Mapeo de Atributos​

4.1. Header (Cabecera del Pedido)​

Campo Destino (Oracle Cloud)Tipo de DatoOrigen / Regla de ExtracciónEjemplo Real
SourceTransactionNumberStringNEXUS.noPedidoNEXUS0000001
SourceTransactionSystemStringConstante FijaOPS
SourceTransactionIdStringNEXUS.noPedidoNEXUS0000001
BusinessUnitNameStringCatálogo alp_cat_inv_perfiles_items.bu_nameUN_MACRO_CEDIS
RequestingBusinessUnitNameStringCatálogo alp_cat_inv_perfiles_items.bu_nameUN_MACRO_CEDIS
BuyingPartyNameStringMaestro Clientes mv_cat_oracle_clientes.party_nameBEBIDAS PURIFICADAS
BuyingPartyContactNameString / NullPor defecto null o asignado por perfilnull
TransactionTypeStringCatálogo alp_cat_inv_perfiles_items.tipo_pedidoGNS GPLP MACROCEDIS SECOS NAVE13
RequestedShipDateISO 8601GEPP_JSON.dateJSON (formateado UTC)2026-11-10T00:00:00.000+00:00
RequestedFulfillmentOrganizationNameStringCatálogo alp_cat_inv_perfiles_items.org_nameMACRO CEDIS - NAVE 13 SECO
PaymentTermsString / NullGEPP_JSON.terminoPago (o null si no aplica)null
FreezePriceFlagBooleanConstante Fijafalse
FreezeShippingChargeFlagBooleanConstante Fijafalse
FreezeTaxFlagBooleanConstante Fijafalse
SubmittedFlagBooleanConstante Fijatrue
SourceTransactionRevisionNumberIntegerConstante Fija1
CustomerPONumberStringGEPP_JSON.noOc"123"

4.2. Clientes y Domicilios (billToCustomer & shipToCustomer)​

Bloque JSONAtributo OracleTipo de DatoOrigen / LógicaEjemplo Real
billToCustomerPartyNameStringmv_cat_oracle_clientes.party_name (BILL_TO)BEBIDAS PURIFICADAS
billToCustomerAccountNumberStringmv_cat_oracle_clientes.account_number191492
billToCustomerAddress1StringDomicilio fiscal calle/númeroAVENIDA SANTA FE
billToCustomerCityStringPoblación o delegación fiscalSANTA FE CUAJIMALPA
billToCustomerStateStringEntidad federativaCDMX
billToCustomerPostalCodeStringCódigo postal fiscal05348
billToCustomerCountyStringMunicipio o alcaldíaCUAJIMALPA DE MORELOS"
billToCustomerProvinceString / NullProvincia complementarianull
billToCustomerCountryStringCódigo de país ISOMX
shipToCustomerPartyNameStringmv_cat_oracle_clientes.party_name (SHIP_TO)BEBIDAS PURIFICADAS
shipToCustomerPartyIdLongmv_cat_oracle_clientes.party_id300000219485505
shipToCustomerPartyNumberStringmv_cat_oracle_clientes.party_number191579
shipToCustomerSiteIdLongmv_cat_oracle_clientes.site_id100000440324981
shipToCustomerAddress1StringDirección del punto de entregaAVENIDA SANTA FE
shipToCustomerCityStringCiudad de entregaCRUZ MANCA
shipToCustomerCountyStringDelegación/Municipio de entregaCRUZ MANCA
shipToCustomerPostalCodeStringCódigo postal de entrega05349
shipToCustomerCountryStringCódigo de paísMX
shipToCustomerContactIdLong / NullIdentificador de contacto en sitionull

4.3. Líneas de Pedido (lines)​

Atributo OracleTipo de DatoOrigenTransformación / ReglaEjemplo Real
SourceTransactionLineIdStringNEXUS.noLineaIdentificador único de partida en el pedidoNEXUS0000001-1
SourceTransactionLineNumberStringNEXUS.noLineaNúmero secuencial de línea visibleNEXUS0000001-1
SourceTransactionScheduleIdStringNEXUS.noLineaSecuencia de entrega vinculada 1:1NEXUS0000001-1
SourceScheduleNumberStringNEXUS.noLineaNúmero secuencial del schedule1
TransactionCategoryCodeStringConstanteCategoría de la transacciónORDER
TransactionLineTypeStringConstanteTipo de línea de pedidoBuy
ProductNumberStringalp_cat_inv_perfiles_items.item_skuSKU homologado vía código de barrasLEUP420
OrderedQuantityDecimal / IntGEPP_JSON.cantidad o calculadaCantidad directa o multiplicada por factor5760
OrderedUOMStringGEPP_JSON.uom o 'PIEZA'UDM de entrada o forzada a piezasPIEZA

5. Regla de Negocio Crítica: Validación y Conversión de UDM​

La unidad de medida enviada por GEPP (GEPP_JSON.uom) se somete a validación frente a las unidades asignadas al artículo en el catálogo de perfiles de cliente (alp_cat_inv_perfiles_items).

  • Escenario 1 (Coincidencia Directa):

    • Si GEPP_JSON.uom == alp_cat_inv_perfiles_items.item_uom:
      • OrderedQuantity = GEPP_JSON.cantidad
      • OrderedUOM = GEPP_JSON.uom
  • Escenario 2 (Conversión por Factor):

    • Si la unidad enviada no coincide con el perfil base, se consulta alp_cat_inv_items_uom_conversions:
      • OrderedQuantity = GEPP_JSON.cantidad * conversion_rate
      • OrderedUOM = 'PIEZA'

6. Consultas SQL de Soporte (omnicanal.general_catalogs)​

A continuación se presentan los queries exactos implementados por el middleware Nexus para la resolución de clientes, artículos y reglas de conversión.


6.1. Consulta 1: Resolución de Perfil y Clientes (Header, Bill-To y Ship-To)​

info

Esta consulta recibe el RFC del cliente emisor (:invoiceTo, extrayendo la subcadena posterior al delimitador | si viene compuesto) e integra en un solo dataset la información fiscal y de entrega física.

Ej. "Bebidas Purificadas S. de R.L. de C.V.|BPU7901018D4" invoiceTo = BPU7901018D4

-- Obtención de perfiles y cuentas maestras a partir del RFC emisor
select perfil.perfil_code
, perfil.perfil
, perfil.org1_code
, perfil.org2_code
, bill_to.nombre BuyingPartyName
, bill_to.nombre billToCustomer_PartyName
, bill_to.numero_cuenta_cliente billToCustomer_AccountNumber
, bill_to.calle billToCustomer_Address1
, bill_to.colonia billToCustomer_City
, bill_to.estado billToCustomer_State
, bill_to.codigo_postal billToCustomer_PostalCode
, bill_to.alcaldia_municipio billToCustomer_County
, bill_to.pais billToCustomer_Country
, ship_to.nombre shipToCustomer_PartyName
, ship_to.party_id shipToCustomer_PartyId
, ship_to.site_use_id shipToCustomer_SiteId
, ship_to.identificador_registro shipToCustomer_PartyNumber
, ship_to.calle shipToCustomer_Address1
, ship_to.colonia shipToCustomer_City
, ship_to.alcaldia_municipio shipToCustomer_County
, ship_to.codigo_postal shipToCustomer_PostalCode
, ship_to.pais shipToCustomer_Country
from alp_cat_ar_perfiles_clientes perfil
join mv_cat_oracle_clientes bill_to
on perfil.cust_account_id = bill_to.cust_account_id
and bill_to.uso_sitio_cuenta = 'BILL_TO'
join mv_cat_oracle_clientes ship_to
on perfil.cust_account_id = ship_to.cust_account_id
AND perfil.cust_acct_site_id = ship_to.cust_acct_site_id
and ship_to.uso_sitio_cuenta = 'SHIP_TO'
where perfil.cliente_rfc = :invoiceTo

6.2. Consulta 2: Resolución de Artículo y Unidad Organizacional​

info

Permite obtener el artículo homologado (item_code), la unidad operativa, el almacén de fulfillment y el tipo de pedido configurado en el perfil.

SELECT org_bu_name
, org_name
, org_code
, tipo_pedido
, item_code
, item_uom
, item_quantity
FROM alp_cat_inv_perfiles_items
WHERE perfil_code = :perfil_code -- Obtenido de Consulta 1 (e.g. 'PE016')
AND item_upc = :codbarras; -- Código de barras de los Artículos de GEPP (e.g. '7501055900039')
note

Cada código de barras (item_upc) identifica de manera única una presentación física o nivel de empaque del producto.

Esto significa que un mismo producto puede tener diferentes códigos de barras según su presentación. Por ejemplo, la pieza individual de LEUP190 tiene un código de barras distinto al de la caja corrugada que la contiene.

Por lo tanto, la búsqueda mediante item_upc permite identificar con precisión la presentación específica del producto que solicita el cliente.


6.3. Consulta 3: Factor de Conversión de Unidades de Medida​

Se ejecuta en caso de discrepancia entre la UDM enviada por GEPP y la registrada en el perfil del artículo (item_uom).

SELECT conversion
FROM alp_cat_inv_items_uom_conversions aciiuc
WHERE item_code = :item_code -- Obtenido de Consulta 2 (e.g. 'LEUP420' o 'LEES675')
AND UOM = :uom; -- Unidad de medida enviada por GEPP (e.g. 'CAJA')
info

Si la unidad de medida recibida no está configurada en el Perfil del Artículo, se consultará el catálogo de conversiones para obtener el factor correspondiente y convertir la cantidad solicitada a piezas (PIEZA), que será la unidad de medida utilizada finalmente.


7. Estrategia de Manejo de Excepciones y Resiliencia​

  1. Errores de Resolución en PostgreSQL (Datos Maestros Inexistentes):
    • Si no se encuentra registro en alp_cat_ar_perfiles_clientes por RFC, o no existe coincidencia de item_upc en alp_cat_inv_perfiles_items, el procesamiento se aborta de forma preventiva y se envía al tópico nexus.purchase-order.dlq con el código de error correspondiente.
  2. Falla en Factor de Conversión de UDM:
    • Si la UDM no existe en el perfil del artículo y tampoco se encuentra factor de conversión en alp_cat_inv_items_uom_conversions, se enruta a nexus.purchase-order.dlq catalogado como error de configuración de catálogo.
  3. Errores de Conectividad / Timeout con Oracle Cloud (HTTP 5xx, 429):
    • El worker canaliza el mensaje a nexus.purchase-order.retry para reintentos progresivos basados en backoff exponencial.
  4. Rechazo Funcional por Validación Oracle (HTTP 400 Bad Request):
    • Si Oracle rechaza el payload por reglas de validación en Order Hub, la transacción se marca como fallida y se envía a nexus.purchase-order.dlq con la traza de respuesta de Oracle para su revisión manual.