¿Cómo crear un webservice en Adobe Commerce (Magento 2)?

Un webservice en Adobe Commerce (Magento 2) es un punto de acceso que su empresa define para que otro sistema consulte o envíe información a la tienda mediante una API REST o SOAP. Crearlo requiere un módulo pequeño, pero el valor está en decidir qué se expone, a quién y con qué controles.

Imagine el cierre semanal de una cadena de tiendas de repuestos. El director de operaciones presenta resultados y, aunque las ventas en línea crecieron, el inventario del ERP y el catálogo de la tienda muestran existencias distintas. Varios clientes compraron productos agotados y recibieron un correo de disculpa. El equipo comercial señala a logística, logística señala a sistemas y la directora financiera pregunta, con razón, cuánto costaron esa semana los reembolsos, las llamadas de servicio y los clientes que no volvieron. Nadie discute que la plataforma de comercio electrónico funciona. Lo que falla es la conversación entre ella y el resto de la empresa.

Esa conversación tiene un nombre técnico, servicio web, y una explicación simple. Los webservices son mecanismos vitales para que dos o más sistemas se comuniquen, ya que permiten transferir información, ejecutar procedimientos o capturar datos de los usuarios. Este artículo explica primero por qué la integración es una decisión de dirección y no solo de desarrollo, y después recorre, con un ejemplo completo, cómo se crea un servicio web en Adobe Commerce, la plataforma antes conocida como Magento, con las prácticas vigentes de la documentación oficial.

¿Qué es un webservice y para qué le sirve a una empresa?

Un servicio web es una puerta con reglas. Del lado de la tienda se define una operación concreta, por ejemplo recibir los datos de una persona que solicita información, y del lado del sistema externo se llama a esa operación cuando hace falta. La tienda no entrega su base de datos ni expone sus pantallas internas, solo responde a las preguntas y a los envíos que su empresa decidió permitir. Esa limitación es lo que lo hace valioso, porque permite conectar sistemas sin que cada conexión sea un proyecto a medida.

Adobe Commerce ofrece soporte para servicios web a través de APIs REST y SOAP. Según la documentación para desarrolladores de Adobe, la ruta de cada servicio se declara en un archivo llamado webapi.xml, donde se indica el método HTTP (GET, POST, PUT o DELETE), una dirección que comienza con la versión, como /V1, y la clase y el método del servicio que responderá. La misma definición sirve para que otros sistemas consuman el servicio, y por eso conviene escribirla con cuidado desde el primer día.

Los usos más comunes se reconocen en cualquier industria. Un distribuidor de consumo masivo sincroniza el inventario del ERP con el catálogo para no vender lo que no tiene. Un banco o una aseguradora envía al CRM los datos de quien solicita una cotización o una cita, de modo que un asesor lo contacte mientras el interés sigue vivo. Un fabricante recibe en su sistema los pedidos de sus distribuidores sin que alguien los digite de nuevo. Una cadena hotelera conecta su programa de lealtad con la aplicación móvil para que el huésped vea sus puntos en tiempo real. En todos los casos el servicio web es el canal, y el negocio está en lo que ese canal permite hacer.

Por qué la integración es una decisión de la dirección

Cuando la comunicación entre sistemas falla, el costo rara vez aparece en una sola línea del presupuesto. Se reparte entre horas de personas que copian datos de una pantalla a otra, pedidos que se corrigen a mano, reportes que no coinciden y clientes que reciben información distinta según el canal. Por eso es una conversación que corresponde al comité de dirección y no solo al área de tecnología.

El informe de conectividad de MuleSoft de 2023, elaborado con Vanson Bourne a partir de una encuesta a 1.050 líderes de tecnología de empresas con al menos mil empleados en nueve países, ofrece una radiografía útil. Las organizaciones encuestadas usan en promedio 1.061 aplicaciones y solo el 29% de ellas está integrado. Además, el 80% de los consultados afirma que los retos de integración frenan sus esfuerzos de transformación digital y el 99% usa APIs para conectar aplicaciones y datos. Son cifras de un estudio de un proveedor de tecnología y conviene leerlas con esa prudencia, pero muestran que casi todas las empresas ya tienen APIs y que la ventaja está en decidir con criterio cuáles construir.

La tienda en línea suele ser el punto donde esa falta de criterio se hace visible primero, porque es el sistema que habla con el cliente. Una existencia mal reflejada es una venta cancelada, un formulario que no llega al CRM es un prospecto que se enfría y un precio desactualizado es un margen perdido.

Qué debe decidir la dirección antes de pedir el desarrollo

Un servicio web bien construido empieza antes del código. La primera decisión es el propósito y el dueño de la información. Si la aseguradora de nuestro ejemplo quiere capturar solicitudes de cotización desde la tienda, alguien debe responder por esos datos, saber en qué sistema viven y decidir cuánto tiempo pueden esperar antes de que un asesor los atienda. Sin un dueño claro, el servicio funciona técnicamente y fracasa operativamente, porque nadie revisa las solicitudes que llegan.

La segunda decisión es la dirección y la frescura del flujo. No es lo mismo que la tienda consulte al ERP el inventario en el momento en que el cliente mira un producto, que el ERP envíe cambios cada cierto tiempo, o que ambos se sincronicen al cierre del día. Cada opción cuesta distinto, tolera fallos distintos y produce una experiencia distinta para el cliente. Una empresa de repuestos de alta rotación necesita inventario casi inmediato, mientras que un fabricante que vende por contrato puede aceptar una sincronización diaria.

La tercera es quién puede llamar al servicio. Esa decisión determina el nivel de riesgo y se desarrolla más adelante, pero conviene adelantar que un formulario público y una integración entre dos sistemas internos no deberían compartir las mismas reglas de acceso. La cuarta es qué ocurre cuando algo falla. Un servicio sin monitoreo, sin responsable de soporte y sin un plan para los envíos que no llegaron es una deuda que se paga en la peor semana del año, normalmente cuando una campaña dispara el tráfico.

Cuando estas cuatro respuestas están escritas y acordadas entre negocio y tecnología, el trabajo del equipo de desarrollo se reduce a una tarea acotada. Lo que sigue es esa tarea, explicada con un ejemplo mínimo.

¿Cómo crear un webservice en Adobe Commerce paso a paso?

El ejemplo que sigue captura los datos de una persona que llena un formulario de contacto, los envía al servidor y los procesa. Podría ser la participación en un sorteo, la solicitud de un servicio particular o un reclamo, y el mismo esquema sirve para conectar un ERP o un CRM. Es una demostración básica pensada para un equipo de desarrollo con acceso al código de la tienda, no una solución lista para producción. Se recomienda agregar validaciones y un captcha antes de ponerla en una página pública.

1. Cree el formulario del lado del cliente

Primero se necesita el formulario HTML que verá el usuario. Para armarlo rápido puede usarse una herramienta de generación de formularios como Bootsnipp, que entrega el código listo para copiar.

Ese código se copia y se pega en el lugar donde se quiera mostrar al usuario. Para este ejercicio se crea una página llamada contact desde el administrador de contenido de la tienda. El formulario debe tener el identificador contact-form, el botón de envío debe tener el identificador submit y los campos deben llamarse name e info, porque el servicio recibirá exactamente esos dos parámetros.

2. Envíe el formulario con JavaScript

Para enviar el formulario cuando el usuario presiona el botón Submit se usa el siguiente código. Es una demostración básica, y se invita a agregar mayor funcionalidad como validaciones o un captcha. Donde aparece contact-form en la dirección del servicio, debe escribir el nombre que quiera dar a la ruta de su webservice, el mismo que usará en el archivo webapi.xml.

<script type="text/javascript" defer>
  require(['jquery','jquery/ui'], function($) {
    $('#submit').on('click', function(){
      var formData = new FormData($("#contact-form")[0]);
      formData = JSON.stringify(Object.fromEntries(formData));
      $('body').trigger('processStart');
      $.ajax({
        type: "POST",
        url: "/rest/V1/custom/contact-form/",
        data: formData,
        success: function(){
          $('body').trigger('processStop');
          alert("Success");
        },
        error: function (xhr, ajaxOptions, thrownError) {
          $('body').trigger('processStop');
          alert("Error");
        },
        dataType: 'json',
        contentType: 'application/json',
      });
    });
  });
</script>

3. Cree el módulo con la API y la ejecución del lado del servidor

Con el formulario listo, falta la mitad del servidor. En la carpeta app/code del directorio de la tienda se crea un módulo. En este ejemplo se llama Acme_Contact, y los archivos van en app/code/Acme/Contact. Reemplace Acme y Contact para que correspondan con el nombre de su empresa y de su módulo. El primer archivo, registration.php, registra el módulo en la plataforma. La nota sobre cómo organizar un repositorio de GitHub en Magento 2 sugiere cómo guardar el módulo.

<?php
\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::MODULE,
    'Acme_Contact',
    __DIR__
);

El archivo etc/module.xml declara el módulo y su dependencia del módulo de servicios web de la plataforma. La guía oficial de Adobe para crear una API REST personalizada declara de esta forma las dependencias de carga y omite el atributo setup_version que se usaba en versiones anteriores, de modo que conviene seguir ese formato en una instalación actual.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Acme_Contact">
        <sequence>
            <module name="Magento_Webapi"/>
        </sequence>
    </module>
</config>

El archivo etc/di.xml indica qué clase implementa la interfaz del servicio.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <preference for="Acme\Contact\Api\Contact" type="Acme\Contact\Model\Api\Contact"/>
</config>

En etc/webapi.xml se define la ruta. Debe reemplazar contact-form por el mismo nombre que asignó en el código JavaScript. La referencia anonymous permite que cualquier visitante llame al servicio, algo razonable para un formulario público y que se revisa en la sección de seguridad más abajo.

<?xml version="1.0"?>
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">
    <route method="POST" url="/V1/custom/contact-form/">
        <service class="Acme\Contact\Api\Contact" method="getPost"/>
        <resources>
            <resource ref="anonymous"/>
        </resources>
    </route>
</routes>

El archivo Api/Contact.php es la interfaz. Aquí se indican los parámetros que recibe el webservice, que en este caso son solo dos, el nombre y la información de contacto. Ambos son cadenas de texto y sus nombres deben coincidir con los nombres de los campos del formulario HTML. La documentación de Adobe advierte que, para que REST y SOAP funcionen, los comentarios de la interfaz deben seguir un formato estricto, con el tipo de cada parámetro y del valor devuelto, y que los tipos de objeto deben escribirse con su nombre completo.

<?php
namespace Acme\Contact\Api;

interface Contact
{
    /**
     * GET for Post api
     * @param string $name
     * @param string $info
     * @return string
     */
    public function getPost($name, $info);
}

Por último, Model/Api/Contact.php contiene la funcionalidad del método getPost. Debe conservar los mismos parámetros y nombres que en la interfaz anterior, e implementarla de forma explícita.

<?php
namespace Acme\Contact\Model\Api;

use Psr\Log\LoggerInterface;

class Contact implements \Acme\Contact\Api\Contact
{
    protected $logger;

    public function __construct(
        LoggerInterface $logger
    )
    {
        $this->logger = $logger;
    }

    /**
     * @inheritdoc
     */
    public function getPost($name, $info)
    {
        $response = ['success' => false];
        try {
            // Su lógica aquí
            $response = ['success' => true, 'message' => $name . " " . $info];
        } catch (\Exception $e) {
            $response = ['success' => false, 'message' => $e->getMessage()];
            $this->logger->info($e->getMessage());
        }
        return json_encode($response);
    }
}

Dentro de la función getPost puede agregarse el comportamiento deseado, como guardar la información en una base de datos, enviar un correo electrónico o reenviar los datos al CRM. De cualquier forma, siempre se recomienda hacer validaciones de seguridad tanto del lado del cliente como del lado del servidor, para evitar ataques de inyección de código o simplemente limpiar formatos de datos inválidos.

4. Instale, compile y pruebe

Una vez que los archivos están en su lugar, solo falta instalar el módulo y compilar. Adobe indica ejecutar la instalación y la compilación después de cambiar archivos XML, agregar parámetros al constructor o crear clases nuevas, y el orden habitual es el siguiente.

bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Ahora ingrese los datos en el formulario. Conviene abrir la consola de inspección del navegador (en Chrome, con F12 o clic derecho e inspeccionar), ir a la pestaña Network y revisar lo que sucede cuando se presiona Submit.

Debería verse un código 200 con el mensaje de respuesta. Si el código de error es 400, revise la sintaxis de su JavaScript, y si es un error 500, revise los registros ubicados en var/log/system.log y var/log/exception.log, además de /var/log/apache2/error.log si usa Apache o /var/log/nginx/nginx_error.log si usa Nginx.

Seguridad: ¿servicio anónimo o autenticado?

La decisión más importante del archivo webapi.xml cabe en una línea, la referencia del recurso. La documentación de Adobe describe tres posibilidades. Con self, el servicio solo trabaja con los datos de quien lo llama. Con anonymous, cualquier visitante puede invocarlo. Con el identificador de un recurso de control de acceso, solo pueden hacerlo los usuarios o integraciones a los que se les asignó ese permiso. Un formulario de contacto público necesita anonymous, mientras que un servicio que actualiza inventario o precios nunca debería usarlo.

Adobe también ha endurecido el valor por defecto. Su guía sobre seguridad de las APIs anónimas explica que la plataforma bloquea de forma predeterminada el acceso anónimo a interfaces que podrían exponer información propia, como productos, categorías, atributos, páginas y bloques de contenido o la configuración de las tiendas, y que el ajuste correspondiente se encuentra en la configuración de servicios, en la seguridad de la API web. La guía recomienda revisar antes qué integraciones de terceros llaman a esos puntos, porque bloquearlos puede interrumpirlas.

Para las integraciones entre sistemas, la guía de autenticación de Adobe describe la autenticación por token para usuarios administradores y clientes en aplicaciones de terceros, que debe usarse siempre sobre HTTPS, y la autenticación OAuth 1.0a mediante una integración registrada para sistemas externos. La elección entre una y otra la tomará su equipo técnico, pero la dirección debe exigir que existan credenciales propias para cada sistema conectado, que puedan revocarse sin afectar a los demás y que tengan los permisos mínimos para su función.

Queda un riesgo que suele subestimarse en los servicios públicos, el abuso por volumen. La función nativa de limitación de solicitudes, disponible desde Adobe Commerce 2.4.7 y desactivada por defecto, se describe como una protección contra ataques de prueba de tarjetas y cubre los puntos de pago y orden de las APIs REST, además de GraphQL. La documentación no menciona las rutas personalizadas, de modo que un servicio anónimo propio, como el de este ejemplo, debe protegerse con las medidas que su empresa ya usa, como un captcha, reglas en el firewall de aplicaciones web y monitoreo del tráfico. La nota sobre ciberseguridad esencial para su tienda en Adobe Commerce amplía esas medidas.

Qué significa para la alta dirección

Para quien responde por la captación de clientes, un servicio web bien diseñado es la diferencia entre un prospecto atendido en minutos y uno que espera a que alguien revise una hoja de cálculo. Las solicitudes de cotización, las citas y las consultas que nacen en la tienda llegan al CRM con sus datos completos y, si se definió un responsable, con una acción de seguimiento.

Para quien responde por la conversión y el servicio, la integración evita la promesa que no se cumple. Un inventario confiable, un precio vigente y un estado de pedido que coincide con lo que dice el almacén reducen las cancelaciones y las llamadas de reclamo. Una cadena de repuestos como la del inicio no necesita más tecnología para resolver su cierre semanal, necesita acordar qué sistema manda sobre cada dato y construir un servicio que lo respete.

Para quien responde por la eficiencia y el control, la tarea es evitar dos extremos. Uno es el exceso de conexiones improvisadas, cada una con su propia credencial olvidada. El otro es la parálisis, en la que todo cambio espera meses porque nadie sabe qué se rompería. La respuesta es un inventario de integraciones con dueño, propósito, nivel de acceso y plan de soporte, revisado con la misma regularidad que otros riesgos del negocio. Cuando la empresa decide más adelante cambiar de ERP, actualizar la plataforma de comercio o incorporar inteligencia artificial, ese inventario es lo que permite hacerlo sin sorpresas. El artículo sobre cuándo actualizar el software a la última versión disponible muestra por qué conviene planificarlo.

Cómo empezar el lunes

Un consultor con experiencia en estas operaciones sugeriría comenzar por la conversación, no por el código. Reúna a quien dirige comercio, a quien dirige operaciones y a quien lidera tecnología y pídales que nombren las tres veces en el último trimestre en que la información no coincidió entre sistemas. Elija un flujo, el que más cuesta, y escriba en una página quién es su dueño, qué debe viajar, con qué frecuencia y qué ocurre si falla.

Con esa página en mano, pida al equipo de desarrollo una propuesta que incluya el tipo de acceso, la forma de probarlo y el plan de monitoreo. La guía oficial de Adobe sugiere probar los servicios protegidos con un cliente REST como Postman y un token de administrador, lo que permite verificar el comportamiento antes de conectar el sistema real. Al terminar, mida lo que le importa al negocio, por ejemplo el tiempo entre una solicitud y su primera atención, o el número de pedidos corregidos a mano cada semana. Si esos números mejoran, habrá justificado la siguiente integración. Si la tienda ya se conecta con un ERP o un CRM, el artículo sobre las seis integraciones clave en su ecommerce y la guía para integrar su CRM y su ERP con un plan claro ayudan a ordenar las prioridades.

Cómo le ayuda ICX

ICX Consulting, firma de consultoría en experiencia del cliente y estrategia comercial con sede en Miami, ayuda a empresas de Estados Unidos y Latinoamérica a decidir qué sistemas deben conversar, con qué reglas y con qué retorno, antes de que se escriba la primera línea de código. Desde nuestra práctica de integración de procesos con sistemas y de arquitectura empresarial diseñamos los flujos entre la tienda, el ERP y el CRM, y los implementamos sobre Adobe Commerce con nuestro equipo de comercio electrónico B2B y de comercio electrónico B2C. ¿Quiere saber qué integraciones le cuestan hoy más de lo que parece? Solicite un diagnóstico con un consultor de ICX.

Para documentar y rediseñar los procesos que dependen de esas conexiones, el Marco de transformación de procesos (PTF) de ICX ofrece una guía para ordenar los flujos, sus responsables y sus puntos de falla.

Preguntas frecuentes

¿Qué diferencia hay entre REST y SOAP en Adobe Commerce?

Ambos protocolos se atienden con la misma definición de servicio en webapi.xml. REST usa direcciones y métodos HTTP y es la opción habitual para aplicaciones web y móviles. SOAP es un protocolo más antiguo que se mantiene por compatibilidad con sistemas heredados. Para integraciones nuevas, REST suele ser más sencillo de construir, probar y operar.

¿Puedo exponer un servicio sin autenticación?

Sí, con la referencia anonymous, pero solo debería hacerse para funciones públicas como un formulario de contacto. Aun así, requiere validación en el servidor, un captcha y vigilancia del tráfico. Cualquier servicio que lea o modifique datos del negocio debe exigir un permiso específico y credenciales propias del sistema que lo consume.

¿Cómo se prueba un servicio web protegido?

Con un cliente REST, como Postman, y un token de administrador, según la guía de Adobe. Se envía la solicitud a la ruta del servicio con el cuerpo en formato JSON y se verifica la respuesta. Hacerlo en un entorno de pruebas, con datos ficticios, permite validar permisos y errores antes de conectar sistemas reales.

¿Quién debe ser el dueño de una integración dentro de la empresa?

El área de negocio que depende del dato debe ser su dueña, y tecnología es la responsable de operarla. Si el flujo alimenta al CRM con solicitudes de clientes, la dirección comercial define los tiempos de atención y tecnología garantiza que el servicio esté disponible, seguro y monitoreado.

Cada integración que su empresa deja a medias se paga con horas de personas que copian datos de una pantalla a otra, con clientes que reciben información distinta según el canal y con decisiones tomadas sobre cifras que no coinciden. Si quiere que su tienda converse con el resto de la empresa con orden y con seguridad, hable con un consultor de ICX y empiece por los flujos que hoy cuestan más.