Especificaciones de integración PunchOut para tiendas a medida

1. Configuración en PunchOut Rocket

Sitio de comercio electrónico

Las rutas de los endpoints se añaden a Site URL tal cual, por lo que deben empezar por /. Ejemplo: Site URL https://your-store.example.com + /api/punchout/clone → https://your-store.example.com/api/punchout/clone.

Los pedidos de compra (sección 6) y carritos predefinidos se incluyen en el plan Premium, incluido en la prueba gratuita: su plan los habilita en el sitio y la página del cliente final muestra las secciones Orders y Predefined Carts. Las confirmaciones de pedido y avisos de envío (secciones 7–8) requieren también la opción OC & ASN.

Cliente final

Cada empresa cliente es un cliente final de su sitio. Además de sus credenciales de protocolo (identidades cXML y shared secret, o usuario y contraseña OCI), estos campos afectan a su tienda:

El resto de las páginas del sitio y del cliente final funciona como en las demás plataformas: consulte la documentación.

2. Endpoint de clonación

Ruta predeterminada: /api/punchout/clone. Se llama cuando un cliente abre su tienda desde el sistema de compras. Su tienda crea (o reutiliza) un usuario clonado de username, vinculado a esta sesión PunchOut, y devuelve una URL SSO que inicia su sesión (sección 3).

Cuerpo de la solicitud

quantity y price son cadenas: conviértalas antes de utilizarlas.

Solicitud: creación con un artículo seleccionado

{
  "username": "buyer123",
  "api_key": "site-api-key-abc",
  "session_token": "sess-012345",
  "operation": "create",
  "end_customer_id": 2,
  "gateway_base_url": "https://middleware.example.com",
  "selected_item": {
    "supplier_part_id": "X-100",
    "supplier_part_auxiliary_id": "19853"
  }
}

Solicitud: edit, con el carrito que debe restaurarse

{
  "username": "buyer123",
  "api_key": "site-api-key-abc",
  "session_token": "sess-67890",
  "operation": "edit",
  "end_customer_id": 2,
  "gateway_base_url": "https://middleware.example.com",
  "cart_items": [
    {"sku": "ABC-001", "product_id": "19852", "quantity": "2", "price": "15.95",
     "description": "Example description", "currency": "EUR"},
    {"sku": "XYZ-002", "product_id": "19854", "quantity": "1", "price": "249.00",
     "description": "Another example description", "currency": "EUR"}
  ]
}

Respuesta de éxito

HTTP 2xx

HTTP 200
{
  "status": "success",
  "sso_url": "https://your-store.example.com/punchout/sso?token=eyJ..."
}

sso_url es el único campo leído: es obligatorio y debe ser una URL absoluta http:// o https://. PunchOut Rocket dirige allí el navegador del cliente (a través del sistema de compras para cXML, directamente para OCI).

Respuestas de error

Cualquier estado no 2xx o respuesta sin un sso_url válido hace fallar el PunchOut: el cliente recibe un error en su sistema de compras. Su respuesta (estado y cuerpo) se guarda en el registro de la sesión PunchOut, así que explique el motivo en el mensaje.

4. Transferencia del carrito (formulario de envío automático)

Para un usuario PunchOut, el botón de finalizar compra no debe iniciar su proceso de pago: envía el carrito a PunchOut Rocket. Su tienda devuelve una página HTML que envía automáticamente un formulario oculto, preferiblemente con un indicador de carga.

• URL: {gateway_base_url}/start-sso-checkout (gateway_base_url de la solicitud de clonación)
• Método: POST, application/x-www-form-urlencoded (envío normal de un formulario del navegador)
• Sin api_key: la sesión se identifica mediante session_token y end_customer_id.

i empieza en 0 y no tiene huecos: PunchOut Rocket deja de leer en el primer índice ausente. Recuerde escapar los valores para HTML.

Ejemplo de página devuelta al acceder al proceso de pago

<!doctype html>
<html>
<body>
<p>Sending your cart to your procurement system…</p>
<form id="punchout_repost" method="post" action="https://middleware.example.com/start-sso-checkout">
  <input type="hidden" name="session_token" value="sess-012345"/>
  <input type="hidden" name="end_customer_id" value="2"/>
  <input type="hidden" name="products[0][sku]" value="ABC-001"/>
  <input type="hidden" name="products[0][product_id]" value="19852"/>
  <input type="hidden" name="products[0][description]" value="Example description"/>
  <input type="hidden" name="products[0][quantity]" value="2"/>
  <input type="hidden" name="products[0][price]" value="15.95"/>
  <input type="hidden" name="products[0][currency]" value="EUR"/>
  <input type="hidden" name="products[0][unit_of_measure]" value="EA"/>
  <input type="hidden" name="products[0][manufacturer_name]" value="3M"/>
  <input type="hidden" name="products[0][category_ids]" value="1145,3398"/>
  <input type="hidden" name="products[1][sku]" value="XYZ-002"/>
  <input type="hidden" name="products[1][product_id]" value="19854"/>
  <input type="hidden" name="products[1][description]" value="Another example description"/>
  <input type="hidden" name="products[1][quantity]" value="4"/>
  <input type="hidden" name="products[1][price]" value="10.90"/>
  <input type="hidden" name="products[1][currency]" value="EUR"/>
  <input type="hidden" name="products[1][manufacturer_name]" value="DEWALT"/>
  <input type="hidden" name="products[1][category_ids]" value="2146"/>
</form>
<script>document.getElementById('punchout_repost').submit();</script>
</body>
</html>

PunchOut Rocket envía entonces el carrito al sistema de compras y finaliza la sesión. Cada sesión acepta un solo carrito:

7. Endpoint de estado de pedidos

Ruta predeterminada: /api/punchout/order-status. Se llama solo para clientes finales con «Send order status updates» activado, para pedidos creados mediante la sección 6: cada hora durante 60 días desde el pedido e inmediatamente tras una notificación (sección 8). Requiere la opción OC & ASN. A partir de la respuesta, PunchOut Rocket envía al sistema de compras del cliente:

• una confirmación de pedido (cXML ConfirmationRequest), una sola vez, cuando se acepta o cancela el pedido;
• un aviso de envío (cXML ShipNoticeRequest) por cada nuevo envío de un pedido confirmado.

PunchOut Rocket recuerda lo que envió: responda siempre con el estado actual del pedido y PunchOut Rocket determina qué ha cambiado.

Solicitud: order_id es el devuelto por su endpoint de creación de pedidos

{"api_key": "site-api-key-abc", "order_id": "100045"}

Respuesta de éxito

HTTP 200

HTTP 200
{
  "status": "success",
  "order_status": "shipped",
  "items": ["5501", "5502"],
  "quantities": [
    {"order_item_id": "5501", "quantity": 2},
    {"order_item_id": "5502", "quantity": 1}
  ],
  "shipments": [
    {
      "id": "SH-1",
      "shipped_at": "2026-11-12T09:30:00+01:00",
      "carrier": "UPS",
      "tracking": "1Z999AA10123456784",
      "items": [{"order_item_id": "5501", "quantity": 2}]
    }
  ]
}

La confirmación se envía una vez, la primera vez que el pedido está en processing, shipped o delivered:

• acepta el pedido completo cuando todas las líneas del PO están presentes en su totalidad;
• en caso contrario, acepta cada línea por la cantidad que contiene el pedido y rechaza el resto (artículos eliminados, cantidades reducidas). Una cantidad superior al PO se confirma por la cantidad del PO;
• si no queda ninguna línea, no se envía nada: utilice cancelled para rechazar el pedido.

Los cambios posteriores en artículos no se confirman de nuevo: modifique el pedido antes de aceptarlo.

Comunique un envío solo cuando haya salido. Los cambios realizados tras notificarlo no se envían de nuevo. Si el sistema de compras rechaza una confirmación o aviso de envío, PunchOut Rocket lo reenvía en la siguiente comprobación y no envía nada posterior hasta que sea aceptado.

9. Comprobaciones antes de la puesta en marcha

1. Configure el sitio (sección 1) e introduzca la misma clave API en su tienda.
2. Cree un cliente final y establezca su «E-commerce User to Clone».
3. Haga clic en «Update from e-commerce» en su Category Mapping y asigne las categorías; establezca un Default UNSPSC.
4. Pruebe un PunchOut con el formulario de prueba cXML del panel de administración: create, después edit con un carrito y luego devuelva el carrito.
5. Para pedidos de compra (plan Premium): envíe un OrderRequest de prueba y compruebe el pedido en su tienda.
6. Para actualizaciones de estado (opción OC & ASN): active «Send order status updates» en el cliente final, pase el pedido de prueba por sus estados y compruebe que el sistema del cliente recibe la confirmación y los avisos de envío.

Recuerde:

• Los usuarios PunchOut no deben completar una compra en su tienda: su carrito vuelve al sistema de compras (sección 4) y el pedido llega después mediante la sección 6.
• Los pedidos recibidos mediante la sección 6 ya están aprobados por el sistema de compras del cliente: no necesitan pago online.

¿Necesita un cliente de prueba o una revisión de su implementación? Hable con nuestros desarrolladores o encargue el desarrollo con Go-Live Assist.