API REST de WordPress: Cómo Crear Endpoints Personalizados (rest_api_init), Autenticación y Solución de Errores 401/403

La API REST de WordPress (accesible de forma nativa a través del prefijo /wp-json/) transforma cualquier instalación de WordPress en un backend de aplicaciones moderno capaz de comunicarse con flujos de n8n, aplicaciones móviles en Flutter/React, pasarelas bancarias por Webhook y servidores MCP (Model Context Protocol).

En esta guía para desarrolladores veremos cuáles son los endpoints nativos más útiles, cómo programar tus propios endpoints personalizados con rest_api_init y register_rest_route en PHP, cómo protegerlos correctamente con permission_callback y cómo solucionar los errores 401 Unauthorized, 403 Forbidden y 404 Not Found.

1. Endpoints nativos principales de la API REST de WordPress (/wp-json/wp/v2/)

Sin instalar ningún plugin, WordPress expone rutas JSON para consultar y gestionar sus entidades principales:

• GET /wp-json/wp/v2/posts?per_page=10&_embed — Lista las últimas entradas incluyendo datos de autor e imagen destacada embebida.
• POST /wp-json/wp/v2/posts/{id} — Actualiza el título, estado, categorías o contenido de una entrada existente.
• GET /wp-json/wp/v2/pages?slug=contacto — Obtiene una página específica por su slug.
• POST /wp-json/wp/v2/media — Sube archivos multimedia directamente a la biblioteca de medios.
• GET /wp-json/wp/v2/users/me — Verifica las credenciales del usuario autenticado actualmente.

2. Cómo crear un Endpoint personalizado en WordPress con rest_api_init

Cuando los endpoints por defecto no bastan (por ejemplo, cuando necesitas actualizar metadatos privados, recibir un webhook externo o exponer una consulta SQL optimizada), puedes registrar tu propio namespace y ruta usando el hook rest_api_init:

add_action('rest_api_init', function () {
    register_rest_route('devcristian/v1', '/actualizar-stock/', array(
        'methods'             => 'POST',
        'callback'            => 'devcristian_actualizar_stock_callback',
        'permission_callback' => function () {
            // Exige que el usuario autenticado tenga permisos para editar productos
            return current_user_can('edit_products');
        },
        'args'                => array(
            'sku' => array(
                'required'          => true,
                'sanitize_callback' => 'sanitize_text_field',
            ),
            'cantidad' => array(
                'required'          => true,
                'validate_callback' => function ($param) {
                    return is_numeric($param);
                },
            ),
        ),
    ));
});

function devcristian_actualizar_stock_callback(WP_REST_Request $request) {
    $sku      = $request->get_param('sku');
    $cantidad = intval($request->get_param('cantidad'));

    $product_id = wc_get_product_id_by_sku($sku);
    if (!$product_id) {
        return new WP_Error('producto_no_encontrado', 'No existe un producto con ese SKU.', array('status' => 404));
    }

    wc_update_product_stock($product_id, $cantidad, 'set');

    return new WP_REST_Response(array(
        'success'    => true,
        'product_id' => $product_id,
        'nuevo_stock'=> $cantidad,
    ), 200);
}

3. Caso Real en WordPress.org: Endpoint REST para almacenamiento temporal (MCOD Temp Storage)

Un ejemplo real de arquitectura basada en la API REST de WordPress es nuestro plugin oficial gratuito MCOD Temp Storage publicado en WordPress.org. Utiliza endpoints REST personalizados para permitir que flujos de automatización (en n8n o Make) suban archivos binarios temporales y obtengan una URL pública que se autodestruye a las 2 horas mediante WP-Cron.

Si quieres aprender a empaquetar tus propios endpoints dentro de un plugin modular, revisa nuestra guía sobre cómo crear un plugin en WordPress desde cero con PHP.

4. Solución a los errores más comunes de la API REST de WordPress

• Error 404 Not Found en /wp-json/: Ocurre cuando los enlaces permanentes están en modo «Simple» o el archivo .htaccess perdió las reglas de reescritura. Ve a Ajustes → Enlaces permanentes, selecciona Nombre de la entrada y haz clic en Guardar cambios.
• Error 401 rest_not_logged_in / 403 rest_cannot_edit: Asegúrate de enviar el encabezado Authorization: Basic base64(usuario:contraseña_de_aplicacion) en peticiones externas, o el encabezado X-WP-Nonce: wpApiSettings.nonce si realizas la petición por AJAX/Fetch desde el mismo frontend de WordPress.
• Campos personalizados que no aparecen en el JSON: Para que un metadato se pueda leer o escribir en meta vía REST, debes registrarlo con register_post_meta() incluyendo 'show_in_rest' => true.