Todo desarrollador requiere tener acceso inmediato a la documentación de las tecnologías que trabaja. Pues nuestro trabajo es resolver problemas y no sabernos de memoria como funciona todo. El principal problema es que la documentación suele ser extensa, variante y por ello suele encontrarse hospedada en Internet. Pero cuando no tenemos buen acceso a Internet debido a que estamos viajando, nos encontramos en un café con mala conexión, vivimos en un lugar con poco ancho de banda y otros, se vuelve un problema acceder a esta documentación. Para estos casos podemos usar DevDocs, un sitio que nos permite almacenar en nuestro navegador la documentación de muchos sitios web.

Cómo funciona DevDocs

DevDocs posee una lista de tecnologías junto a su respectiva versión. Al hacer clic sobre cada uno de ellas verás desplegada la documentación oficial (al menos en las que probé). Encima de cada enlace del menú puedes hacer clic en Enable y empezará a descargar la documentación al almacenamiento local del navegador para posterior lectura, así no tengas acceso a Internet.

Entonces al estar guardada en tu navegador, puedes acceder a DevDocs y podrás acceder a toda la documentación guardada sin la necesidad de tener conexión a Internet. Inclusive, si tienes conexión pero es lenta, es mucho mas rápido acceder a esta documentación guardada. Otra ventaja es que la documentación se sincroniza automáticamente entonces no debes preocuparte por si esta obsoleta o con errores por actualizar.

Interfaz de DevDocs
Interfaz de DevDocs

Ventajas de usar DevDocs

  • Tienes acceso rápido a la documentación en tu propio equipo sin acceder a Internet.
  • Puedes ver la documentación de varias tecnologías en un mismo formato. Tal vez no parece importante pero es cómodo no estar viendo formatos distintos cuando trabajas con varias tecnologías a las vez.
  • El buscador integrado te permite hacer una búsqueda en varios lenguajes a la vez. Útil para comparar o ver donde es mas fácil hacerlo.
  • Al ser una página web, puedes acceder la desde cualquier dispositivo. Puedes tener la documentación abierta en tu tableta o lector de libros así sea viejo.

Espero que te sirva esta información y permite mejorar tu flujo de trabajo. Recuerda compartir este artículo en las redes si te y gustó, o deja un comentario aportando tu opinión.

Zoho es una excelente herramienta en la nube para la administración de negocios. Posee una excelente API REST para realizar integración de datos entre sistemas. Hace unos días tuve problemas para subir información al API y me arrojaba el error JSON malformed.

Cómo solucionar el error de JSON malformed

La documentación no indica cual puede ser el problema y en que campo. Obviamente es un error de codificación de JSON pero al revisar mi código y los datos que estaba enviando, noté que el JSON estaba bien validado. Pero me di cuenta que Zoho pide enviar el JSON dentro del cuerpo de la petición en texto plano, no en formato JSON. Por ello, al codificar los campos en la cadena, el símbolo de ampersand ( & ) puede confundirse como el inicio de un parámetro GET. Así que es necesario codificarlo con su respectivo valor en HTML que es %26.

Así que para solucionar mi problema tuve simplemente que reemplazar el valor luego de ser codificado en JSON:

$jsonString = str_replace('&', '%26', json_encode($invoice));
$body = '&JSONString=' . $jsonString;

¡Listo! Ahora si podrás subir la data a Zoho.

Woocommerce es una excelente plataforma para montar tu propia tienda en línea. Aunque mucha gente piensa que WordPress sigue siendo solo una plataforma para blogs, desde hace años se ha cambiado el funcionamiento interno para soportar todo tipo de contenido. Woocommerce es un ejemplo de ellos, pues este plugin permite soportar todo el contenido requerido en una tienda en línea como: productos, órdenes, pagos, descuentos, entre otros.

API REST

El plugin incluye una API REST para las operaciones mas básicas (se debe activar previamente), permitiendo comunicación hacia o desde aplicaciones externas, extendiendo aún mas las posibilidades de procesos que se pueden implementar en la tienda. Sin embargo, si manejas flujos de compras personalizados o deseas realizar acciones mas allá de las disponibles en el API por defecto, puedes agregar las tuyas tal como se explicará a continuación.

Desarrollo del plugin

El plugin se divide en 2 archivos, el principal para definir el plugin como tal y permitirle indicar a WordPress en que momento se va a cargar el segundo archivo, que contiene los métodos que responden a las rutas personalizadas del API.

Cargador de la clases

Para modificar WordPress, siempre es recomendable hacerlo a través de plugins, por eso el primer paso es definir un plugin como cualquier otro y dentro del constructo de la clase del plugin, indicar a Woocommerce que luego de cargar el código necesario para implementar el API (a través del hook woocommerce_api_loaded) se deben agregar la(s) clase(s) que implementan las rutas personalizadas (a través del hook woocommerce_api_classes), este código lo pueden ver a continuación:


/**
 * Plugin Name: Woocommerce custom path example
 * Description: Custom API calls plugin
 * Version: 1.0
 * Author: Miguel Useche
 * Author URI: http://migueluseche.com
 * License: GPL 3.0
 *
 * @package MyPlugin
 */

 
if ( ! defined( 'ABSPATH' ) ) {
    exit; // Exit if accessed directly
}

if (!class_exists('WD_API_LOADER')) {

    /**
     * Main plugin class
     *
     * @package MyPlugin
     * @author Skatox
     */

    class WD_API_LOADER
    {
        public function init()
        {
          add_action( 'woocommerce_api_loaded', array( $this, 'load' ) );
        }

        public function load()
        {
            require_once plugin_dir_path( __FILE__ ).'wc-api-custom.php';
            add_filter( 'woocommerce_api_classes', array( $this, 'register' ) );
        }

        public function register( $api_classes=array() )
        {
          array_push( $api_classes, 'WC_API_Custom' );

          return $api_classes;
        }
    }
}

$wc_custom_api = new WD_API_LOADER();
$wc_custom_api->init();

Leyendo observarán que es un plugin de WordPress donde la clase WD_API_LOADER registra los hooks mencionados anteriormente, para inyectar en el momento que Woocommerce carga sus clases del API, las clases que instancia los procesos personalizados a ser implementados en el API.

Al final es recomendable instanciar la clase en un objeto, de este modo es posible acceder a los métodos de forma global desde plugines externos, como por ejemplo para detener la carga de las clases o implementar modificaciones permitiendo dar mayor flexibilidad al plugin.

Clase con los métodos de la API REST

El siguiente paso corresponde a crear la clase que responde a las peticiones HTTP del API. En este ejemplo, se define una constante con el PATH personalizado y en el constructor se definen las rutas personalizadas y el método que se debe llamar que responderá a la petición realizada. Si observas, el parámetro recibido es un array donde la llave representa la ruta relativa del API y como valor, otro arreglo con el nombre de la función a procesar la petición y las banderas del tipo de petición. Estas últimas banderas permiten definir el tipo de petición a recibir, por ejemplo
WC_API_Server::READABLE indica que lee datos desde la petición tal como es una petición GET,
WC_API_Server::ACCEPT_DATA permite decir que lea el cuerpo de la petición y permite leer información para peticiones POST y PUT, entre otros.


/**
 * Custom API REST path  class
 *
 * @package MyPlugin
 * @author Skatox
 */

class WC_API_Custom extends WC_API_Resource
{

    const PATH = '/custom';

    /**
     * Function to define each of the custom path
     */

    public function register_routes($routes)
    {
        //GET Request
        $routes[self::PATH . '/orders'] = array(
            array(array($this, 'listShippingOrders'), WC_API_Server::READABLE),
        );

        //POST Request
        $routes[self::PATH . '/orders/(?P<order_id>\d+)/fulfillments.json'] = array(
            array(array($this, 'createItem'), WC_API_Server::CREATABLE | WC_API_Server::ACCEPT_DATA),
        );

        //PUT Request
        $routes[self::PATH . '/variants/(?P<id>\d+).json'] = array(
            array(array($this, 'updateItem'), WC_API_Server::EDITABLE | WC_API_Server::ACCEPT_DATA),
        );

        return $routes;
    }

    public function listShippingOrders($fields = null, $filter = array(), $status = null, $page = 1)
    {
        $wcApiOrders = new WC_API_Orders($this->server);
        $orders = $wcApiOrders->get_orders($fields, $filter, $status, $page);

        //Removes orders without shipping methods
        foreach ($orders['orders'] as $key => $oreder)
        {
            if (empty($oreder['shipping_methods'])) {
                unset($oreders['orders'][$key]);
                continue;
            }
        }

        return $order;
    }

    public function createItem($order_id, $data)
    {
        //Do insert proccess and then return the response array
    }

    public function updateItem($id, $data)
    {
        //Do update proccess and then return the response array

    }
}

Una vez que proceses la petición, si necesitas devolver un objeto JSON, simplemente debes retornar un array con la información deseada y automáticamente Woocommerce se encargará de transformarlo en un objeto JSON e imprimirlo en la salida.

Recomendaciones

Como podrás observar, no es difícil. En caso que no sepas como desarrollar debido a la poca documentación. Te recomiendo leer el código fuente de las clases del API de Woocommerce, son fáciles de entender, creadas por el mismo equipo del plugin y verás como están creados los métodos existentes. Una de las mejores clases para guiarte, es la de productos que se encuentra ubicada en la ruta wp-plugins/woocommerce/includes/api/class-wc-api-products.php, pues es muy completa y posee todas las operaciones REST soportadas.

Recuerda crear un plugin para esto, evita colocarlo en el functions.php pues será difícil de mantener y dificulta migrar de tema (porque el API dependerá de ésta). Finalmente, recuerda respetar el estándar REST, he visto gente que implementa todo en POST y agrega incompatibilidades a aplicaciones.

Ya depende de tu imaginación, descubrir como extender las funcionalidades de Woocommerce a través de un API REST personalizado.