Iniciar un proyecto

Usar la API REST de Reward Points

WooCommerce Reward Points Documentation

Sume puntos de recompensa a los usuarios mediante un endpoint REST seguro que ofrece el plugin.

¿Qué hace esta API?

Ofrece un endpoint REST que suma puntos de recompensa a un usuario de WooCommerce y devuelve su nuevo total.
Internamente reutiliza la lógica manually_add_user_points() del plugin, de modo que totales, registros y hooks funcionan como al sumar puntos manualmente en el administrador.

¿Cuál es el endpoint?

  • Método: POST
  • Ruta: /wp-json/wc-reward-points/v1/add-points

¿Qué permisos se necesitan?

Solo los usuarios autenticados con la capacidad manage_woocommerce pueden llamar a este endpoint (normalmente administradores o gestores de tienda). Las solicitudes no autorizadas se rechazan.

¿Qué parámetros son necesarios?

Todos los parámetros son obligatorios y se validan en el servidor:

Campo Tipo Reglas Finalidad
user_id integer Debe existir en WordPress Usuario al que se suman los puntos
points integer Debe ser un entero positivo (> 0) Cuántos puntos se suman
message string Se sanea en el servidor (sanitize_text_field) Se muestra en el registro / nota de puntos

Ejemplo de cuerpo JSON

{
  "user_id": 123,
  "points": 250,
  "message": "Customer service gesture for delayed shipment"
}

¿Cómo es una respuesta correcta?

{
  "success": true,
  "user_id": 123,
  "points_added": 250,
  "new_total": 1420,
  "message": "Customer service gesture for delayed shipment"
}

Nota: new_total se lee de los metadatos del usuario después de sumar los puntos.

¿Qué errores pueden aparecer?

HTTP Código Cuándo ocurre
400 invalid_user user_id falta, no es válido o el usuario no existe
400 invalid_points points es <= 0 o falta
401 n/a No autenticado
403 n/a Autenticado pero sin la capacidad manage_woocommerce
404 n/a Ruta no registrada (plugin desactivado o API no activada)

¿Cómo me autentico?

  1. Contraseñas de aplicación (recomendado entre servidores): WordPress 5.6+ → Perfil de usuario → Contraseñas de aplicación → Crear nueva. Use autenticación HTTP Basic (user:application-password).
  2. Cookies de sesión + nonce (para llamadas desde wp-admin).
  3. JWT/OAuth (con plugins de autenticación aparte) si su sistema los usa.

Ejemplo de cURL (contraseñas de aplicación)

curl -X POST "https://example.com/wp-json/wc-reward-points/v1/add-points" \
  -u "admin:YOUR-APP-PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"user_id":123,"points":250,"message":"Promo: Spring bonus"}'

Configuración rápida en Postman/Insomnia

  1. Método/URL: POST https://your-site/wp-json/wc-reward-points/v1/add-points
  2. Auth: Basic → usuario: su usuario de WP, contraseña: contraseña de aplicación
  3. Cabeceras: Content-Type: application/json
  4. Cuerpo (JSON sin formato): vea el ejemplo de arriba

Ejemplo de PHP (en el servidor con contraseñas de aplicación)

<?php
$url = site_url('/wp-json/wc-reward-points/v1/add-points');
$resp = wp_remote_post($url, array(
  'headers' => array(
    'Authorization' => 'Basic ' . base64_encode('admin:YOUR-APP-PASSWORD'),
    'Content-Type'  => 'application/json',
  ),
  'body' => wp_json_encode(array(
    'user_id' => 123,
    'points'  => 100,
    'message' => 'Welcome bonus',
  )),
  'timeout' => 20,
));
if (is_wp_error($resp)) {
  error_log($resp->get_error_message());
} else {
  $code = wp_remote_retrieve_response_code($resp);
  $body = json_decode(wp_remote_retrieve_body($resp), true);
  // Handle $code / $body
}
fetch('/wp-json/wc-reward-points/v1/add-points', {
  method: 'POST',
  credentials: 'include', // send auth cookies
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ user_id: 123, points: 50, message: 'Manual adjustment' })
}).then(r => r.json()).then(console.log);
The endpoint relies on capability checks (current_user_can('manage_woocommerce')), so cookies + a logged-in admin session are sufficient for auth in this context.

¿Funciona en multisitio?

Sí. Si se cumplen ambas condiciones –WordPress es multisitio y el ajuste multisiteSplitPoints del plugin está activo–, los puntos se guardan con una clave meta propia de cada sitio:

woocommerce_reward_points_<BLOG_ID>

En caso contrario, la clave meta es:

woocommerce_reward_points

Esto importa si lee los totales directamente de los metadatos del usuario en otro lugar.

¿Por qué falta la ruta (404)?

  • El plugin (o su función de API) está desactivado.
  • La opción enable del plugin es false (las rutas solo se registran si está activado).
  • Su capa de caché bloquea /wp-json o las solicitudes POST.
  • Un plugin de seguridad / cortafuegos interfiere con las llamadas REST.

¿Qué ocurre internamente al llamar a la API?

  1. Las entradas se sanean y se validan.
  2. El código define $_POST['userId'], $_POST['points'], $_POST['text'] y $_POST['action']='woocommerce_reward_points_add_points'.
  3. Inicializa WooCommerce_Reward_Points_Earning y llama a manually_add_user_points().
  4. Lee el nuevo total de los metadatos del usuario y lo devuelve en la respuesta.

¿Puedo usarla para restar puntos?

No: este endpoint solo suma puntos (requiere points > 0). Para restar, cree un endpoint aparte o amplíe este con un proceso de resta seguro.

¿Hay límite de solicitudes o idempotencia?

No de serie. Si conecta sistemas externos, implemente la idempotencia en el cliente (p. ej. con un ID de operación único) para evitar sumas duplicadas.

¿Cómo lo pruebo rápidamente?

  1. Active el ajuste de API del plugin (enable = true).
  2. Compruebe que su usuario tiene manage_woocommerce.
  3. Ejecute el ejemplo de cURL.
  4. Verify the user’s points in the admin or via: 
    get_user_meta(123, 'woocommerce_reward_points', true);

    (o la clave propia del sitio en multisitio)

Lista de comprobación de problemas

  • 401/403: no autenticado o sin la capacidad necesaria. Use contraseñas de aplicación o una sesión de administrador.
  • 404: compruebe que la función está activada y que ningún cortafuegos bloquea /wp-json.
  • 400 invalid_user: user_id debe ser un usuario de WP existente.
  • 400 invalid_points: use un entero positivo.
  • El total no cambia: revise hooks personalizados o cachés de objetos que puedan revertir o retener los cambios.

Buenas prácticas de seguridad

  • Use preferentemente contraseñas de aplicación para llamadas entre servidores y, si es posible, una cuenta de administrador con pocos privilegios.
  • Sirva solo por HTTPS.
  • Registre cada suma con un message claro y legible.
  • Considere límites de solicitudes o reglas WAF si el endpoint es accesible más allá de sus sistemas internos.