Documentación de PunchOut Rocket

Especificación de integración de comercio electrónico personalizada

Este documento describe lo que debe proporcionar la implementación de comercio electrónico personalizada para que pueda configurarse en los campos de administración:

“Endpoint de clonación personalizado”
“Endpoint de categorías personalizado”

Además, describe:

Comportamiento de inicio de sesión automático / SSO
Formulario de autoenvío (reenvío del carrito al middleware)

Incluye los verbos HTTP obligatorios, los parámetros, el significado de los parámetros y los posibles valores, las respuestas esperadas (éxito y error) y ejemplos concretos.

1) Endpoint de clonación personalizado (propósito)
Utilizado por el middleware para:

Crear un nuevo pedido/sesión en la tienda remota (flujo “create”), o
Editar/rellenar un pedido/carrito existente (flujo EDIT). El endpoint debe devolver uno de los siguientes:
Una URL de SSO que inicie sesión al comprador con un token de un solo uso en el sitio remoto, donde el usuario puede ser redirigido al carrito si es un flujo EDIT y el carrito está rellenado, puede ser redirigido al producto seleccionado (en caso de que se comunique durante el flujo “create”); de lo contrario, se le redirige a la página de inicio.

Ruta de URL recomendada (ejemplo):

POST https://your-store.example.com/api/punchout/clone

Verbo HTTP

POST (obligatorio). Use cuerpo JSON (application/json). El middleware llamará a POST.

Cuerpo de la solicitud (JSON)
Campos base (siempre presentes)

- username (string) — nombre de usuario en el comercio electrónico del usuario que se va a clonar para generar un nuevo usuario vinculado a la sesión de punchout.
- api_key (string) — clave de API que debe coincidir con la configurada en Punchout Rocket para el comercio electrónico actual
- end_customer_id (integer) – identificador del cliente final en el middleware de Punchout Rocket para el comercio electrónico de la solicitud punchout actual
- session_token (string) — Buyer Cookie único en caso de CXML o UUID único o similar en caso de OCI
- operation (string) — “create” o “edit” o “inspect” en caso de CXML, “create” en caso de OCI. En caso de “edit” o “inspect” puede pasarse una lista de artículos del carrito
- gateway_base_url (string) — URL del middleware al que posteriormente debe enviarse el carrito

Adiciones específicas del protocolo

Si el protocolo resuelto es CXML, pueden añadirse estos campos adicionales:

selected_item (object) — identificación del producto al que se debe redirigir al usuario; opcional en caso de operación “create”:

supplier_part_id (string) — identificador del SKU (código de producto) en el comercio electrónico (si existe)
supplier_part_auxiliary_id (string) — identificador del ID de producto en el comercio electrónico (si existe)

Ejemplo: json

{  
  "selected_item":  
  {  
  "supplier_part_id": "ABC-001",  
  "supplier_part_auxiliary_id": "19852"  
  }  
}

cart_items (array) — la lista de artículos del carrito que deben volver a añadirse al carrito de la sesión actual. Cada elemento de cart_items suele contener:

sku (string) — identificador del SKU (código de producto) en el comercio electrónico (si existe)
product_id (string) — identificador del ID de producto en el comercio electrónico (si existe)
quantity (integer) – cantidad del artículo en el carrito
price (número decimal con punto como separador decimal) – precio unitario del artículo en el carrito. Tenga en cuenta que se actualizará al precio actual cuando el usuario sea redirigido al carrito
description (string) – descripción del producto
currency (string) — código de divisa ISO 4217

Ejemplo de payload (create, CXML, con 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"
  }
}

Ejemplo de payload (edit, CXML, carrito rellenado)

{
  "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" : "Descripción de ejemplo",
  "currency": "EUR"
  },
  {
  "sku": "XYZ-002",
  "product_id": "19854",
  "quantity": 1,
  "price": 249.00,
  "description" : "Otra descripción de ejemplo",
  "currency": "EUR"
  }
  ]
}

Respuesta(s) de éxito
Opción A — Proporcionar una URL de SSO directa (JSON) – HTTP 200 – Content-Type: application/json – Body:

{
  "status":"ok",
  "sso_url":"https://your-store.example.com/sso?token=eyJ…"
}

Comportamiento: El middleware redirigirá al comprador a sso_url (GET) y la devolverá a la plataforma de compras en caso de CXML o directamente en caso de OCI. La tienda remota debe consumir el token, iniciar sesión al usuario y, a continuación:

Si la acción es “edit” o “inspect”: el sitio remoto debe leer la información del carrito y rellenarlo para que el usuario llegue a la tienda en la página del carrito con los artículos ya en el carrito y con las cantidades correspondientes.

Si la acción es “create”: el sitio remoto debe redirigir al artículo seleccionado si se ha pasado y se ha encontrado; de lo contrario, el usuario debe aterrizar en el escaparate

Respuestas de error
HTTP 400 — Solicitud incorrecta (faltan campos obligatorios) json

{  
  "status":"error",  
  "error_code":"invalid_request",  
  "message":"Falta el campo: action"  
}

HTTP 422 — No se puede crear el SSO (p. ej., falta la identidad del comprador) json

{  
  "status":"error",  
  "error_code":"sso_unavailable",  
  "message":"No se puede generar el token de SSO para este usuario"  
}

HTTP 500 — Error interno json

{  
  "status":"error",  
  "error_code":"internal_error"  
}

2) Comportamiento de inicio de sesión automático / SSO (cómo iniciar sesión al comprador y rellenar el carrito)
Al responder con sso_url, la tienda debe:

Consumir el token (para que no pueda usarse dos veces) e iniciar sesión al comprador con el usuario clonado.
Después del inicio de sesión:
- Si la acción es “edit”:
  - Rellenar el carrito del usuario con los productos y cantidades exactos proporcionados como artículos del carrito.
  - Redirigir al usuario a la página de carrito/checkout, donde podrá editar antes de finalizar la compra.
- Si la acción es “create”:
  - Opcionalmente, redirigir al producto especificado como artículo seleccionado. Si el middleware no proporcionó ningún artículo seleccionado o si ya no se encuentra en el comercio electrónico, hacer que el usuario aterrice en la página de inicio de la tienda.

Seguridad:

Utilice solo HTTPS.

Los tokens deben ser de un solo uso.

3) Formulario de autoenvío (reenvío del carrito al middleware)
Cuando la tienda deba enviar el carrito/confirmación del carrito de vuelta al middleware (después del inicio de sesión por SSO al añadir productos al carrito o al editarlo), cuando el usuario haga clic en el botón (normalmente en el carrito) que debería iniciar el checkout del carrito y, en su lugar, en el caso de usuarios clonados de sesiones punchout, debe hacer POST de un formulario (content-type: application/x-www-form-urlencoded) a la URL del middleware comunicada en la solicitud al endpoint de clonación, en la ruta relativa «/start-sso-checkout». La UX preferida: la tienda sirve una página HTML que muestra un cargador y que envía automáticamente un formulario oculto al endpoint del middleware (esto hace que el SSO sea fluido).

Campos del formulario esperados por el middleware:

session_token (string) — token de sesión recibido por el comercio electrónico durante la solicitud de clonación
end_customer_id (integer) — identificación del cliente final recibida por el comercio electrónico durante la solicitud de clonación
Para cada artículo del carrito, debemos tener datos de formulario con índice base cero, por ejemplo con la clave products[0][product_id] para el ID de producto del primer artículo del carrito. Para cada artículo del carrito, la lista de campos es
- sku (string) — identificador del SKU (código de producto) en el comercio electrónico (si existe)
- product_id (string) — identificador del ID de producto en el comercio electrónico (si existe)
- description (string) — descripción del producto
- quantity (integer) — cantidad del producto en el carrito
- price (número decimal con punto como separador decimal) — precio unitario
- currency (string) — código de divisa ISO 4217
- manufacturer_name (string) – fabricante del producto
- category_ids (string) — lista, separada por comas, de los ID enteros de categoría en el comercio electrónico de las categorías a las que pertenece directamente el producto (normalmente hoja en la estructura de árbol de categorías)

Ejemplo de formulario HTML de autoenvío (la tienda devuelve al navegador del usuario y lo envía automáticamente de vuelta al middleware):

Comportamiento:

El navegador envía automáticamente un POST a middleware_callback.

El middleware recibe el carrito y continúa su flujo de trabajo añadiendo códigos de categoría (p. ej., UNSPSC) calculados al hacer coincidir las categorías del comercio electrónico con códigos de categoría remapeados.

4) Endpoint de categorías personalizado (propósito)
Utilizado por el middleware/admin para obtener categorías de la tienda remota y permitir el mapeo con códigos de categoría estándar (p. ej., UNSPSC).

Ruta de URL recomendada (ejemplo):

POST https://your-store.example.com/api/punchout/categories

Verbo HTTP

POST (obligatorio). Se permiten parámetros de consulta opcionales (véase más abajo).

Parámetros de consulta

api_key (string) — clave de API que debe coincidir con la configurada en Punchout Rocket para el comercio electrónico actual

Respuesta de éxito
HTTP 200
Content-Type: application/json
Body:

{
  "status":"ok",
  "categories":[
  {"id":1345,"name":"Material de oficina","parent_id":0},
  {"id":1847,"name":"Bolígrafos","parent_id":1345},
     {"id":2345,"name":"Electrónica","parent_id":0}
  ]
}

Semántica:

id (integer) — identificador único (normalmente el ID entero de la categoría en la tabla de categorías del comercio electrónico) de la categoría, que posteriormente el middleware utilizará al enviar el carrito al sistema de compras con categorías remapeadas (p. ej., código UNSPSC).

name (string) — nombre para mostrar

parent_id (integer) — identificador único (normalmente el ID entero de la categoría en la tabla de categorías del comercio electrónico) de la categoría padre de la categoría actual. Normalmente “0” si no tiene una categoría padre

Respuestas de error:

HTTP 400 — consulta no válida

HTTP 500 — error interno

Ejemplo de solicitud: GET /api/punchout/categories?api_key=site-api-key-abc

Ejemplo de respuesta:

{
  "status":"ok",
  "categories":[
  {"id":1345,"name":"Material de oficina","parent_id":0},
  {"id":1847,"name":"Bolígrafos","parent_id":1345},
     {"id":2345,"name":"Electrónica","parent_id":0}
  ]
}

5) Notas y recomendaciones de implementación

Utilice siempre HTTPS.

Utilice tokens de SSO de un solo uso.

Al enviar líneas del carrito, mantenga el orden de los índices (sku[], product_id[], quantity[], unit_price[], extended_price[], categories[]). El middleware emparejará los artículos por índice.

Especificación de integración de comercio electrónico personalizada

Contacto

Empresa