Referencia de API

Arquitectura de APIs

El proyecto integra múltiples fuentes de datos a través de diferentes APIs:

1. API de Magento (GraphQL y REST)
2. API de Directus (GraphQL)
3. API de Typesense (HTTP/REST)
4. APIs internas de Next.js (Proxies y manipulación de datos)

APIs de Magento

Endpoints Principales

Endpoint	Descripción
/api/magento/graphql	Proxy para la API GraphQL de Magento
/api/magento/rest/*	Proxy para la API REST de Magento

GraphQL de Magento

Consulta de Carrito

query CartQuery($cartId: String!) {
  cart(cart_id: $cartId) {
    id
    items {
      id
      product {
        name
        sku
      }
      quantity
      prices {
        price {
          value
          currency
        }
      }
    }
    prices {
      grand_total {
        value
        currency
      }
    }
  }
}

Ejemplo de Solicitud

const response = await requestMagento({
  query: CART_QUERY,
  variables: { cartId: 'abc123' },
  signal: abortController.signal
});

Respuesta

{
  "data": {
    "cart": {
      "id": "abc123",
      "items": [
        {
          "id": "123",
          "product": {
            "name": "Producto Ejemplo",
            "sku": "SKU123"
          },
          "quantity": 1,
          "prices": {
            "price": {
              "value": 299.99,
              "currency": "MXN"
            }
          }
        }
      ],
      "prices": {
        "grand_total": {
          "value": 299.99,
          "currency": "MXN"
        }
      }
    }
  }
}

Gestión de Sesiones y Cookies

Dado que se utilizan ambos frontends a la vez (Magento / Headless) dependiendo de la página, no es posible utilizar solo las apis REST de magento, por lo que se hace uso de las cookies de sesión generadas por magento, esto causa que tener 2 dominios diferentes no puedan compartir cookies.

El proxy de Magento (/api/magento/graphql/index.js) maneja automáticamente el traspaso de cookies de sesión entre el cliente y Magento. Las sesiones se mantienen con la cookie PHPSESSID que es modificada para funcionar en el dominio del frontend.

En modo producción no es necesario, ya que cloudflare se encarga de manejar el balanceo de cargas utilizando el mismo nombre de dominio.

API de Directus

Endpoints Principales

Endpoint	Descripción
${DIRECTUS_URL}/graphql	Endpoint GraphQL de Directus
${DIRECTUS_URL}/assets/:id	Acceso a activos (imágenes, etc.)

Ejemplo de Consulta GraphQL

query LandingPage($status: String = "published") {
    landing_page(filter: {
        status: {_eq: $status}
    }, limit: 100) {
        slug
    }
}

Ejemplo de Uso

const tagPromotions = await directusGraphql({
  query: TagPromotions,
  variables: {
    status: DirectusStatusType.published,
  }
});

API de Typesense

Métodos Principales

Método	Descripción
TypesenseService.search	Búsqueda general en el índice
TypesenseService.searchBySkus	Búsqueda por SKUs específicos
TypesenseService.searchBySku	Búsqueda por un solo SKU
TypesenseService.getBestSellers	Obtiene productos más vendidos

Ejemplo de Uso

const product = await TypesenseService.searchBySku({
  sku: 'SKU123',
  indexName: 'products',
  attributesToRetrieve: ['name', 'price', 'image_url']
});

Limitaciones Conocidas

1. Proxies y CORS: En desarrollo, todas las solicitudes a Magento deben pasar por el proxy para evitar problemas de CORS.
2. Manejo de Sesiones: Las sesiones de Magento están vinculadas a cookies que deben ser gestionadas correctamente.
3. Cache de GraphQL: Algunas consultas GraphQL pueden ser cacheadas para mejorar el rendimiento.