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ópico | Publisher | Consumer | Propósito / Ciclo de Vida |
|---|---|---|---|
nexus.purchase-order.requested | Outbox Publisher (Purchase Order API) | Fusion Worker | Solicitud de creación de OC validada y persistida. Dispara el procesamiento y homologación del pedido. |
nexus.purchase-order.retry | Fusion Worker / Retry API | Fusion Worker | Cola de reintento automático con backoff exponencial o reintento manual ante fallos recuperables (e.g., timeout en Oracle). |
nexus.purchase-order.dlq | Fusion Worker | Operador / Proceso de limpieza | Dead 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 Dato | Origen / Regla de Extracción | Ejemplo Real |
|---|---|---|---|
SourceTransactionNumber | String | NEXUS.noPedido | NEXUS0000001 |
SourceTransactionSystem | String | Constante Fija | OPS |
SourceTransactionId | String | NEXUS.noPedido | NEXUS0000001 |
BusinessUnitName | String | Catálogo alp_cat_inv_perfiles_items.bu_name | UN_MACRO_CEDIS |
RequestingBusinessUnitName | String | Catálogo alp_cat_inv_perfiles_items.bu_name | UN_MACRO_CEDIS |
BuyingPartyName | String | Maestro Clientes mv_cat_oracle_clientes.party_name | BEBIDAS PURIFICADAS |
BuyingPartyContactName | String / Null | Por defecto null o asignado por perfil | null |
TransactionType | String | Catálogo alp_cat_inv_perfiles_items.tipo_pedido | GNS GPLP MACROCEDIS SECOS NAVE13 |
RequestedShipDate | ISO 8601 | GEPP_JSON.dateJSON (formateado UTC) | 2026-11-10T00:00:00.000+00:00 |
RequestedFulfillmentOrganizationName | String | Catálogo alp_cat_inv_perfiles_items.org_name | MACRO CEDIS - NAVE 13 SECO |
PaymentTerms | String / Null | GEPP_JSON.terminoPago (o null si no aplica) | null |
FreezePriceFlag | Boolean | Constante Fija | false |
FreezeShippingChargeFlag | Boolean | Constante Fija | false |
FreezeTaxFlag | Boolean | Constante Fija | false |
SubmittedFlag | Boolean | Constante Fija | true |
SourceTransactionRevisionNumber | Integer | Constante Fija | 1 |
CustomerPONumber | String | GEPP_JSON.noOc | "123" |
4.2. Clientes y Domicilios (billToCustomer & shipToCustomer)
| Bloque JSON | Atributo Oracle | Tipo de Dato | Origen / Lógica | Ejemplo Real |
|---|---|---|---|---|
billToCustomer | PartyName | String | mv_cat_oracle_clientes.party_name (BILL_TO) | BEBIDAS PURIFICADAS |
billToCustomer | AccountNumber | String | mv_cat_oracle_clientes.account_number | 191492 |
billToCustomer | Address1 | String | Domicilio fiscal calle/número | AVENIDA SANTA FE |
billToCustomer | City | String | Población o delegación fiscal | SANTA FE CUAJIMALPA |
billToCustomer | State | String | Entidad federativa | CDMX |
billToCustomer | PostalCode | String | Código postal fiscal | 05348 |
billToCustomer | County | String | Municipio o alcaldía | CUAJIMALPA DE MORELOS" |
billToCustomer | Province | String / Null | Provincia complementaria | null |
billToCustomer | Country | String | Código de país ISO | MX |
shipToCustomer | PartyName | String | mv_cat_oracle_clientes.party_name (SHIP_TO) | BEBIDAS PURIFICADAS |
shipToCustomer | PartyId | Long | mv_cat_oracle_clientes.party_id | 300000219485505 |
shipToCustomer | PartyNumber | String | mv_cat_oracle_clientes.party_number | 191579 |
shipToCustomer | SiteId | Long | mv_cat_oracle_clientes.site_id | 100000440324981 |
shipToCustomer | Address1 | String | Dirección del punto de entrega | AVENIDA SANTA FE |
shipToCustomer | City | String | Ciudad de entrega | CRUZ MANCA |
shipToCustomer | County | String | Delegación/Municipio de entrega | CRUZ MANCA |
shipToCustomer | PostalCode | String | Código postal de entrega | 05349 |
shipToCustomer | Country | String | Código de país | MX |
shipToCustomer | ContactId | Long / Null | Identificador de contacto en sitio | null |
4.3. Líneas de Pedido (lines)
| Atributo Oracle | Tipo de Dato | Origen | Transformación / Regla | Ejemplo Real |
|---|---|---|---|---|
SourceTransactionLineId | String | NEXUS.noLinea | Identificador único de partida en el pedido | NEXUS0000001-1 |
SourceTransactionLineNumber | String | NEXUS.noLinea | Número secuencial de línea visible | NEXUS0000001-1 |
SourceTransactionScheduleId | String | NEXUS.noLinea | Secuencia de entrega vinculada 1:1 | NEXUS0000001-1 |
SourceScheduleNumber | String | NEXUS.noLinea | Número secuencial del schedule | 1 |
TransactionCategoryCode | String | Constante | Categoría de la transacción | ORDER |
TransactionLineType | String | Constante | Tipo de línea de pedido | Buy |
ProductNumber | String | alp_cat_inv_perfiles_items.item_sku | SKU homologado vía código de barras | LEUP420 |
OrderedQuantity | Decimal / Int | GEPP_JSON.cantidad o calculada | Cantidad directa o multiplicada por factor | 5760 |
OrderedUOM | String | GEPP_JSON.uom o 'PIEZA' | UDM de entrada o forzada a piezas | PIEZA |
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.cantidadOrderedUOM=GEPP_JSON.uom
- Si
-
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_rateOrderedUOM='PIEZA'
- Si la unidad enviada no coincide con el perfil base, se consulta
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)
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
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')
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')
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
- Errores de Resolución en PostgreSQL (Datos Maestros Inexistentes):
- Si no se encuentra registro en
alp_cat_ar_perfiles_clientespor RFC, o no existe coincidencia deitem_upcenalp_cat_inv_perfiles_items, el procesamiento se aborta de forma preventiva y se envía al tópiconexus.purchase-order.dlqcon el código de error correspondiente.
- Si no se encuentra registro en
- 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 anexus.purchase-order.dlqcatalogado como error de configuración de catálogo.
- Si la UDM no existe en el perfil del artículo y tampoco se encuentra factor de conversión en
- Errores de Conectividad / Timeout con Oracle Cloud (HTTP 5xx, 429):
- El worker canaliza el mensaje a
nexus.purchase-order.retrypara reintentos progresivos basados en backoff exponencial.
- El worker canaliza el mensaje a
- 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.dlqcon la traza de respuesta de Oracle para su revisión manual.
- 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