Products & Categories

products — Busca de produtos

Query principal de catálogo. Aceita search (full-text), filter, sort, pageSize e currentPage.

{
    products(
        search: "tshirt"
        filter: { price: { from: "10", to: "100" } }
        sort: { price: ASC }
        pageSize: 20
        currentPage: 1
    ) {
        total_count
        page_info { page_size current_page total_pages }
        items {
            sku
            name
            url_key
            price_range {
                minimum_price {
                    final_price { value currency }
                    discount { percent_off amount_off }
                }
            }
            image { url label }
            small_image { url }
            categories { id name url_path }
            ... on ConfigurableProduct {
                configurable_options {
                    attribute_code
                    label
                    values { value_index label }
                }
            }
        }
        aggregations {
            attribute_code
            label
            count
            options { value label count }
        }
    }
}

aggregations retorna os filtros disponíveis (facetas) para construir UI de navegação.

categories / categoryList — Árvore de categorias

categories é a query moderna (Magento 2.4+). Aceita filtros e paginação:

{
    categories(
        filters: { parent_id: { eq: "2" } }
        pageSize: 20
    ) {
        total_count
        items {
            id
            uid
            name
            url_path
            children_count
            children {
                id
                name
                url_path
                product_count
            }
        }
    }
}

Para obter uma categoria específica:

{
    categories(filters: { url_key: { eq: "men" } }) {
        items {
            id
            name
            children {
                id name url_path
            }
        }
    }
}

categoryList está deprecated desde 2.4.3 — migre para categories.

customAttributeMetadataV2 — Metadados de atributos

{
    customAttributeMetadataV2(attributes: [
        { attribute_code: "color", entity_type: "catalog_product" }
    ]) {
        items {
            code
            label
            entity_type
            frontend_input
            is_required
            is_unique
            default_value
            options { label value }
        }
        errors { type message }
    }
}

Use para renderizar formulários dinâmicos com os atributos corretos (select, textarea, date, etc.).

urlResolver — Descobrir o tipo de uma URL do storefront

Peça tipo e ID de entidade a partir de uma URL. Essencial para roteamento client-side no PWA Studio / Hyvä.

{
    urlResolver(url: "/men/tops.html") {
        type         # CATEGORY | PRODUCT | CMS_PAGE
        id
        entity_uid
        relative_url
        redirectCode  # 0 = sem redirect; 301 = permanente; 302 = temporário
    }
}

Dica (PT-BR): o campo redirectCode permite seu frontend respeitar redirects administrativos.