Usa la API REST de gestión de Product Add-Ons

Usa esta referencia para herramientas de catálogo autenticadas que gestionan grupos de POM, opciones reutilizables, definiciones específicas de producto, revisiones de publicación, asignaciones o información de integridad.

Autenticación y ámbito del sitio

• Usa una cuenta de administrador o de gestor de tienda. Los clientes HTTPS remotos pueden usar una contraseña de aplicación de WordPress; los clientes con sesión iniciada usan el nonce REST habitual.
• Usa la URL del sitio multisitio previsto. Los registros, las capacidades, las cachés y los identificadores de compatibilidad tienen ámbito de sitio.
• Lee un registro inmediatamente antes de modificarlo para que el cliente disponga de su ETag seguro actual o su revision numérico.

El espacio de nombres de gestión es:

/wp-json/pom-tweaks/v1/product-add-ons

Rutas

type es group, choice o product. Antepón el espacio de nombres mostrado antes a cada ruta anterior.

Enumerar registros

Las colecciones de grupos y opciones aceptan parámetros acotados page, per_page, search, status, orderby y order. per_page no puede superar 100. Las respuestas incluyen X-WP-Total y X-WP-TotalPages.

Los registros de grupo contienen el name interno, estado, prioridad, el campo definition, la asignación scope, el estado de publicación, la revisión y el uso de solo lectura. El ámbito admite:

• all_products, category_ids, include_children y product_ids;
• include_rules y exclude_rules para identificadores de producto, tipos de producto o términos de una taxonomía de productos registrada;
• include_relation y exclude_relation, cada uno con any o all.

Los registros de opciones reutilizables contienen name, estado, config, estado de publicación, revisión y uso de solo lectura. La configuración del producto contiene local_definition, excluded_group_ids, exclude_global y el estado de herencia del idioma canónico.

Crear un grupo

Crea un borrador de configuración habilitado que esté asignado a una categoría:

POST /wp-json/pom-tweaks/v1/product-add-ons/groups
Content-Type: application/json

{
  "name": "Gift options",
  "public_name": "Gift options",
  "status": "publish",
  "priority": 20,
  "definition": {
    "fields": []
  },
  "scope": {
    "all_products": false,
    "category_ids": [42],
    "include_children": true,
    "product_ids": [],
    "include_relation": "any",
    "exclude_relation": "any",
    "include_rules": [],
    "exclude_rules": []
  }
}

status describe si la configuración dentro del borrador está habilitada (publish) o deshabilitada (draft); no omite el paso de publicación independiente. El servidor normaliza el esquema y devuelve el registro guardado con su ETag. Un campo mal formado, un producto o término desconocido, un conjunto de reglas excesivo o un tipo no compatible rechaza la escritura completa.

Actualizar sin sobrescribir a otro editor

Lee el registro y conserva su cabecera de respuesta:

GET /wp-json/pom-tweaks/v1/product-add-ons/groups/123
ETag: "pom-pao-group-123-r7"

Envía la actualización prevista con esa condición previa:

PATCH /wp-json/pom-tweaks/v1/product-add-ons/groups/123
If-Match: "pom-pao-group-123-r7"
Content-Type: application/json

{
  "name": "Gift and presentation options",
  "priority": 15
}

Cada PUT, PATCH o DELETE debe incluir o bien el valor exacto If-Match o bien el revision numérico actual. Si ambos están presentes, deben coincidir. Una condición previa obsoleta devuelve el HTTP 409; una condición previa ausente devuelve el HTTP 428. Lee y reconcilia el registro actual en lugar de reintentar a ciegas.

La misma regla se aplica a las opciones y a la configuración del producto. Existe un filtro temporal pom_tweaks_product_addons_allow_unversioned_writes para una migración controlada de un cliente conocido, pero las escrituras sin versión no pueden detectar ediciones obsoletas y no deberían permanecer habilitadas.

Gestionar la configuración específica del producto

Lee la fuente actual y las exclusiones:

GET /wp-json/pom-tweaks/v1/product-add-ons/products/123/configuration

Actualiza local_definition, excluded_group_ids y exclude_global juntos cuando el producto necesite una configuración explícita. Envía local_definition: null para eliminar solo los campos específicos del producto.

Para un producto traducido, envía esto por sí solo para eliminar su anulación local completa y reanudar la herencia desde el producto del idioma predeterminado:

{
  "inherit_canonical": true
}

Para crear una anulación traducida explícita, envía inherit_canonical: false con los valores completos de definición local y de exclusión previstos. Las respuestas identifican canonical_product_id, configuration_source_product_id y inherits_canonical.

Explicar la asignación

Usa la ruta de explicación antes de publicar un grupo amplio o complejo:

GET /wp-json/pom-tweaks/v1/product-add-ons/groups/123/explain?product_id=456

La respuesta informa de si el grupo publicado se aplica y explica cada inclusión y exclusión. Las exclusiones a nivel de producto tienen prioridad primero, las reglas de exclusión de grupo prevalecen sobre las reglas de inclusión, y una variación hereda el tipo de producto y los términos de taxonomía del padre variable.

Publicar o restaurar una revisión

Lee el estado de publicación:

GET /wp-json/pom-tweaks/v1/product-add-ons/publications/group/123

Publica el borrador actual con su revisión de registro:

{
  "operation": "publish",
  "reason": "Reviewed gift option changes",
  "revision": 7
}

Restaura una publicación anterior como una nueva revisión con operation: "rollback" y source_revision_id. El historial se conserva; los carritos y pedidos existentes conservan sus instantáneas almacenadas.

Eliminar de forma segura

DELETE /groups/{id} y DELETE /choices/{id} mueven el registro a la papelera de forma predeterminada. Añade force=true solo para una eliminación permanente intencionada. POM devuelve el HTTP 409 con reference_count y un resumen de uso mientras quede alguna asignación, exclusión de producto o referencia de campo. No existe ninguna omisión que deje configuración huérfana.

La ruta autenticada /integrity informa de recuentos de entidades acotados y con ámbito de sitio, propiedad, mapas de uso, recuentos de huérfanos y hasta 100 muestras. Es de solo lectura y nunca repara registros automáticamente.

Límites y puntos de extensión

La API usa los mismos límites de campo, opción, asignación, carga útil y texto que la administración. Los valores predeterminados importantes de la administración incluyen 100 campos por definición, 500 opciones por campo, 2.000 opciones por definición, 24 reglas de inclusión y 24 de exclusión, 200 valores por regla y 500 valores de reglas avanzadas en total.

pom_tweaks_product_addons_assignment_taxonomies puede exponer una taxonomía ya registrada adjunta a productos. El filtro no registra la taxonomía ni concede capacidades. Usa pom_tweaks_product_addons_operational_limits solo para requisitos medidos y mantén sus valores devueltos dentro de los techos protegidos.

Verificar un cliente

1. Enumera grupos con dos páginas y confirma los totales y el orden estable.
2. Crea un grupo en borrador, actualízalo con If-Match y confirma que el valor obsoleto devuelve 409 sin modificar el registro.
3. Explica un producto incluido y un producto excluido.
4. Publica el borrador y confirma que la ruta pública de producto y el escaparate lo usan.
5. Envía a la papelera una opción reutilizable vinculada, restáurala y confirma que su relación de campo permanece.
6. Intenta la eliminación permanente mientras está vinculada y confirma la respuesta de uso 409.
7. Lee /integrity como gestor y confirma que una solicitud anónima es rechazada.
8. En multisitio, repite una lectura contra otra URL de sitio y confirma que los registros no cruzan entre sitios.

Solución de problemas

• HTTP 401 o 403: autentica a un usuario con permiso de gestión de WooCommerce y usa la URL de sitio correcta.
• HTTP 409: el registro cambió o sigue referenciado; inspecciona la respuesta antes de actuar.
• HTTP 428: lee el registro y envía su ETag o revision.
• rest_invalid_param: envía la estructura pública documentada en lugar de metadatos privados de WordPress.
• Resultado de asignación ausente: confirma que el grupo está publicado; la ruta de explicación evalúa el comportamiento de asignación publicado.

Relacionado: Publicar y restaurar configuraciones, Compatibilidad oficial de Product Add-Ons y Comprobaciones de estado y compatibilidad.