wp_add_post_terms: asigna términos a una entrada
Establece qué términos de una taxonomía lleva una entrada.
Sustituye por defecto
El nombre dice «añadir». El comportamiento, salvo que pases append: true, es sustituir todos los términos existentes en esa taxonomía.
Llamarlo con una sola etiqueta sobre una entrada que tiene cinco etiquetas deja la entrada con una etiqueta. Las otras cuatro desaparecen y nada te avisa.
Es el valor por defecto más destructivo de los grupos de herramientas de WordPress, porque la pérdida es invisible: la escritura se ejecuta correctamente, la entrada tiene buen aspecto y la clasificación que falta no se detecta hasta semanas después, cuando una página de archivo se queda corta.
Pasa append: true siempre que tu intención sea añadir.
Argumentos
| Argumento | Obligatorio | Significado |
|---|---|---|
post_id |
Sí | La entrada que se va a modificar |
taxonomy |
Sí | Qué taxonomía |
terms |
Sí | IDs de término que se van a establecer |
append |
No | Añadir a los términos existentes en lugar de sustituir |
dry_run |
No | Informar sin escribir |
terms acepta IDs de término, no nombres. Un término debe existir ya; créalo primero con wp_create_term.
Permisos
Allow content writes abierto y edit_post sobre la entrada de destino.
La taxonomía debe estar registrada para ese tipo de contenido, y el actor también necesita su capacidad assign_terms. Cada ID de término suministrado debe existir en esa taxonomía. El permiso para editar la entrada por sí solo no es suficiente.
Los dos patrones seguros
Para añadir sin perder nada:
Añade el término 42 a la entrada 412, agregándolo a los términos existentes.
Para establecer una lista exacta, lee primero los términos actuales para saber qué estás sustituyendo:
Lee la entrada 412 y muéstrame sus categorías actuales. Luego establece exactamente estas: 42 y 57.
No emitas nunca una llamada de sustitución sin haber visto el estado actual.
Revisa las asignaciones actuales
La vista previa incluye los IDs de término actuales en before y los IDs solicitados en terms. Comprueba el valor exacto de append en la solicitud antes de aprobar. Si otro editor cambia las asignaciones, obtén una aprobación nueva.
Una taxonomía a la vez
La llamada afecta solo a la taxonomía que nombres. Establecer categorías no toca las etiquetas, y viceversa.
Para una entrada que necesita cambios en dos taxonomías, eso supone dos llamadas —y dos oportunidades de sustituir algo por accidente—.
Eliminar todos los términos
Pasar un array terms vacío con append en false elimina todos los términos de esa taxonomía de la entrada. Es una operación legítima y un accidente fácil: un cliente que resolvió cero IDs de término a partir de una búsqueda por nombre y llamó de todos modos despoja a la entrada de su clasificación.
Si un asistente informa de que asigna «sin términos», comprueba la entrada.
Qué devuelve
Los IDs de taxonomía de términos resultantes, o un error.
Vuelve a leer la entrada para ver los términos por nombre:
Aplícalo y luego lee la entrada 412 y muéstrame sus categorías y etiquetas.
En un lote
Reetiquetar muchas entradas es un buen trabajo para MCP y un mal lugar para equivocarse con append —el error se repite en cada entrada—.
Haz una prueba piloto con tres:
Añade el término 42 a las tres primeras entradas, muéstrame los términos resultantes de cada entrada y detente.
Comprueba esas tres en WordPress antes de continuar. Consulta Create terms and organize content.
Problemas comunes
| Síntoma | Causa |
|---|---|
| La escritura se rechaza | Puerta de escritura de contenido cerrada |
pom_ai_mcp_forbidden |
Sin edit_post sobre esa entrada |
| Los términos existentes desaparecieron | No se estableció append |
| Todos los términos desaparecieron | Un array terms vacío con append en false |
| Un error sobre términos no válidos | Los IDs no existen en esa taxonomía |
| Nada cambió en el front-end | La caché no se purgó |
Relacionado
wp_create_term— los términos deben existir primerowp_get_categoriespara encontrar los IDswp_get_post— lee antes de sustituir