WooCommerce REST API: как добавить и обновить метаполя заказа без ошибок

Диагностика проблемы: почему метаполя заказов не сохраняются через REST API

При работе с WooCommerce REST API часто возникает задача добавить или обновить метаполя (custom fields) заказа. Однако стандартная документация WooCommerce не всегда охватывает этот момент подробно, и многие разработчики сталкиваются с ошибками или тем, что метаполя не сохраняются.

Основные симптомы проблемы:

• При отправке запроса на обновление заказа с метаполями, они не сохраняются, хотя ответ API успешный (статус 200).
• Ошибки вида Invalid parameter(s): meta_data или meta_data is not allowed.
• Некорректное отображение или отсутствие новых полей в админке WooCommerce.

Как правильно добавлять и обновлять метаполя заказа через WooCommerce REST API

Поддержка метаполей в WooCommerce REST API

С версии WooCommerce 3.5.0 REST API поддерживает работу с метаданными через параметр meta_data. Это массив объектов с ключами key и value. Пример структуры:

{
  "meta_data": [
    {
      "key": "_custom_key",
      "value": "custom_value"
    }
  ]
}

Важно: ключ метаполя должен начинаться с подчёркивания, если оно служит для скрытых данных (как в большинстве случаев WooCommerce).

Пример запроса для обновления заказа с метаполями

Используем PATCH-запрос к REST API:

PATCH /wp-json/wc/v3/orders/123

{
  "meta_data": [
    {
      "key": "_delivery_date",
      "value": "2024-07-10"
    },
    {
      "key": "_gift_wrap",
      "value": "yes"
    }
  ]
}

В PHP с использованием библиотеки WooCommerce REST API клиент:

$data = [
  'meta_data' => [
    [
      'key' => '_delivery_date',
      'value' => '2024-07-10'
    ],
    [
      'key' => '_gift_wrap',
      'value' => 'yes'
    ]
  ]
];

$woocommerce->put('orders/123', $data);

Пошаговое решение проблемы с метаполями заказов

1. Проверьте версию WooCommerce. Метаполя в REST API поддерживаются с версии 3.5.0, обновитесь при необходимости.
2. Используйте ключ meta_data с массивом объектов {key, value}. Отправляйте именно такую структуру.
3. Обязательно используйте HTTP-метод PATCH или PUT для обновления заказа. POST только для создания новых заказов.
4. Проверяйте права доступа пользователя API. Для обновления метаданных нужно, чтобы пользователь имел права 'edit_shop_orders'.
5. Отправляйте запросы с правильными заголовками и авторизацией. Обычно Basic Auth или OAuth.
6. Проверьте, что другие плагины не блокируют метаполя. Иногда плагины безопасности или оптимизации могут фильтровать нестандартные поля.

Как проверить, что метаполя успешно добавлены

1. Через REST API сделайте GET-запрос на заказ:

GET /wp-json/wc/v3/orders/123

В ответе должен присутствовать массив meta_data с вашими ключами и значениями.

2. В админке WordPress перейдите в редактирование заказа и в разделе «Пользовательские поля» (если не видны, включите через «Настройки экрана») убедитесь, что там добавлены нужные поля.

3. Используйте код в functions.php для отладки (например, вывод в error_log):

add_action('woocommerce_update_order', function($order_id) {
  $order = wc_get_order($order_id);
  error_log(print_r($order->get_meta('_delivery_date'), true));
});

Частые ошибки при работе с метаполями через REST API и их исправление

• Ошибка «meta_data is not allowed»: значит, вы используете устаревший endpoint или версию WooCommerce без поддержки метаданных. Обновите WooCommerce и API.
• Метаполя не сохраняются, хотя запрос успешен: проверьте права пользователя API и используйте PATCH/PUT, а не POST для обновления.
• Ключи метаполей без подчёркивания: метаполя WooCommerce обычно должны начинаться с _, иначе могут не отображаться или конфликтовать с другими данными.
• Проблемы с авторизацией: убедитесь, что токены или ключи API имеют права на редактирование заказов.

Практические советы по безопасности и производительности

• Для защиты ключей API используйте .htaccess или серверные правила, ограничивайте доступ по IP.
• Кэшируйте GET-запросы к заказам на стороне клиента, чтобы снизить нагрузку.
• Не храните в метаполях чувствительные данные без шифрования.
• При массовом обновлении заказов с метаполями используйте пакетные запросы и реализуйте повторные попытки при ошибках 429.

Сравнение вариантов добавления метаполей в WooCommerce заказ