Referencia para desarrolladores de Composite Products

Esta referencia cubre las superficies públicas estables para tiendas personalizadas e integraciones admitidas. El servidor sigue siendo la autoridad para la pertenencia de productos, la disponibilidad, las reglas, el stock, los Add-Ons y el precio.

Opciones del capítulo Explorar

GET /wp-json/pom-tweaks/v1/composite-products/<product_id>/chapters/<chapter_id>/options

Los parámetros de consulta admitidos son opcionales page_size de 1 a 50, el cursor opaco devuelto por la respuesta anterior, search de hasta 100 caracteres, category_id y hasta 200 claves selected[] en formato product_id:variation_id. Cuando se omite page_size, se aplica la Options per load del capítulo; un valor de 0 hereda la Default options per load del producto, que por defecto es 12. Un page_size válido explícito anula el valor predeterminado guardado para esa solicitud. El servidor siempre aplica el máximo de 50; las opciones seleccionadas se revalidan y se devuelven por separado de la página de descubrimiento.

La respuesta separa los options actuales de los selected_options revalidados, enumera las claves seleccionadas no disponibles y devuelve has_more más next_cursor. Nunca construyas ni persistas un cursor. Reinicia desde la primera página cuando un cursor quede invalidado por un cambio de producto, término o configuración.

Descubrir los Add-Ons de los componentes

GET /wp-json/pom-tweaks/v1/composite-products/<product_id>/chapters/<chapter_id>/components/<component_id>/addons

Añade variation_id para una variación exacta. Usa el modelo público respaldado por UUID devuelto para construir la intención addons de un presupuesto. Se admiten campos de elección, casilla de verificación, texto, área de texto, precio personalizado, multiplicador de entrada, encabezado y fecha. Las cargas de archivos y los multiplicadores de reserva por persona o por bloque no se pueden representar en el contrato JSON de Composite.

Solicitar un presupuesto

POST /wp-json/pom-tweaks/v1/composite-products/<product_id>/quote

Cuerpo de ejemplo:

{
  "quantity": 2,
  "selections": [
    {
      "chapter_id": "chapter-drinks",
      "items": [
        {
          "product_id": 125,
          "variation_id": 130,
          "quantity": 4,
          "addons": {
            "context-uuid": {
              "field-uuid": "option-uuid"
            }
          }
        }
      ]
    }
  ]
}

Omite variation_id o usa cero para un producto simple. quantity multiplica la configuración completa; la cantidad de cada componente es la cantidad dentro de una configuración.

Una respuesta correcta incluye valid, quote_hash, la revisión de la configuración, los desgloses por capítulo y por elemento, los detalles de las reglas, el stock, los totales de cálculo sin impuestos, money_context, cart_allocation y scenario_state. La validación de negocio devuelve valid: false con errores legibles por máquina y sin totales de confianza. Una solicitud mal formada o una configuración guardada imposible devuelve un error REST.

totals.management_fee es la comisión efectiva sin impuestos de una configuración. totals.management_fee_rule_id identifica la primera regla de combinación exacta habilitada que sustituyó a la predeterminada; es una cadena vacía cuando se aplica la predeterminada o el producto usa precios de total fijo. La coincidencia usa la selección validada completa entre los capítulos visibles, los ID de variación exactos y el ajuste de cantidad de la regla. La solicitud de presupuesto sigue conteniendo solo la intención de selección: los clientes no pueden enviar una comisión de confianza ni una regla ganadora. Las adiciones de Cart y de la Store API vuelven a cotizar la misma intención en el servidor.

En un presupuesto válido de la tienda, POM Tweaks escribe totals.unit_total_html en el importe de precio principal de WooCommerce y en cualquier POM Theme de precio fijo de la barra de producto. El resumen de Composite sigue usando totals.total_html, que incluye la cantidad solicitada del producto principal. Esto mantiene el precio estándar del producto como un importe por configuración mientras que el resumen sigue siendo el total completo de la compra.

La raíz de Composite despacha entonces un evento de navegador ascendente pom:composite:unit-price-updated. Su detail contiene productId, valid, el unitTotal numérico, el displayUnitTotal numérico en el contexto fiscal de la tienda y el unitTotalHtml saneado. Cuando el presupuesto no es válido, valid es falso, unitTotal es null, unitTotalHtml está vacío y se restaura el precio original del producto. Los temas personalizados pueden escuchar este evento cuando su marcado de precio de producto visible no usa la estructura estándar .summary .price o .entry-summary .price de WooCommerce.

La solicitud está limitada a 65.536 bytes, ocho niveles de anidamiento, 30 entradas de capítulo, 200 selecciones por capítulo, 200 selecciones en total y cantidades enteras de 1 a 999. De forma predeterminada, el tráfico público de presupuestos permite 40 solicitudes cada 10 segundos para su identidad principal de cliente o navegador, más un techo de red anónima más amplio de 400 solicitudes. Una respuesta limitada usa el estado 429 y las cabeceras de reintento estándar.

Límites de configuración

El editor impide nuevas filas en los límites visibles. La validación del servidor rechaza una solicitud modificada por encima de un límite sin truncar la configuración ni reemplazar el último valor guardado válido.

Contratos de error

Los fallos estructurales usan códigos pom_composite_* estables e incluyen un data.path compatible con JSON Pointer cuando hay disponible una ubicación de la solicitud. Entre los ejemplos importantes se incluyen:

• pom_composite_quote_body_too_large con el estado 413;
• pom_composite_quote_body_too_deep;
• pom_composite_duplicate_chapter_selection;
• pom_composite_duplicate_selected_item;
• pom_composite_too_many_selected_items; y
• pom_composite_unknown_chapter con el estado 400.

Una configuración guardada no válida devuelve un error coincidente pom_composite_configuration_* con el estado 409 en lugar de evaluar una definición parcial. La limitación de velocidad devuelve pom_composite_quote_rate_limited con el estado 429 y cabeceras de reintento. Los fallos del esquema de argumentos de WordPress pueden usar rest_invalid_param.

Añadir al carrito en la Store API

Envía el mismo contrato de selección bajo extensions.pom-composite.selections. POM Tweaks vuelve a cotizar y realiza la misma inserción atómica de producto principal y componentes que usa el formulario de producto. Las filas del carrito de la Store API exponen la relación de grupo y mantienen no editables los controles de cantidad y eliminación de los componentes.

Puntos de extensión PHP admitidos

• pom_tweaks_composite_component_product_types añade un slug de tipo de producto a la búsqueda de administración y a la elegibilidad del servidor. El tipo personalizado debe seguir siendo compatible con la tienda y con el ciclo de vida del carrito.
• pom_tweaks_composite_builder_hooks amplía las posiciones de constructor incluidas en la lista de permitidos. Los valores deben nombrar ganchos de acción reales; las posiciones simbólicas integradas pom_composite_description_start y pom_composite_description_end se gestionan a través de la descripción larga del producto.
• pom_tweaks_composite_summary_hooks amplía las posiciones de acción de WordPress incluidas en la lista de permitidos que usa cada diseño, incluido el constructor de ranuras (Slot builder). Cada producto registra una sola vez su acción de resumen configurada; la tienda elimina la alternativa en línea oculta cuando esa acción se representa correctamente.
• pom_tweaks_product_addons_component_summary proporciona el resumen de descubrimiento acotado de Product Add-Ons que se usa para evitar cargar un contrato de componente completo cuando no hay campos configurables.
• pom_tweaks_composite_before_builder y pom_tweaks_composite_after_builder se ejecutan alrededor del constructor.
• pom_tweaks_composite_before_chapter y pom_tweaks_composite_after_chapter se ejecutan alrededor de un capítulo.
• pom_tweaks_composite_storefront_option filtra los datos de visualización preparados, nunca el precio autoritativo.
• pom_tweaks_composite_before_component_validation, pom_tweaks_composite_validate_component y pom_tweaks_composite_after_component_validation admiten integraciones de contenedores durante la validación del presupuesto y del carrito.
• pom_tweaks_composite_component_cart_item_data añade datos no autoritativos de línea de componente y no puede reemplazar la identidad reservada, las instantáneas de Add-Ons ni el precio.

Ejemplo de elegibilidad de tipo de producto personalizado:

add_filter(
    'pom_tweaks_composite_component_product_types',
    static function (array $types): array {
        $types[] = 'my_product_type';

        return $types;
    }
);

Las integraciones operativas pueden ajustar el limitador de presupuestos acotado mediante pom_tweaks_composite_quote_rate_limit y los filtros de identidad de confianza. pom_tweaks_composite_quote_observed expone campos agregados de duración y carga de trabajo sin selecciones, nombres de productos, datos de clientes, cookies, nonces ni identificadores de red. El registro optativo de WooCommerce se controla mediante pom_tweaks_composite_quote_logging_enabled y está deshabilitado por defecto.