¿Qué es una API de comercio headless? MACH, comercio componible y la capa de contrato

Si está construyendo una tienda que no encaja en una plantilla estándar, probablemente necesite una API de comercio sin cabecera (headless commerce API). En esta arquitectura, el backend de comercio expone productos, carritos, precios, inventario y pedidos mediante una API, mientras que el frontend se implementa como una aplicación independiente. En la práctica, la API se convierte en el contrato que conecta la tienda, apps móviles, integraciones de socios y otros canales. Este enfoque se relaciona con el comercio componible y MACH, y parte de una idea clave: el software se está volviendo sin cabecera y su API es ahora el producto.

Prueba Apidog hoy

Qué significa "sin cabecera" (headless) en el comercio

En una plataforma de comercio tradicional, el catálogo, el carrito, el checkout y las páginas HTML suelen vivir en el mismo sistema. Usted aplica un tema, configura la tienda y la publica.

En comercio sin cabecera, esas responsabilidades se separan:

• Backend de comercio: catálogo, precios, inventario, carrito, pedidos y reglas de negocio.
• Frontend: tienda web, app móvil, kiosco, asistente de voz u otro canal.
• API: contrato que conecta ambos lados.

La "cabecera" es la capa de presentación. Volverse sin cabecera significa reemplazar una presentación fija por una API que cualquier cliente pueda consumir.

Un flujo típico se ve así:

Frontend React / App móvil / POS
        |
        | HTTP / GraphQL / REST
        v
API de comercio
        |
        v
Catálogo, precios, inventario, carrito, pedidos

Esto permite que el equipo frontend elija su framework y despliegue su experiencia de usuario sin estar atado al tema de la plataforma. El equipo backend mantiene las reglas de comercio. La API define el límite entre ambos.

La desventaja: usted asume más trabajo de ingeniería. Debe construir, desplegar, probar y mantener la tienda. Por eso el enfoque sin cabecera tiene sentido cuando:

• necesita una experiencia de compra muy personalizada;
• quiere servir varios canales desde el mismo backend;
• el tema estándar de la plataforma limita al equipo;
• varios equipos o socios necesitan integrarse contra el mismo contrato.

Sin cabecera vs. componible vs. MACH

Estos términos se solapan, pero no significan lo mismo.

Término	Lo que describe	Alcance
Comercio sin cabecera	Frontend desacoplado de un backend de comercio, conectado por una API	Un backend, una o varias interfaces
Comercio componible	Pila dividida en servicios intercambiables de "lo mejor de su clase": catálogo, búsqueda, pagos, PIM, OMS	Muchos servicios independientes ensamblados
MACH	Principios arquitectónicos que muchas pilas componibles siguen	Una filosofía, no un producto

Sin cabecera es el caso más limitado. Puede tener una tienda sin cabecera aunque el backend siga siendo monolítico, siempre que el frontend consuma sus capacidades mediante una API.

Comercio componible va más allá. En lugar de depender de un único backend, usted combina servicios independientes: búsqueda de un proveedor, pagos de otro, PIM separado, OMS separado, etc. Cada pieza expone su propia API.

MACH es el conjunto de principios detrás de muchas arquitecturas componibles. Según la MACH Alliance, formada en 2020, MACH significa:

• Microservicios
• API-first
• Cloud-native SaaS
• Headless

El punto importante para desarrolladores: en MACH, la API no es un detalle secundario. Es la forma principal en que las piezas se comunican. Ese es el mismo razonamiento detrás de tratar su API como un producto.

Lo que expone una API de comercio sin cabecera

La forma exacta depende de la plataforma, pero la mayoría de APIs de comercio sin cabecera cubren estas áreas:

• Catálogo y productos: productos, variantes, colecciones, imágenes y metadatos.
• Búsqueda y navegación: consultas, filtros, ordenamiento y facetas.
• Carrito y checkout: crear carritos, agregar o eliminar artículos, aplicar descuentos y avanzar hacia el pago.
• Clientes: inicio de sesión, cuentas, direcciones e historial de pedidos.
• Inventario y precios: stock disponible y precios según contexto.
• Pedidos: creación, lectura, actualización de estado y seguimiento.

Un ejemplo simple de respuesta de producto podría verse así:

{
  "id": "prod_123",
  "slug": "camiseta-negra",
  "title": "Camiseta negra",
  "description": "Camiseta de algodón",
  "variants": [
    {
      "id": "var_123_s",
      "sku": "CAM-NEG-S",
      "size": "S",
      "price": {
        "amount": 2999,
        "currency": "EUR"
      },
      "inventory": {
        "available": true,
        "quantity": 24
      }
    }
  ],
  "images": [
    {
      "url": "https://example.com/products/camiseta-negra.png",
      "alt": "Camiseta negra"
    }
  ]
}

Este contrato importa porque el frontend depende de nombres, tipos y estructuras concretas. Si variants cambia a items, o si price.amount pasa de número a string sin aviso, la tienda puede romperse.

Muchas plataformas separan sus APIs en dos tipos:

• API de tienda: orientada al cliente, intensiva en lectura, usada por el frontend.
• API de administración: orientada a back-office, usada para editar catálogo, gestionar pedidos y configurar la tienda.

El protocolo también influye. Muchas APIs de comercio sin cabecera usan GraphQL porque permite pedir exactamente los campos necesarios en una sola llamada. Otras usan REST, y algunas ofrecen ambas opciones. Si está evaluando el diseño, consulte REST vs GraphQL.

Ejemplo de consulta GraphQL para una página de producto:

query ProductPage($slug: String!) {
  product(slug: $slug) {
    id
    title
    description
    images {
      url
      alt
    }
    variants {
      id
      sku
      price {
        amount
        currency
      }
      inventory {
        available
      }
    }
  }
}

Ejemplo equivalente en REST:

GET /store/products/camiseta-negra
Accept: application/json

Plataformas principales

El ecosistema de comercio sin cabecera se divide, en general, entre motores SaaS y motores de código abierto. Algunas opciones frecuentes son:

• commercetools. Miembro fundador de la MACH Alliance y una de las plataformas de comercio componible más citadas. API-first y nativa de la nube por diseño.
• Shopify. Permite construcciones sin cabecera mediante Storefront API, con Hydrogen como framework React para consumirla. Si ya trabaja con Shopify, este tutorial de la API de Shopify es un buen punto de partida.
• BigCommerce. Admite modo sin cabecera con GraphQL Storefront y Checkout APIs sobre su catálogo. Consulte la guía para usar las APIs de BigCommerce.
• Saleor. Motor de código abierto, GraphQL-first, construido en Python y Django.
• Medusa. Motor de código abierto construido en Node.js y TypeScript, popular entre equipos JavaScript que quieren control del backend.

Antes de elegir una plataforma, valide:

• cobertura real de la API;
• límites de rate limit;
• modelo de autenticación;
• soporte para webhooks;
• opciones de hosting;
• versionado;
• coste;
• facilidad para probar y simular contratos.

El patrón base es el mismo: el motor expone la lógica de comercio mediante una API y usted construye la cabecera.

Cómo diseñar el contrato de una API de comercio sin cabecera

Una vez que la tienda está desacoplada, la API deja de ser "tubería" y se convierte en el acuerdo técnico entre equipos.

Un enfoque práctico:

1. Liste los casos de uso del frontend

   • página de listado;
   • página de producto;
   • búsqueda;
   • carrito;
   • checkout;
   • cuenta de cliente;
   • historial de pedidos.

2. Defina los recursos o queries

   • GET /products
   • GET /products/{slug}
   • POST /cart
   • POST /cart/{id}/items
   • POST /checkout
   • GET /customers/{id}/orders

3. Modele las respuestas

   • campos obligatorios;
   • campos opcionales;
   • tipos;
   • errores;
   • paginación;
   • estados.

4. Documente ejemplos reales

   • producto simple;
   • producto con variantes;
   • producto sin stock;
   • descuento inválido;
   • carrito abandonado.

5. Ejecute pruebas de contrato

   • valide que la implementación respeta la especificación;
   • detecte cambios incompatibles antes del despliegue;
   • pruebe integraciones de socios con datos estables.

Un ejemplo mínimo de OpenAPI para productos:

openapi: 3.0.3
info:
  title: Storefront API
  version: 1.0.0

paths:
  /products/{slug}:
    get:
      summary: Obtener producto por slug
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Producto encontrado
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        "404":
          description: Producto no encontrado

components:
  schemas:
    Product:
      type: object
      required:
        - id
        - slug
        - title
        - variants
      properties:
        id:
          type: string
          example: prod_123
        slug:
          type: string
          example: camiseta-negra
        title:
          type: string
          example: Camiseta negra
        description:
          type: string
        variants:
          type: array
          items:
            $ref: "#/components/schemas/ProductVariant"

    ProductVariant:
      type: object
      required:
        - id
        - sku
        - price
      properties:
        id:
          type: string
          example: var_123_s
        sku:
          type: string
          example: CAM-NEG-S
        price:
          type: object
          required:
            - amount
            - currency
          properties:
            amount:
              type: integer
              example: 2999
            currency:
              type: string
              example: EUR

Por qué los equipos dependen del contrato de la API de comercio

Su equipo frontend no puede lanzar una página de producto si no conoce la forma exacta de la respuesta. Una app móvil consume el mismo contrato. Una integración de fidelización, impuestos o marketplace también depende de esos endpoints.

Si una respuesta cambia sin previo aviso, todos los consumidores pueden fallar a la vez.

Por eso el contrato debe ser:

• claro;
• estable;
• versionado;
• probado;
• documentado;
• compartido entre equipos.

Un contrato sólido permite que equipos independientes avancen sin bloquearse. Uno ambiguo convierte cada release en coordinación manual.

Aquí entran las pruebas de contrato. Sirven para detectar cambios incompatibles antes de que lleguen a producción o a una integración de socio.

Buenas prácticas de versionado:

• Prefiera cambios aditivos: agregar campos suele ser más seguro que renombrarlos.
• No elimine campos sin ventana de deprecación.
• Documente fechas de retiro.
• Mantenga ejemplos actualizados.
• Ejecute pruebas en CI.
• Avise a consumidores externos antes de cambios incompatibles.

Ejemplo de cambio seguro:

{
  "id": "prod_123",
  "title": "Camiseta negra",
  "brand": "Acme"
}

Aquí brand se agregó sin romper consumidores existentes.

Ejemplo de cambio riesgoso:

{
  "id": "prod_123",
- "title": "Camiseta negra"
+ "name": "Camiseta negra"
}

Si el frontend espera title, este cambio rompe la tienda.

Dónde encaja Apidog

Apidog no gestiona su tienda. No es un motor de comercio, CMS ni pasarela de pago. Tampoco convierte por sí solo su arquitectura en sin cabecera o componible.

Su rol es más específico: ayudarle a diseñar, probar, simular y documentar el contrato de API del que dependen la tienda y las integraciones.

Un flujo práctico con Apidog sería:

1. Diseñar el contrato primero
   
   Modele la API de tienda o administración como una especificación OpenAPI en Apidog antes de implementar el backend.

2. Acordar la forma de los datos
   
   Frontend y backend revisan productos, carritos, errores y estados antes de escribir código dependiente.

3. Simular la API
   
   Genere un servidor mock desde la especificación para que el equipo frontend avance aunque el backend siga en desarrollo. Puede profundizar en la explicación de API simulada.

4. Probar el contrato en CI
   
   Ejecute pruebas de API sin GUI mediante CLI para validar que la implementación sigue cumpliendo el contrato.

5. Publicar documentación interactiva
   
   Entregue a equipos internos y socios una única fuente de verdad para integrarse.

Para entender por qué esto importa cuando la API se convierte en la única interfaz, vea el software se está volviendo sin cabecera y su API es ahora el producto. Si quiere probar el flujo, descargue Apidog e importe una especificación existente.

Checklist para implementar una tienda sin cabecera

Use esta lista antes de empezar el desarrollo:

• [ ] Definir canales: web, móvil, POS, marketplace, etc.
• [ ] Elegir backend de comercio.
• [ ] Decidir REST, GraphQL o ambos.
• [ ] Diseñar contrato de productos.
• [ ] Diseñar contrato de carrito.
• [ ] Diseñar contrato de checkout.
• [ ] Definir autenticación y permisos.
• [ ] Definir errores estándar.
• [ ] Crear ejemplos de respuesta.
• [ ] Generar mocks para frontend.
• [ ] Configurar pruebas de contrato.
• [ ] Publicar documentación para equipos y socios.
• [ ] Establecer política de versionado y deprecación.

Preguntas frecuentes

¿Es el comercio sin cabecera lo mismo que el comercio componible?

No. El comercio sin cabecera desacopla la tienda de un backend de comercio mediante una API. El comercio componible ensambla muchos servicios independientes de "lo mejor de su clase", cada uno con su propia API, en una experiencia única.

Toda pila componible suele ser sin cabecera, pero una configuración sin cabecera con un backend monolítico no es necesariamente componible.

¿Necesito GraphQL para una API de comercio sin cabecera?

No. GraphQL es común porque permite al frontend pedir exactamente los campos necesarios en una sola llamada. Esto encaja bien con páginas de producto, carritos y experiencias dinámicas.

Pero muchas APIs de comercio sin cabecera usan REST, y algunas plataformas ofrecen ambas. El protocolo importa menos que la estabilidad, documentación y capacidad de prueba del contrato.

¿Puedo probar una API de comercio sin cabecera antes de que el backend esté construido?

Sí. Si define el contrato como una especificación, puede generar un servidor simulado con respuestas realistas.

Así, el equipo frontend puede construir contra mocks mientras el motor de comercio sigue en desarrollo. Más tarde, cambia los endpoints simulados por los reales.

¿Qué es la Alianza MACH?

La MACH Alliance es un grupo industrial formado en 2020 para promover pilas tecnológicas abiertas y "best-of-breed" basadas en:

• Microservicios;
• API-first;
• Cloud-native SaaS;
• Headless.

Proveedores como commercetools son miembros fundadores. MACH no es un producto único; es un conjunto de principios arquitectónicos.

El contrato es la tienda

El comercio sin cabecera mueve el centro de gravedad desde el tema hacia la API. Una vez que el frontend está desacoplado, la API de comercio es la base sobre la que trabajan equipos web, móviles y socios.

El comercio componible y MACH llevan esa idea más lejos al convertir API-first en un principio central.

Apidog no reemplaza su motor de comercio, pero sí puede darle un lugar para diseñar, simular, probar y documentar el contrato. Si su proyecto depende de una API de comercio estable, Apidog puede ser esa capa de trabajo sin pretender ser la plataforma de comercio subyacente.