Saltar a contenido

PDF-009B-1 - WooCommerce Product API Extension Design

Fecha: 2026-06-22

Estado: CANDIDATE DOCUMENTAL / SIN API / SIN CREDENCIALES / SIN RUNTIME / PRE-PDF-009B

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Destino funcional: La Directa WooCommerce

Owner: Gabi / Carlos Canu

1. Objetivo

Definir, antes de PDF-009B read-only, si los datos de SOURCE-002 Productos alcanzan con el endpoint estandar de productos de WooCommerce o si se requiere una extension adicional via meta_data, register_meta, register_rest_field, plugin propio o endpoint custom.

2. Base documental usada

Documentos leidos para este diseno:

  • docs/governance/PROJECT-CONSTITUTION.md
  • CODEX.md
  • docs/governance/ACTIVE-CONTEXT.md
  • docs/PROJECT-STATE.md
  • docs/ROADMAP.md
  • docs/tenants/alpuntodeventa/business-observer/blueprints/PRODUCT-BLUEPRINT.md
  • docs/tenants/alpuntodeventa/business-observer/BUSINESS-OBSERVER-DATA-CONTRACT-001.md
  • docs/tenants/alpuntodeventa/business-observer/source-authority/SOURCE-002-PRODUCTOS-PRODUCTS-AUTHORITY.sql
  • docs/tenants/alpuntodeventa/business-observer/SOURCE-002-FUTURE-LAYER-MAPPING.md
  • docs/tenants/alpuntodeventa/business-observer/production/PDF-009A-WOOCOMMERCE-PRODUCTS-MAPPING-API-CANDIDATE.md
  • infra/business-observer/production/woocommerce/products/PDF-009A/

3. Conclusiones ejecutivas

3.1 Decision principal

La recomendacion es:

  • usar WooCommerce estandar para el catalogo publico minimo;
  • usar meta_data solo para extensiones privadas puntuales y no sensibles que ayuden a trazabilidad o a reglas futuras;
  • mantener en PostgreSQL los datos economicos, de proveedor, costo, descuentos, listas multiples y trazabilidad sensible;
  • no crear por ahora plugin, register_rest_field ni endpoint custom;
  • reabrir extension WordPress solo si un gate futuro demuestra una necesidad concreta no cubierta por el endpoint estandar.

3.2 Que alcanza con WooCommerce estandar

El endpoint estandar /wp-json/wc/v3/products alcanza para:

  • sku
  • name
  • description
  • short_description
  • regular_price
  • sale_price
  • manage_stock
  • stock_quantity
  • stock_status
  • weight
  • status
  • catalog_visibility
  • categories
  • attributes

Eso cubre el catalogo comercial base sin tocar la API ni agregar runtime.

3.3 Que no conviene poner en Woo publico

No deben exponerse en endpoints publicos de producto:

  • costo y costo lista proveedor;
  • proveedor, codigo proveedor y senales de compras;
  • margenes;
  • descuentos de compra;
  • descuento permitido;
  • precio con descuento permitido;
  • listas L2..L9 y sus netos/ivas/margenes;
  • hashes tecnicos y batches;
  • dias sin comprar, dias sin vender y dias sin actualizar costo;
  • reglas internas no aprobadas de publish/draft.

3.4 Necesidad de extension custom

No hay necesidad concreta actual de:

  • endpoint custom;
  • plugin propio;
  • register_rest_field;
  • register_meta.

Eso solo seria justificable si en una fase posterior se necesita:

  • exponer en REST campos calculados no almacenados;
  • aplicar reglas B2B de carrito como minimo por pack o multiplo de venta;
  • leer o editar metadata protegida desde clientes autenticados con contrato estable;
  • separar una API privada de integracion distinta del catalogo Woo estandar.

4. Inventario fuente considerado

La autoridad vigente de SOURCE-002 devuelve 81 campos reales y los deja anclados a tenant_id + SKU.

Este diseno tambien evalua campos futuros ya presentes en el candidate PostgreSQL/WooCommerce:

  • units_per_pack
  • min_units
  • sale_pack_quantity
  • woo_category_candidate
  • woo_status_candidate
  • wc_product_id futuro

Y deja explicitamente identificado un gap:

  • original_price no aparece como campo autoridad vigente ni como columna nombrada en la documentacion leida; queda UNKNOWN hasta definir si negocio lo entiende como regular_price, precio pre-oferta, o precio base de una lista particular.

5. Estrategia recomendada por dominio

Dominio Estrategia recomendada
Identidad comercial Woo nativo (sku, name)
Descripcion comercial Woo nativo (description, short_description) con regla editorial pendiente
Precio publico Woo nativo, una sola verdad publica (regular_price y opcional sale_price)
Stock vendible Woo nativo (manage_stock, stock_quantity, stock_status)
Categoria / subcategoria taxonomia nativa product_cat cuando exista mapping aprobado
Marca atributo Woo visible; solo pasar a taxonomia si realmente agrega filtros/navegacion
Peso Woo nativo (weight)
Volumen, pack, pallet, PLU meta_data privada o PostgreSQL segun necesidad
Costos, proveedor, descuentos, margenes, listas multiples PostgreSQL only
Trazabilidad tecnica sync meta_data privada minima o tabla/control en PostgreSQL
wc_product_id futuro control de sync en PostgreSQL; no como extension publica

6. Matriz de destino WooCommerce / API

6.1 Identidad, clasificacion y senales comerciales

Campo SGC Significado de negocio Destino recomendado Mecanismo Visible cliente Sensible/interno Necesario sync Necesario frontend Decision
SKU identificador canonico del producto sku Woo native field YES NO YES YES READY
Articulo nombre comercial legible name y base de descripcion Woo native field YES NO YES YES READY
Marca atributo comercial de marca atributo visible Marca; taxonomia solo si aporta filtros attribute YES NO YES YES PENDING_RULE
Estado estado fuente observado; la autoridad ya filtra ACTIVO conservar raw en PostgreSQL; no traducir automaticamente a publish PostgreSQL only NO NO YES NO PENDING_RULE
Acepta Devolucion politica comercial de devolucion conservar interna; exponer solo si negocio la quiere visible al cliente meta_data NO YES NO NO PENDING_RULE
Estrategico clasificacion comercial interna conservar interna PostgreSQL only NO YES NO NO READY
PLU Articulo identificador auxiliar de unidad metadata privada opcional meta_data NO NO NO NO READY
[PLU Bulto] identificador auxiliar de bulto metadata privada opcional meta_data NO NO NO NO READY
Cod Proveedor codigo de proveedor asociado al SKU mantener interno PostgreSQL only NO YES NO NO READY
Proveedor nombre legible del proveedor mantener interno PostgreSQL only NO YES NO NO READY
Category categoria comercial raw mapear a product_cat solo con mapping aprobado taxonomy YES NO YES YES PENDING_RULE
SubCategoria subcategoria comercial raw mapear a product_cat o atributo complementario segun taxonomia final taxonomy YES NO YES YES PENDING_RULE

6.2 Stock e inventario

Campo SGC Significado de negocio Destino recomendado Mecanismo Visible cliente Sensible/interno Necesario sync Necesario frontend Decision
Stock stock actual en unidades stock_quantity y derivado stock_status Woo native field YES NO YES YES READY
Stock en Bultos stock expresado en bultos no publicar como stock oficial; guardar solo si aporta operacion meta_data NO NO NO NO READY

6.3 Costos, precios base, impuestos y promociones

Campo SGC Significado de negocio Destino recomendado Mecanismo Visible cliente Sensible/interno Necesario sync Necesario frontend Decision
CostoListaProveedor lista proveedor antes de descuentos mantener interno PostgreSQL only NO YES NO NO READY
Dcto Compra 1 primer descuento de compra mantener interno PostgreSQL only NO YES NO NO READY
Dcto Compra 2 segundo descuento de compra mantener interno PostgreSQL only NO YES NO NO READY
Dcto Compra 3 tercer descuento de compra mantener interno PostgreSQL only NO YES NO NO READY
Costo costo neto final del producto mantener interno PostgreSQL only NO YES NO NO READY
Markup markup general vigente mantener interno PostgreSQL only NO YES NO NO READY
PrecioListaNeto precio base neto sin IVA mantener interno; no es el precio publico final PostgreSQL only NO YES NO NO READY
AlicuotaIVA alicuota impositiva mantener interna; Woo trabaja con tax classes, no con este dato bruto de producto en el payload candidato PostgreSQL only NO YES NO NO READY
IVAPListaFinal componente IVA del precio lista final mantener interno PostgreSQL only NO YES NO NO READY
PrecioListaFinal mejor candidato actual a precio publico base regular_price Woo native field YES NO YES YES READY
Descuento Permitido regla interna de descuento maximo no exponer PostgreSQL only NO YES NO NO READY
PrecioCDescPermitidoFinal precio derivado de regla interna de descuento permitido no exponer como precio publico PostgreSQL only NO YES NO NO READY
PrecioOfertaFinal precio promocional vigente sale_price solo si regla de vigencia y prioridad queda aprobada Woo native field YES NO YES YES PENDING_RULE

6.4 Bloque repetible de listas L1..L9

Campo SGC Significado de negocio Destino recomendado Mecanismo Visible cliente Sensible/interno Necesario sync Necesario frontend Decision
MargenL1 margen de lista L1 mantener interno PostgreSQL only NO YES NO NO READY
PrecioL1 precio final de lista L1 no publicar directo hasta cerrar si L1 es la lista ecommerce; por ahora interno PostgreSQL only NO YES NO NO PENDING_RULE
IVAPrecioL1 componente IVA de L1 mantener interno PostgreSQL only NO YES NO NO READY
PrecioNetoL1 precio neto sin IVA de L1 mantener interno PostgreSQL only NO YES NO NO READY
MargenL2 margen de lista L2 mantener interno PostgreSQL only NO YES NO NO READY
PrecioL2 precio final de lista L2 mantener interno PostgreSQL only NO YES NO NO READY
IVAPrecioL2 componente IVA de L2 mantener interno PostgreSQL only NO YES NO NO READY
PrecioNetoL2 precio neto sin IVA de L2 mantener interno PostgreSQL only NO YES NO NO READY
MargenL3 margen de lista L3 mantener interno PostgreSQL only NO YES NO NO READY
PrecioL3 precio final de lista L3 mantener interno PostgreSQL only NO YES NO NO READY
IVAPrecioL3 componente IVA de L3 mantener interno PostgreSQL only NO YES NO NO READY
PrecioNetoL3 precio neto sin IVA de L3 mantener interno PostgreSQL only NO YES NO NO READY
MargenL4 margen de lista L4 mantener interno PostgreSQL only NO YES NO NO READY
PrecioL4 precio final de lista L4 mantener interno PostgreSQL only NO YES NO NO READY
IVAPrecioL4 componente IVA de L4 mantener interno PostgreSQL only NO YES NO NO READY
PrecioNetoL4 precio neto sin IVA de L4 mantener interno PostgreSQL only NO YES NO NO READY
MargenL5 margen de lista L5 mantener interno PostgreSQL only NO YES NO NO READY
PrecioL5 precio final de lista L5 mantener interno PostgreSQL only NO YES NO NO READY
IVAPrecioL5 componente IVA de L5 mantener interno PostgreSQL only NO YES NO NO READY
PrecioNetoL5 precio neto sin IVA de L5 mantener interno PostgreSQL only NO YES NO NO READY
MargenL6 margen de lista L6 mantener interno PostgreSQL only NO YES NO NO READY
PrecioL6 precio final de lista L6 mantener interno PostgreSQL only NO YES NO NO READY
IVAPrecioL6 componente IVA de L6 mantener interno PostgreSQL only NO YES NO NO READY
PrecioNetoL6 precio neto sin IVA de L6 mantener interno PostgreSQL only NO YES NO NO READY
MargenL7 margen de lista L7 mantener interno PostgreSQL only NO YES NO NO READY
PrecioL7 precio final de lista L7 mantener interno PostgreSQL only NO YES NO NO READY
IVAPrecioL7 componente IVA de L7 mantener interno PostgreSQL only NO YES NO NO READY
PrecioNetoL7 precio neto sin IVA de L7 mantener interno PostgreSQL only NO YES NO NO READY
MargenL8 margen de lista L8 mantener interno PostgreSQL only NO YES NO NO READY
PrecioL8 precio final de lista L8 mantener interno PostgreSQL only NO YES NO NO READY
IVAPrecioL8 componente IVA de L8 mantener interno PostgreSQL only NO YES NO NO READY
PrecioNetoL8 precio neto sin IVA de L8 mantener interno PostgreSQL only NO YES NO NO READY
MargenL9 margen de lista L9 mantener interno PostgreSQL only NO YES NO NO READY
PrecioL9 precio final de lista L9 mantener interno PostgreSQL only NO YES NO NO READY
IVAPrecioL9 componente IVA de L9 mantener interno PostgreSQL only NO YES NO NO READY
PrecioNetoL9 precio neto sin IVA de L9 mantener interno PostgreSQL only NO YES NO NO READY

6.5 Fechas operativas e historicos utiles

Campo SGC Significado de negocio Destino recomendado Mecanismo Visible cliente Sensible/interno Necesario sync Necesario frontend Decision
Fecha de Ultima Compra recencia de compra mantener interna PostgreSQL only NO YES NO NO READY
UltVenta recencia de ultima venta mantener interna PostgreSQL only NO YES NO NO READY
UltCambioCosto fecha de ultimo cambio de costo mantener interna PostgreSQL only NO YES NO NO READY
DiasSinComprar dias desde la ultima compra mantener interna PostgreSQL only NO YES NO NO READY
DiasSinVender dias desde la ultima venta mantener interna PostgreSQL only NO YES NO NO READY
DiasSinActCosto dias desde la ultima actualizacion de costo mantener interna PostgreSQL only NO YES NO NO READY

6.6 Politica comercial, pack, peso, volumen y palletizado

Campo SGC Significado de negocio Destino recomendado Mecanismo Visible cliente Sensible/interno Necesario sync Necesario frontend Decision
CantVtaMin unidades minimas de venta meta_data.min_sale_quantity; regla de carrito solo en gate futuro si negocio la exige meta_data NO NO YES NO READY
CantVentaAgrupada cantidad agrupada o pack comercial de venta meta_data.sale_pack_quantity meta_data NO NO YES NO READY
UnidadMedida unidad de medida atributo visible solo si aporta lectura comercial; sino interna attribute NO NO NO NO PENDING_RULE
PesoxUnidad peso unitario weight Woo native field YES NO YES YES READY
VolumenxUnidad volumen unitario metadata privada; Woo no acepta volumen como campo nativo simple meta_data NO NO NO NO READY
BasePallet base operativa de pallet metadata privada meta_data NO NO NO NO READY
AlturaPallet altura operativa de pallet metadata privada meta_data NO NO NO NO READY
Unidades_x_Bulto unidades por bulto / pack meta_data.units_per_pack meta_data NO NO YES NO READY
CantUnidxPallet unidades por pallet metadata privada meta_data NO NO NO NO READY
CantBultosxPallet bultos por pallet metadata privada meta_data NO NO NO NO READY
PesoxPalletkg peso total de pallet metadata privada meta_data NO NO NO NO READY
VolumenxPalletm3 volumen total de pallet metadata privada meta_data NO NO NO NO READY

6.7 Campos derivados / futuros ya visibles en el candidate PostgreSQL

Campo candidato Significado de negocio Destino recomendado Mecanismo Visible cliente Sensible/interno Necesario sync Necesario frontend Decision
description descripcion larga comercial en catalog candidate description Woo native field YES NO YES YES PENDING_RULE
short_description descripcion corta comercial short_description Woo native field YES NO YES YES PENDING_RULE
regular_price precio publico final seleccionado para ecommerce regular_price Woo native field YES NO YES YES READY
sale_price precio promocional publico sale_price Woo native field YES NO YES YES PENDING_RULE
stock_quantity stock vendible ya normalizado stock_quantity Woo native field YES NO YES YES READY
manage_stock control de stock en Woo manage_stock Woo native field NO NO YES YES READY
brand marca ya normalizada en catalog candidate atributo visible Marca attribute YES NO YES YES PENDING_RULE
weight_kg peso ya normalizado weight Woo native field YES NO YES YES READY
volume_m3 volumen ya normalizado metadata privada meta_data NO NO NO NO READY
units_per_pack pack base de unidades meta_data.units_per_pack meta_data NO NO YES NO READY
min_units minimo de unidades por compra meta_data.min_sale_quantity meta_data NO NO YES NO READY
sale_pack_quantity multiplo o pack comercial de venta meta_data.sale_pack_quantity meta_data NO NO YES NO READY
category_raw categoria raw catalogada taxonomia cuando exista mapping taxonomy YES NO YES YES PENDING_RULE
subcategory_raw subcategoria raw catalogada taxonomia o atributo complementario taxonomy YES NO YES YES PENDING_RULE
woo_category_candidate senal interna de categoria Woo sugerida conservar interna hasta validar ids Woo PostgreSQL only NO YES YES NO READY
woo_status_candidate senal interna de publicacion sugerida traducir luego a status; no exponer como campo fuente PostgreSQL only NO YES YES NO READY
supplier_code proveedor tecnico ya normalizado mantener interno PostgreSQL only NO YES NO NO READY
supplier_name nombre proveedor ya normalizado mantener interno PostgreSQL only NO YES NO NO READY
quality_status semaforo de calidad del producto mantener interno PostgreSQL only NO YES YES NO READY
quality_notes notas internas de calidad mantener interno PostgreSQL only NO YES YES NO READY
source_row_hash hash tecnico para detectar cambios metadata privada opcional o control de sync en PostgreSQL meta_data NO YES YES NO READY
sync_batch_id trazabilidad de corrida metadata privada opcional o control de sync en PostgreSQL meta_data NO YES YES NO READY

6.8 Campos pedidos especialmente y no resueltos en la autoridad actual

Campo pedido Lectura documental actual Destino recomendado Mecanismo Visible cliente Sensible/interno Necesario sync Necesario frontend Decision
original_price no existe como campo nombrado en la autoridad ni en el candidate leido no mapear hasta definir si equivale a regular_price, precio pre-oferta o lista base UNKNOWN NO UNKNOWN NO NO UNKNOWN
descpermitido se interpreta como Descuento Permitido / PrecioCDescPermitidoFinal mantener interno PostgreSQL only NO YES NO NO READY
wc_product_id futuro relacion externa futura con Woo guardar en control de sync PostgreSQL; no disenar como campo publico PostgreSQL only NO YES YES NO READY

7. Campos que van a WooCommerce nativo

Recomendacion READY o READY/PENDING_RULE dentro de estandar Woo:

  • SKU -> sku
  • Articulo -> name
  • description -> description
  • short_description -> short_description
  • PrecioListaFinal -> regular_price
  • PrecioOfertaFinal -> sale_price solo con regla aprobada
  • Stock -> stock_quantity
  • Stock -> stock_status
  • manage_stock = true
  • PesoxUnidad -> weight
  • Category/SubCategoria -> categories solo con mapping a ids Woo
  • Marca -> attributes como Marca
  • woo_status_candidate -> status solo despues de regla publish/draft aprobada

8. Campos que van a meta_data

meta_data privada recomendada, sin exponer al catalogo publico:

  • PLU Articulo
  • [PLU Bulto]
  • Unidades_x_Bulto -> units_per_pack
  • CantVtaMin -> min_sale_quantity
  • CantVentaAgrupada -> sale_pack_quantity
  • VolumenxUnidad
  • BasePallet
  • AlturaPallet
  • CantUnidxPallet
  • CantBultosxPallet
  • PesoxPalletkg
  • VolumenxPalletm3
  • opcionalmente source_row_hash
  • opcionalmente source_sync_batch_id

Uso recomendado:

  • solo metadata privada para trazabilidad o futura logica autenticada;
  • no usarla como sustituto de un modelo comercial no decidido;
  • no usarla para costo, proveedor o reglas sensibles cuando Woo no la necesita.

9. Campos que requieren decision comercial

Quedan PENDING_RULE:

  • regla final de description y short_description;
  • si Marca queda como atributo visible simple o como taxonomia navegable;
  • mapping Category/SubCategoria -> product_cat;
  • criterio ACTIVO != publish automatico;
  • politica para sin precio;
  • politica para sin stock;
  • politica para sin imagen;
  • regla de sale_price y vigencia de oferta;
  • confirmacion de si PrecioL1 es o no la lista ecommerce;
  • si UnidadMedida se muestra al cliente o queda interna.

10. Campos que no deben exponerse

No deben exponerse en Woo publico ni en endpoint custom publico:

  • CostoListaProveedor
  • Costo
  • Cod Proveedor
  • Proveedor
  • Dcto Compra 1
  • Dcto Compra 2
  • Dcto Compra 3
  • Markup
  • MargenL1..MargenL9
  • PrecioNetoL1..PrecioNetoL9
  • IVAPListaFinal
  • IVAPrecioL1..IVAPrecioL9
  • Descuento Permitido
  • PrecioCDescPermitidoFinal
  • Fecha de Ultima Compra
  • UltVenta
  • UltCambioCosto
  • DiasSinComprar
  • DiasSinVender
  • DiasSinActCosto
  • quality_status
  • quality_notes
  • source_row_hash
  • sync_batch_id

11. Plugin / register_meta / register_rest_field / endpoint custom

11.1 Recomendacion actual

NO implementar ahora:

  • plugin propio;
  • endpoint custom;
  • register_rest_field;
  • register_meta.

11.2 Cuando si tendria sentido

Abrir un gate separado solo si aparece una necesidad concreta como:

  • exponer metadata privada seleccionada a un consumidor autenticado con schema estable;
  • devolver en REST un campo calculado que no conviene persistir;
  • hacer cumplir en WordPress reglas de carrito por pack, multiplo o minimo de venta;
  • sincronizar una taxonomia especial que el Woo estandar no cubra.

11.3 Orden recomendado si se necesitara extender

Orden de menor a mayor complejidad:

  1. meta_data privada en endpoint estandar.
  2. register_meta para exponer solo algunas metas protegidas a REST autenticado.
  3. register_rest_field para campos calculados.
  4. plugin propio.
  5. endpoint custom solo si lo anterior no alcanza.

12. Impacto futuro en gates

12.1 PDF-009B read-only preflight

No requiere extension custom.

Debe enfocarse en:

  • validar credenciales sin imprimirlas;
  • confirmar URL/base Woo;
  • hacer solo lecturas por sku o paginacion;
  • verificar si los campos nativos alcanzan para el cruce;
  • no escribir ni crear metadata.

12.2 Futuro dry-run de comparacion

Puede resolverse con:

  • sku
  • name
  • regular_price
  • sale_price
  • stock_quantity
  • stock_status
  • categories
  • attributes
  • metadata tecnica opcional (source_row_hash, sync_batch_id)

Tampoco necesita endpoint custom.

12.3 Futuro write gate

Antes de cualquier write se debe cerrar:

  • mapping real de categorias;
  • politica de publish/draft;
  • politica de sin precio, sin stock, sin imagen;
  • decision de marca como atributo o taxonomia;
  • decision de si alguna meta_data privada debe viajar de verdad.

12.4 Futuro gate de extension Woo/API

Solo abrir si el dry-run demuestra un gap real.

Trigger valido:

  • Woo no puede representar una regla comercial indispensable con campos nativos y metadata privada.

Trigger no valido:

  • querer mover campos internos "por si acaso".

13. Recomendacion final

La estrategia mas robusta y simple para SOURCE-002 -> WooCommerce La Directa es:

  • WooCommerce native first;
  • una sola capa publica de precio y stock;
  • meta_data privada minima para pack/PLU/trazabilidad si realmente aporta;
  • PostgreSQL como fuente gobernada de toda la economia sensible;
  • sin plugin y sin endpoint custom hasta que exista una necesidad probada.

14. Confirmacion de alcance

Durante este trabajo:

  • no se toco WooCommerce API;
  • no se cargaron credenciales;
  • no se leyeron secretos;
  • no se creo ni modifico .env;
  • no se toco VPS;
  • no se toco Docker;
  • no se toco PostgreSQL;
  • no se ejecuto SQL;
  • no se ejecuto sync, scheduler, cron ni pipelines;
  • no se hizo deploy;
  • no se hizo push;
  • no se modifico La Directa;
  • no se modifico runtime.