Su catálogo ya es una API: construya su propia tienda sobre Axentra

Hay una pregunta que nos hacen seguido los clientes que tienen a alguien técnico en el equipo o una agencia de confianza: “me gusta el sistema, pero quiero mi tienda con mi diseño, no una plantilla. ¿Puedo?”

La respuesta es que sí, y probablemente lleva más tiempo del que usted cree estando disponible. El catálogo de su Axentra ya es una API pública. No hay que activar un módulo nuevo ni pagar un extra: los productos que usted marca como públicos en inventario se pueden consultar desde afuera, y con eso alguien puede construirle la tienda que quiera.

Este artículo es para esa persona técnica. Si usted no lo es, pásele el enlace: en una tarde tiene el catálogo de su empresa corriendo en una página hecha a la medida.

Un solo catálogo, no dos

Lo primero es entender por qué esto importa más de lo que parece.

La forma tradicional de tener tienda en línea es mantener dos inventarios: el del sistema con el que usted factura, y el de la plataforma de la tienda. Después toca sincronizarlos. Y la sincronización siempre falla en el peor momento: usted vende el último en el mostrador, la web sigue diciendo que hay disponible, y termina llamando a un cliente para decirle que no había.

Aquí no hay dos catálogos. Hay uno, y es el de su ERP. El precio que muestra la tienda es el precio de su lista. La existencia que muestra es la existencia real de su almacén, la que baja cuando su cajero factura en el punto de venta. Marcar un producto como público es un check en la ficha del producto, y nada más.

Lo que ya puede consultar hoy

La API vive en el mismo dominio de su instancia, en /storefront/graphql, y no pide autenticación porque solo devuelve lo que usted decidió publicar: productos marcados como públicos y activos. Es de solo lectura.

Hay cuatro consultas disponibles:

storefront devuelve los datos de la tienda: nombre, logo, colores de marca, WhatsApp para el botón de contacto.
storefrontProducts lista productos con búsqueda por texto, filtro por categoría y paginación.
storefrontCategories lista las categorías con su conteo de productos.
storefrontProduct trae un producto individual por su slug, para la página de detalle.

Traer los primeros productos es esto:

const ENDPOINT = 'https://suempresa.axentra.com.do/storefront/graphql';

const res = await fetch(ENDPOINT, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: `
      query Catalogo($limit: Int, $offset: Int, $search: String) {
        storefrontProducts(limit: $limit, offset: $offset, search: $search) {
          items { id slug sku name price imageUrl inStock unitName categoryName }
          totalCount
          hasMore
        }
      }`,
    variables: { limit: 24, offset: 0, search: null },
  }),
});

const { data } = await res.json();
console.log(data.storefrontProducts.items);

Cada producto trae lo que una tienda necesita para pintarse: nombre, descripción, precio, imagen, si hay existencia, la unidad de medida y la categoría a la que pertenece.

Un componente de React, completo

Nada de pseudocódigo. Esto es una grilla de productos funcional:

import { useEffect, useState } from 'react';

const ENDPOINT = 'https://suempresa.axentra.com.do/storefront/graphql';

const QUERY = `
  query Catalogo($limit: Int, $search: String) {
    storefrontProducts(limit: $limit, search: $search) {
      items { id slug name price imageUrl inStock unitName }
      totalCount
    }
  }`;

export function Catalogo() {
  const [productos, setProductos] = useState([]);
  const [busqueda, setBusqueda] = useState('');

  useEffect(() => {
    const t = setTimeout(async () => {
      const res = await fetch(ENDPOINT, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          query: QUERY,
          variables: { limit: 24, search: busqueda || null },
        }),
      });
      const { data } = await res.json();
      setProductos(data?.storefrontProducts?.items ?? []);
    }, 250);
    return () => clearTimeout(t);
  }, [busqueda]);

  return (
    <>
      <input
        value={busqueda}
        onChange={(e) => setBusqueda(e.target.value)}
        placeholder="Buscar productos"
      />
      <div className="grilla">
        {productos.map((p) => (
          <article key={p.id}>
            {p.imageUrl && <img src={p.imageUrl} alt={p.name} />}
            <h3>{p.name}</h3>
            <p>RD$ {p.price}</p>
            <small>{p.inStock ? `Disponible por ${p.unitName}` : 'Agotado'}</small>
          </article>
        ))}
      </div>
    </>
  );
}

Búsqueda con retardo, paginación disponible en la misma consulta, existencias reales. Su diseñador se encarga del resto.

Autorice su dominio primero

Un detalle que ahorra media hora de frustración: si su tienda vive en otro dominio (tienda.suempresa.com, por ejemplo, o una vista previa en su servidor de pruebas), el navegador bloquea la llamada hasta que ese origen esté autorizado.

Eso se configura en Ajustes, en la lista de dominios permitidos. Es una lista editable por tenant, así que puede agregar el dominio de producción y el de pruebas sin pedirle permiso a nadie. Sin ese paso la consulta falla en el navegador aunque funcione perfecto desde la terminal, y es el primer tropiezo de todo el que empieza.

El alcance de esta API, para que no haya sorpresas

Vale la pena decirlo claro antes de que alguien empiece a construir: esta API es de solo lectura. Sirve para mostrar el catálogo. No registra pedidos y no procesa cobros.

Para muchos negocios eso ya es suficiente. Una vitrina bien hecha, con búsqueda y existencias reales, más un botón de WhatsApp para cerrar la venta, es exactamente la tienda que necesitan y no requiere nada más.

Si su operación necesita además cobrar en línea, esa parte existe hoy dentro del sistema, en el módulo de suscripciones y cobros, y no a través de esta API: se genera un enlace de pago, el cliente paga con su tarjeta en la página segura de la pasarela, su empresa no recibe ni almacena el número de tarjeta, y el pago queda registrado con su comprobante fiscal y su asiento contable. Es un flujo que se opera desde el sistema, no algo que hoy se pueda invocar desde una tienda hecha a la medida.

Estamos trabajando en unir las dos cosas para que una tienda propia pueda registrar el pedido y cobrarlo. Cuando esté disponible lo publicamos aquí, con la misma documentación y los mismos ejemplos.

Empiece hoy

Si tiene Axentra y alguien técnico a mano, no hay que esperar nada:

Marque como públicos los productos que quiere mostrar.
Autorice el dominio de su tienda en Ajustes.
Consuma /storefront/graphql desde donde quiera: React, Astro, Vue, o HTML con fetch.

Y si todavía no tiene Axentra, solicite una demo y le mostramos el catálogo de su empresa corriendo en una página propia antes de que termine la llamada.