Contrato de API — Recepción de productos (Integrador → PC Manager)

Para: equipo Integrador Endpoint: POST /api/products/receive Fecha: 2026-07-17 — última actualización: 2026-08-03 (endpoint auxiliar de categorías)

1. Propósito

Permite al Integrador empujar productos simples a PC Manager en el momento en que ocurren los eventos (alta desde SAP, venta, cambio de precio o nombre, activación/desactivación), en lugar de esperar el polling periódico de PC Manager. Semántica upsert: si el sku no existe y vienen los campos mínimos, el producto se crea; si existe, se actualiza (PATCH por campo).

Si el producto actualizado es componente de productos compuestos activos, PC Manager reevalúa cada combo afectado (selección de componentes, disponibilidad, stock real, precio) y, si algo cambió, sincroniza el combo de vuelta al Integrador por el canal habitual (POST /api/supplier-products/sync) — un único POST por combo.

2. Autenticación

Token estático compartido en el encabezado HTTP:

X-API-TOKEN: <token acordado>

Sin token o con token inválido → HTTP 403. El token se entrega por canal seguro y se configura en el .env de PC Manager (PCM_API_TOKEN).

3. Payload

Un mismo lote puede mezclar actualizaciones y altas. Ejemplo con ambos casos:

{
    "products": [
        {
            "sku": "CPI-259951",
            "stock": 3,
            "regular_price": 2560360.00,
            "special_price": null,
            "special_from_date": null,
            "special_to_date": null,
            "product_name": "Celular Apple iPhone 14 128GB - Starlight - Reacondicionado",
            "active": true
        },
        {
            "sku": "CPI-300100",
            "product_name": "Teclado Genius KB-100 USB Negro",
            "category_name": "Accesorios Pc",
            "stock": 12,
            "regular_price": 150000.00,
            "supplier_sku": "GEN-KB100",
            "supplier_name": "Compulandia",
            "supplier_id": 1,
            "brand": "Genius",
            "short_description": "Teclado USB de membrana, español latinoamericano",
            "long_description": "",
            "ean": "4710268045078",
            "active": true
        }
    ]
}

El primer ítem actualiza un producto existente (stock, precio y nombre); el segundo, al no existir el sku y venir los campos mínimos, crea el producto.

Campo	Tipo	Reglas
sku	string	Obligatorio siempre. Sku del producto (el mismo de product_items).
stock	int >= 0	Opcional en update. Requerido para alta.
product_name	string	Opcional en update (propaga renombres de SAP). Requerido para alta.
supplier_sku	string	Opcional (sin uso en la lógica interna de PC Manager).
supplier_name	string	Opcional en update. Requerido para alta.
category_name	string	Opcional en update (mueve de categoría). Requerido para alta. Debe existir en PC Manager y estar activa (ver §4).
regular_price	decimal	Opcional (default 0 en alta).
special_price	decimal o null	Opcional.
special_from_date / special_to_date	date (YYYY-MM-DD) o null	Opcionales.
active	bool	Opcional (default true en alta). false desactiva el producto en PC Manager: deja de ser asignable como componente y los combos que dependían de él se reevalúan (quedan no disponibles si no hay sustituto).
brand	string	Opcional.
short_description / long_description	string	Opcionales.
supplier_id	int	Opcional.
ean	string	Opcional.

Semántica PATCH por campo en updates: solo se aplican los campos presentes en el payload, y solo si difieren del valor actual (idempotente: reenviar el mismo payload no genera efectos ni sincronizaciones; un alta reenviada resulta unchanged).

4. Reglas de rechazo por ítem

El lote nunca falla completo; cada ítem se procesa de forma independiente:

• Sku inexistente sin los campos mínimos de alta → status: "error" con la lista de faltantes.
• Sku de un producto compuesto → status: "error". Los combos son de autoría exclusiva de PC Manager; aceptarlos crearía un ciclo de retroalimentación.
• category_name desconocida en PC Manager → status: "error" (sincronizar categorías primero).
• category_name inactiva en PC Manager → status: "error". PC Manager solo gestiona productos de sus categorías activas. (Configurable del lado PC Manager con PCM_RECEIVE_ALLOW_INACTIVE_CATEGORIES=True si en el futuro se decide aceptarlas.)
• Campos con formato inválido → status: "error" con el detalle de validación.

5. Respuesta

{
    "status": "success",
    "processed": [
        { "sku": "CPI-259951", "status": "updated", "fields": ["stock", "regular_price", "product_name"] },
        { "sku": "CPI-300100", "status": "created" },
        { "sku": "CPI-9999", "status": "unchanged" },
        { "sku": "CPI-0001", "status": "error", "errors": ["El sku no existe; para crearlo faltan campos requeridos: stock, supplier_name."] }
    ],
    "composites_reevaluated": ["PCM-12163"]
}

• created: producto nuevo dado de alta (tipo simple, disponible para usarse como componente de combos).
• updated: se aplicaron los campos listados en fields (con los mismos nombres del payload; un cambio de categoría se reporta como category_name).
• unchanged: el ítem no difería de lo almacenado; no dispara reevaluaciones.
• composites_reevaluated: skus de los combos activos afectados que fueron reevaluados en este request. Si alguno cambió (stock, precio, disponibilidad o receta), el Integrador recibirá el push correspondiente por supplier-products/sync — llega dentro del mismo ciclo, inmediatamente después de esta respuesta.

6. Efecto esperado en el Integrador (contexto)

Venta de un componente → push a este endpoint → PC Manager recalcula el stock real de los combos afectados → push del combo actualizado al Integrador. La ventana en la que el Integrador puede ver stock viejo de un combo se reduce al round-trip de estos dos requests.

7. Endpoint auxiliar — categorías que sincronizar

GET /api/categories?active=1 (misma autenticación: encabezado X-API-TOKEN).

Devuelve las categorías de PC Manager para que el Integrador sepa qué categorías empujar y evite enviar productos que serían rechazados por categoría inactiva (§4), ahorrando peticiones y verificación.

• ?active=1 → solo las categorías activas en PC Manager (el caso de uso normal: empujar únicamente productos de estas categorías).
• Sin parámetro → todas las categorías, con su estado (?active=0 devuelve solo las inactivas).

{
    "count": 37,
    "categories": [
        { "external_id": 1, "name": "Accesorios Pc", "is_active": true },
        { "external_id": 2, "name": "Accesorios p/ Notebook", "is_active": true }
    ]
}

• external_id es el id de la categoría en el Integrador (PC Manager lo guarda de la sincronización de categorías), por lo que el Integrador puede mapear directamente contra su propio catálogo sin comparar por nombre.
• name es el valor exacto que PC Manager espera en category_name de este contrato.
• Recomendación: consultar este endpoint al inicio de cada ciclo de sincronización (o cachearlo con TTL corto); el conjunto de categorías activas cambia con poca frecuencia.