Guía técnica para implementar Punch-Out B2B con OCI y cXML

OCI vs. cXML: cómo integrar un catálogo B2B con plataformas de procurement y ERP

Introducción

Cuando quieres integrar tu eCommerce B2B con el sistema de compras de un cliente corporativo, el reto va mucho más allá de “poner un botón que lleve al catálogo”.

Una integración real necesita un mecanismo para que dos sistemas puedan:

• autenticarse;
• intercambiar información;
• identificar productos;
• transportar cantidades y precios;
• devolver el carrito al sistema comprador;
• generar una orden de compra;
• enviarla en formato electrónico;
• recibir una respuesta;
• gestionar errores;
• mantener trazabilidad.

En este contexto aparecen con frecuencia dos tecnologías: OCI (Open Catalog Interface) y cXML (Commerce XML).

Ambas participan en un ecosistema Punch-Out, cada una con una función distinta.

Los documentos técnicos de referencia describen una arquitectura en la que el catálogo del proveedor se conecta con el sistema de compras de una organización y, después, ambas partes intercambian las órdenes en cXML. Si buscas la visión de negocio antes que la técnica, empieza por cómo integrar un eCommerce B2B con ERP y sistemas de procurement.

1. Antes de hablar de protocolos: ¿qué es Punch-Out?

Punch-Out es un modelo de integración en el que el comprador inicia sesión desde su plataforma de procurement y llega al catálogo electrónico del proveedor.

El recorrido del usuario es:

1. Sistema de compras
2. Catálogo del proveedor
3. Selección de productos
4. Carrito
5. Regreso al sistema de compras
6. Aprobación
7. Orden de compra

Así, el comprador aprovecha la experiencia, la información técnica y la lógica comercial del catálogo del proveedor sin perder el control del proceso corporativo de procurement.

En B2B esto pesa, porque el catálogo puede contener:

• miles de SKUs;
• configuraciones;
• precios específicos;
• unidades de medida;
• información técnica;
• contratos;
• disponibilidad;
• productos sustitutos;
• relaciones entre productos.

El sistema de procurement, por su parte, controla:

• usuarios;
• autorizaciones;
• presupuestos;
• centros de costo;
• contratos;
• aprobaciones;
• órdenes de compra.

Punch-Out conecta ambos mundos. Si quieres la explicación desde cero, revisa qué es Punch-Out y cómo funciona en eProcurement.

2. ¿Dónde entra OCI?

OCI significa Open Catalog Interface.

En el modelo documentado, OCI conecta el catálogo del proveedor con el sistema comprador.

El documento técnico especifica:

Elemento	Configuración documentada
Punch-Out	OCI
Comunicación	HTTP / HTTPS
Método de acceso	GET / POST
Catálogo	Catálogo web del proveedor

La implementación documentada también pide que el catálogo sea compatible con el estándar OCI de SAP y esté disponible en Internet.

3. Arquitectura básica de una integración OCI

Una implementación se ve así:

┌──────────────────────┐
│ Sistema de Compras   │
│ / ERP del cliente    │
└──────────┬───────────┘
           │
           │ Punch-Out
           │ HTTP / HTTPS
           ▼
┌──────────────────────┐
│ Catálogo del         │
│ Proveedor            │
│                      │
│ eCommerce B2B        │
└──────────┬───────────┘
           │
           │ Carrito OCI
           ▼
┌──────────────────────┐
│ Sistema de Compras   │
│                      │
│ Aprobación / PO      │
└──────────────────────┘

Fíjate en el final: en un Punch-Out, el carrito no termina en el checkout tradicional del eCommerce. Regresa al sistema comprador.

4. ¿Qué pasa a nivel técnico durante el Punch-Out?

El sistema comprador hace una llamada al endpoint del proveedor.

El documento OCI contempla:

• URL;
• usuario;
• contraseña;
• HOOK_URL;
• método GET o POST.

El ejemplo de la documentación usa una URL conceptual con parámetros como:

https://www.supplier.com/punchoutlogin.jsp
?USERNAME=#USER#
&PASSWORD=#PASSWORD#
&HOOK_URL=#HOOK_URL#

En tu proyecto, sustituye esos valores por los que definan durante la implementación.

5. El endpoint de Punch-Out

Como proveedor, necesitas desarrollar o configurar un endpoint que pueda:

• recibir la solicitud;
• validar las credenciales;
• identificar al comprador;
• identificar el entorno;
• crear la sesión;
• guardar el HOOK_URL;
• abrir el catálogo;
• permitir la construcción del carrito;
• devolver el carrito al sistema comprador.

Por eso Punch-Out requiere lógica en backend, además de la configuración del frontend.

6. El HOOK_URL: uno de los elementos fundamentales

Al iniciar la sesión, el sistema comprador envía una dirección de retorno. Con ese valor, el catálogo del proveedor sabe:

“Cuando el comprador termine su selección, aquí debes enviar el carrito.”

El recorrido completo:

Sistema comprador
       │
       │ USERNAME
       │ PASSWORD
       │ HOOK_URL
       ▼
Catálogo proveedor
       │
       │ usuario selecciona productos
       ▼
Carrito
       │
       │ POST hacia HOOK_URL
       ▼
Sistema comprador

Prueba este punto con cuidado: una integración puede funcionar bien en todo el recorrido y fallar justo al regresar el carrito.

7. ¿Qué información debe regresar el catálogo?

El documento técnico define los campos que el proveedor debe enviar por la interfaz OCI. Entre ellos:

Campo OCI	Qué representa
NEW_ITEM-DESCRIPTION[n]	Descripción del producto. La especificación documentada establece un máximo de 40 caracteres.
NEW_ITEM-MATNR[n]	Número de material utilizado por el sistema comprador. Es opcional en esta implementación y tiene una longitud máxima documentada de 40 caracteres.
NEW_ITEM-LANGUAGE[p]	Código de idioma. El documento indica que utiliza códigos ISO.
NEW_ITEM-UNIT[n]	Unidad de medida. Debe utilizar códigos compatibles con el estándar definido para la integración.
NEW_ITEM-PRICE[n]	Precio unitario. La implementación documentada considera precio con dos posiciones decimales.
NEW_ITEM-QUANTITY[n]	Cantidad solicitada. El documento especifica valores enteros, sin cantidades parciales, para esta integración.
NEW_ITEM-PRICEUNIT	Unidad asociada al precio. Por ejemplo, el precio puede representar una cantidad determinada de unidades.
NEW_ITEM-CURRENCY[n]	Moneda. La documentación indica el uso de códigos ISO 4217 (por ejemplo: USD, MXN, EUR).

8. Identificación del producto: un punto crítico

Uno de los errores más caros en una integración B2B es asumir que “SKU” significa lo mismo para todos los sistemas. Puede haber:

• SKU del proveedor;
• SKU del fabricante;
• número de material del cliente;
• número contractual;
• número interno del ERP.

OCI contempla un campo para cada caso:

Campo OCI	Qué representa
NEW_ITEM-VENDORMAT[n]	Número de producto del proveedor.
NEW_ITEM-MANUFACTMAT[n]	Número de parte del fabricante.
NEW_ITEM-MANUFACTCODE[n]	Código del fabricante. La implementación documentada incluso muestra un ejemplo como FLUKE.

Con ellos mantienes la relación entre los distintos identificadores comerciales.

9. Categorías de producto

El campo NEW_ITEM-MATGROUP[n] representa la categoría o grupo de producto.

En el modelo documentado, el proveedor envía su clasificación (por ejemplo UNSPSC u otro estándar) y después ambas partes la mapean al grupo de materiales del sistema comprador.

Aquí entra lo que tratamos en la guía de estandarización de información de producto: una integración no arregla una mala estructura de producto. Si tus categorías están mal definidas, el problema viaja de un sistema a otro.

10. Otros campos OCI importantes

La implementación documentada contempla también:

Campo OCI	Qué representa
NEW_ITEM-CONTRACT[n]	Número de contrato.
NEW_ITEM-LEADTIME[n]	Tiempo de entrega.
NEW_ITEM-LONGTEXT_n:132	Descripción larga.
NEW_ITEM-VENDOR[n]	Código del proveedor.

El LEADTIME es opcional en esta implementación. Si el proveedor no lo envía, el sistema toma el lead time del contrato SAP.

11. Mapping: la parte que casi nadie ve

Supón que en tu eCommerce la unidad es EA y en el ERP del comprador es PC. Si ningún sistema reconoce la equivalencia, el producto llega a destino y el ERP lo interpreta mal.

Para evitarlo, la documentación contempla tablas de mapping para:

• monedas;
• idiomas;
• unidades de medida;
• categorías.

Ejemplo:

Sistema proveedor	Sistema comprador
USD	USD
MXN	MXN
EA	PC
BOX	CJ

Los valores reales dependen del acuerdo entre ambas organizaciones.

12. Ambientes QA y Producción

Una implementación profesional no arranca en producción. El documento define ambientes separados para QA / Test y PR / Production, cada uno con su propio:

• URL;
• método de acceso;
• usuario;
• contraseña.

Mantén separados los tres ambientes:

Desarrollo → QA → Producción

En QA puedes probar:

• autenticación;
• sesiones;
• productos;
• precios;
• cantidades;
• monedas;
• unidades;
• categorías;
• retorno del carrito;
• errores.

13. ¿Dónde entra cXML?

OCI resuelve el intercambio del catálogo y el carrito Punch-Out. cXML entra después, para los documentos transaccionales.

En la documentación analizada, el comprador envía la orden de compra con <OrderRequest> y el proveedor responde con el estándar de respuesta cXML. Ambas partes validan la estructura contra el DTD de cXML acordado para la integración.

14. Arquitectura OCI + cXML

Así se combinan las dos tecnologías:

             PUNCH-OUT
          ────────────────
Sistema de Compras
        │
        │ OCI
        ▼
Catálogo del Proveedor
        │
        │ Carrito
        ▼
Sistema de Compras
        │
        │ Aprobación
        ▼
          EDI / cXML
        ────────────────
        OrderRequest
             │
             ▼
      Sistema Proveedor
             │
             ▼
      Ventas / ERP
             │
             ▼
      Logística / Factura

• OCI ayuda a conectar la experiencia de catálogo y carrito.
• cXML permite estructurar el intercambio transaccional.

Juntas cubren el recorrido completo, del catálogo a la factura.

15. Punch-Out PO vs. Coded/Spot PO

La documentación cXML distingue entre Punch-Out PO y Release/Spot PO. La estructura general se parece; la diferencia está en cómo se identifica el producto.

Una Punch-Out PO usa <SupplierPartID>, el identificador del producto según el proveedor. Además, lleva un Extrinsic llamado PunchOut con valor TRUE.

Una Release/Spot PO lleva PunchOut = FALSE y puede usar <BuyerPartID>, el identificador del comprador.

16. Ejemplo de estructura cXML

Un OrderRequest puede empezar así:

<OrderRequest>
    <OrderRequestHeader
        orderID="123456"
        orderDate="2026-09-20T10:00:00-06:00"
        type="new"
        agreementID="CONTRACT-001"
        orderType="release"
        orderVersion="1">
        <Total>
            <Money currency="MXN">228.57</Money>
        </Total>
        <BillTo>
            ...
        </BillTo>
        <LegalEntity>
            ...
        </LegalEntity>
        <PaymentTerm>
            ...
        </PaymentTerm>
        <Contact role="buyer">
            ...
        </Contact>
    </OrderRequestHeader>
    <ItemOut
        quantity="57"
        lineNumber="00001">
        <ItemID>
            <SupplierPartID>SUP-71031617</SupplierPartID>
        </ItemID>
        <ItemDetail>
            <UnitPrice>
                <Money currency="MXN">4.01</Money>
            </UnitPrice>
            <Description>
                <ShortName>
                    Producto ejemplo
                </ShortName>
            </Description>
            <UnitOfMeasure>PC</UnitOfMeasure>
        </ItemDetail>
    </ItemOut>
</OrderRequest>

Anonimizamos y simplificamos este ejemplo a propósito. La estructura sigue el ejemplo de OrderRequest de la documentación de referencia.

17. ¿Qué significa cada elemento?

Elemento	Significado
orderID	Identificador de la orden. En términos prácticos: el número que permitirá rastrear la transacción.
orderDate	Fecha y hora de la orden. La documentación especifica formato ISO 8601.
type	Puede representar diferentes tipos de operación, incluyendo new, update y delete, según la estructura documentada.
agreementID	Identifica el acuerdo maestro cuando la orden corresponde a un contrato o acuerdo existente.
orderType	La documentación distingue Regular y Release, donde Release representa una liberación contra un acuerdo, contrato o blanket purchase order.

18. ItemOut: el corazón de las líneas de producto

Cada producto de la orden va en un <ItemOut>. Algunos elementos importantes:

• quantity
• lineNumber
• agreementItemNumber
• requestedDeliveryDate

Y dentro de <ItemID> pueden aparecer <SupplierPartID> y <BuyerPartID>.

En esta implementación, SupplierPartID es obligatorio para una Punch-Out PO.

19. SupplierPartAuxiliaryID

Usa este campo cuando SupplierPartID no basta para identificar un producto sin ambigüedad. La documentación lo describe como una clave auxiliar que, junto con SupplierID y SupplierPartID, identifica una parte de forma única. Te sirve en catálogos complejos donde un solo identificador comercial se queda corto.

20. Información logística

cXML también transporta información de <ShipTo> y <DeliverTo>, con datos como:

• dirección;
• planta;
• ubicación;
• edificio;
• área;
• persona receptora.

La documentación usa DeliverTo para indicar quién recibe. En B2B industrial esto pesa: una empresa puede tener una sola razón social y 20 plantas, así que el destino de entrega tiene que viajar como dato estructurado y no como una nota en la orden.

21. Comunicación cXML: HTTP POST

A diferencia de OCI, que acepta GET o POST, esta implementación cXML pide HTTP POST y aclara que no soporta SOAP. La URL productiva debe usar HTTPS o contar con un mecanismo de autenticación.

22. Autenticación

El documento contempla dos mecanismos:

Mecanismo	Descripción
Basic Authentication	Usuario + contraseña.
SharedSecret / Token	Un secreto compartido transmitido en el header de la comunicación.

La elección depende de la arquitectura y del acuerdo entre las partes. Para producción, te recomiendo:

HTTPS + autenticación + gestión segura de secretos.

23. Content-Type

La implementación documentada pide Content-Type: text/xml; charset="UTF-8" y el XML viaja en el body del POST:

POST /cxml/order HTTP/1.1
Host: supplier.example.com
Content-Type: text/xml; charset=UTF-8
Authorization: ...

<xml>
    ...
</xml>

24. La respuesta cXML

Al recibir el OrderRequest, el proveedor devuelve una respuesta cXML. El ejemplo documentado usa:

<Response>
    <Status code="200" text="OK"/>
</Response>

Es decir: HTTP 200 + respuesta cXML válida. Que el servidor “no marque error” no alcanza; tu aplicación tiene que procesar la orden y devolver la respuesta esperada.

25. Códigos HTTP: una parte crítica de la integración

La documentación distingue tres escenarios:

Código	Significado	Ejemplos
2xx · Success	El proveedor procesó la operación.	200 OK
4xx · Permanent Error	Alguien tiene que corregir el problema antes de reprocesar.	400 Bad Request, 401 Unauthorized, 403 Forbidden
5xx · Transient Error	Indica una falla temporal del servidor o la infraestructura.	500 Internal Server Error

26. ¿Qué hacer cuando falla una orden?

Una integración B2B se pone a prueba cuando algo falla. La documentación de esta implementación define un tratamiento para cada caso:

• Error 4xx: la plataforma no reenvía la PO por su cuenta y el caso pasa a un proceso manual.
• Error 5xx: la plataforma reintenta el envío. En el caso documentado hace tres intentos y después pasa a un proceso manual.

Además de definir el API, define qué pasa cuando el API falla. Toda integración necesita una estrategia de recuperación.

27. Idempotencia y trazabilidad

Los documentos se enfocan en una implementación concreta, pero hay un principio que conviene llevar al diseño: un reintento de comunicación no debe duplicar la orden. Para lograrlo, usa identificadores consistentes como orderID y payloadID.

El documento cXML describe payloadID como un identificador para logging y seguimiento que no cambia entre reintentos. Con él distingues una nueva orden de un reintento de la misma orden.

28. Service Status Response

La documentación también contempla una operación para comprobar si un servicio cXML está disponible: un HTTP GET que devuelve una respuesta cXML como esta:

<Response>
    <Status code="200" text="OK">
        Ping Response Message
    </Status>
</Response>

Puedes usarla como diagnóstico o health check.

29. ¿Cómo implementar OCI y cXML en un proyecto real?

Te recomiendo separar la implementación en fases.

Fase 1: Discovery

Definir:

• comprador;
• proveedor;
• sistemas involucrados;
• ERP;
• eCommerce;
• procurement;
• catálogo;
• contratos;
• documentos;
• responsables técnicos;
• responsables comerciales.

La documentación de referencia incluye hasta una matriz de contactos con responsables de negocio y técnicos. Esta fase corresponde al Discovery de mi metodología de trabajo.

Fase 2: Mapping de datos

Antes de programar, define el mapping. Por ejemplo:

Proveedor	Sistema comprador
SKU proveedor	SupplierPartID
SKU cliente	BuyerPartID
MXN	MXN
EA	PC
Categoría proveedor	Material Group
Fabricante	Manufacturer
Contrato	Contract

Esta fase parece trámite, y es de las que más riesgo le quitan al proyecto.

Fase 3: Construcción OCI

Desarrollar:

• endpoint Punch-Out;
• autenticación;
• creación de sesión;
• recepción de HOOK_URL;
• navegación de catálogo;
• construcción del carrito;
• generación de payload OCI;
• retorno del carrito.

Fase 4: Configuración cXML

Desarrollar:

• endpoint POST;
• autenticación;
• recepción de OrderRequest;
• validación XML;
• validación DTD;
• procesamiento;
• respuesta cXML;
• logging;
• manejo de errores;
• reintentos.

La documentación recomienda validar la estructura del documento cXML con el DTD correspondiente.

Fase 5: QA

Prueba escenarios reales:

Escenario	Qué debe ocurrir
Caso exitoso	Login → catálogo → producto → carrito → regreso → aprobación → PO → 200 OK
Producto inexistente	¿Qué sucede?
Precio incorrecto	¿Qué sucede?
Producto sin disponibilidad	¿Qué sucede?
Credenciales inválidas	El sistema devuelve un error controlado.
Endpoint caído	Se activa la política de reintentos definida.
XML inválido	El sistema lo rechaza con el error correcto.

Fase 6: Certificación

Antes de producción:

• probar casos positivos;
• probar casos negativos;
• validar mapping;
• validar seguridad;
• validar payload;
• validar respuesta;
• validar logs;
• validar reintentos;
• validar duplicidad;
• validar trazabilidad.

Fase 7: Producción

El orden de salida es:

QA → Certificación → Production URL → Monitoring → Soporte

Después viene una etapa que muchas empresas olvidan: operar la integración. Alguien tiene que monitorearla todos los días, porque los errores aparecen cuando cambian precios, catálogos o credenciales.

30. Checklist técnico de Punch-Out OCI

Conectividad

• URL QA
• URL Producción
• HTTP/HTTPS
• GET/POST
• firewall
• DNS
• certificados

Autenticación

• usuario
• password
• manejo de secretos
• expiración de credenciales

Sesión

• USERNAME
• PASSWORD
• HOOK_URL
• identificación del comprador

Catálogo

• SKU
• descripción
• precio
• moneda
• UOM
• categoría
• fabricante
• lead time

Carrito

• cantidad
• precio
• identificación del producto
• contrato
• información adicional
• retorno mediante HOOK_URL

31. Checklist técnico de cXML

Request

• OrderRequest
• orderID
• orderDate
• type
• orderType
• orderVersion
• Total
• BillTo
• LegalEntity
• PaymentTerm
• Contact
• ItemOut

Producto

• SupplierPartID
• BuyerPartID
• SupplierPartAuxiliaryID
• UnitPrice
• UnitOfMeasure
• SupplierID

Logística

• ShipTo
• DeliverTo
• fecha requerida
• planta
• ubicación

Comunicación

• POST
• HTTPS
• autenticación
• Content-Type
• UTF-8

Response

• HTTP 200
• cXML Response
• Status
• payloadID
• logging
• retry strategy

32. La recomendación más importante: no empieces por desarrollar

Es el punto que más enfatizo en mis proyectos de consultoría. Una empresa contrata a un desarrollador y le pide: “Necesitamos implementar Punch-Out”. Con esa instrucción, el desarrollador no tiene cómo resolver lo importante. Antes hay que responder:

• ¿Qué queremos integrar?
• ¿Qué sistema es dueño de cada dato?
• ¿Qué identificador utiliza cada sistema?
• ¿Qué productos participan?
• ¿Qué clientes participan?
• ¿Cómo funcionan los contratos?
• ¿Qué ocurre con los precios?
• ¿Cómo se manejan las excepciones?
• ¿Qué sucede cuando falla el endpoint?
• ¿Quién monitorea la integración?
• ¿Quién atiende una orden que no llegó?

Eso es arquitectura de integración, y va antes del código.

OCI y cXML cumplen funciones distintas

Esta tabla resume la diferencia:

	OCI	cXML
Principal aplicación	Punch-Out / catálogo	Documentos transaccionales
Catálogo	Sí	Puede participar según escenario
Carrito	Sí	No es el foco principal
PO	Puede formar parte del flujo	Sí
Formato	Parámetros OCI	XML
Comunicación	HTTP/HTTPS	HTTP/HTTPS
Método	GET/POST según implementación	POST en esta implementación
Identificación producto	Campos NEW_ITEM-*	SupplierPartID, BuyerPartID
Respuesta	Retorno del carrito	Response/Status
DTD	No aplica de la misma manera	Sí

Combinadas, cubren el flujo completo:

• OCI → experiencia Punch-Out
• cXML → intercambio transaccional

Conclusión

Implementar Punch-Out implica mucho más que conectar dos URLs. Construyes un puente entre eCommerce, procurement, ERP, compras, ventas, logística y finanzas.

OCI estructura la interacción entre el sistema comprador y el catálogo del proveedor. cXML estructura el intercambio de documentos y respuestas entre sistemas.

El resultado depende de la calidad de tu arquitectura de datos, del mapping, de las reglas de negocio y del manejo de excepciones. Un Punch-Out conectado con malos SKUs, unidades inconsistentes, categorías sin mapping o reglas comerciales ambiguas te deja otra integración que genera problemas.

🚀 ¿Estás evaluando implementar Punch-Out?

Si tu empresa vende B2B y algún cliente te pide integrarte con su plataforma de procurement, SAP, ERP o sistema de compras, no empieces por el código. Primero define:

Proceso → arquitectura → datos → protocolo → integración → pruebas → operación.

En esa etapa, una consultoría especializada le quita buena parte del riesgo al proyecto.

Puedo ayudarte a:

• evaluar si necesitas OCI, cXML o ambos;
• mapear tu arquitectura actual;
• definir los datos que deben intercambiarse;
• construir el mapping entre sistemas;
• definir requerimientos funcionales y técnicos;
• preparar la documentación para IT;
• estructurar el roadmap de implementación;
• acompañar las pruebas QA y certificación;
• identificar riesgos antes de llegar a producción.

Si estás por implementar Punch-Out o integrar tu eCommerce B2B con un sistema de procurement, contáctame y revisamos tu escenario. También puedes conocer más sobre mi servicio de eProcurement e integración B2B.

Antes de escribir código, entiende cómo debe fluir el negocio.