Contrato de API — Sync de productos compuestos (PC Manager → Integrador)

Para: equipo PC Manager (Python) Endpoint: POST /api/supplier-products/sync (Sanctum) — alias POST /api/supplier-products (token estático) Referencia de diseño: docs/rfc/004-soporte-productos-compuestos.md Fecha: 2026-07-14

1. Qué cambia

El payload de cada producto acepta dos campos nuevos, opcionales:

Campo	Tipo	Reglas
type	string	"simple" o "composite". Opcional; default "simple".
components	array	Requerido si type = "composite", mínimo 1 elemento. Cada elemento: {"sku": string, "quantity": int >= 1}.

El sku de cada componente es el sku de product_items del Integrador — el mismo que PC Manager lee de GET /api/products (campo sku). No usar sku_sap ni IDs.

Los productos simples no necesitan ningún cambio: el payload actual sigue siendo 100% válido.

2. Ejemplo — alta/actualización de un combo

{
    "supplier_id": 1,
    "supplier_code": "CL",
    "products": [
        {
            "sku": "pcm-00123",
            "name": "PC Gamer X",
            "short_description": "",
            "long_description": "",
            "regular_price": 5500000.0,
            "special_price": null,
            "special_from_date": null,
            "special_to_date": null,
            "stock": 5,
            "category": "PC ARMADAS",
            "brand": "Compulandia",
            "active": true,
            "images": [],
            "type": "composite",
            "components": [
                { "sku": "MEM-KING-16", "quantity": 2 },
                { "sku": "SSD-WD-1TB", "quantity": 1 }
            ]
        }
    ]
}

3. Semántica de actualización (importante)

La composición se trata con semántica PATCH: solo se toca si viene en el payload.

Payload recibido	Comportamiento en el Integrador
Sin type ni components	La receta guardada no se toca. Se actualizan solo los campos enviados (precio, stock, etc.). Un combo puede recibir updates de precio/stock sin re-enviar su receta.
type: "composite" + components	La receta recibida reemplaza completa a la anterior (snapshot, sin merge). Es la forma de crear el combo y también de comunicar una sustitución de componente: se envía la lista final vigente.
type: "composite" sin components	HTTP 422 — rechazado por validación. Si se declara compuesto, la receta debe venir completa.
components sin type	Se asume composite (la presencia de receta implica compuesto).
type: "simple" en un producto que era compuesto	La receta se elimina y la variante vuelve a simple. Es la forma de "des-armar" un combo.

Recomendación para PC Manager: enviar type + components completos en cada push del combo (alta, cambio de receta, sustitución), y omitir ambos campos en pushes que solo actualizan precio/stock. Nunca enviar components: [] ni components: null para "no cambiar" — simplemente omitir la clave.

4. Respuesta y warnings

La respuesta incluye, por producto, el resultado y los problemas de resolución de componentes:

{
    "status": "success",
    "message": "Productos procesados correctamente.",
    "processed": [
        {
            "sku": "pcm-00123",
            "status": "updated",
            "warnings": [
                "Componente 'SSD-NUEVO-XYZ': no existe como ProductItem"
            ]
        }
    ]
}

• warnings vacío = receta aceptada (y materializada, si el producto ya está confirmado en el Integrador).
• El push nunca falla por un componente no resoluble: el JSON crudo se guarda siempre. Pero atención a la semántica:
• Producto pendiente (aún no confirmado por un operador): los warnings son informativos; la receta se validará al confirmar.
• Producto confirmado: si algún componente no resuelve, la receta nueva NO se aplica — se conserva la anterior hasta recibir un push cuya receta resuelva completa. El warning es la señal para corregir y reenviar.

Motivos posibles de warning por componente: no existe como ProductItem, el ProductItem está inactivo, no tiene sku_sap (sin inventario en SAP).

5. Efectos aguas abajo (contexto)

Cuando la receta se materializa en un combo confirmado, el Integrador reindexa el documento del combo en Algolia (product_items_view_index) en el mismo request, agregando:

{ "product_type": "composite",
  "components": [
    { "product_item_id": 501, "sku": "MEM-KING-16", "sku_sap": "A00123", "name": "RAM 16GB DDR5", "quantity": 2 }
  ] }

Por eso importa que PC Manager pushee inmediatamente al sustituir un componente (comportamiento ya confirmado): la ventana en que el OMS puede ver una receta vieja depende solo de ese push.