Introduction

Nota (PT-BR): conteúdo técnico em inglês (fiel ao repositório AdobeDocs/commerce-webapi). Foco na edição Open Source.

What is the Magento 2 GraphQL API?

GraphQL is a query language for APIs that allows clients to request exactly the data they need in a single round-trip. The Magento 2 GraphQL API was designed primarily for PWA / headless storefronts and is now the recommended way to build customer-facing experiences.

Endpoint

POST https://<magento_host>/graphql

Um único endpoint recebe todas as queries e mutations. O body é um objeto JSON com os campos query e opcionalmente variables e operationName.

Queries vs Mutations

• Query — leitura (GET equivalente). Ex.: listar produtos, obter categorias, consultar pedidos.
• Mutation — escrita (POST/PUT/DELETE). Ex.: criar conta, adicionar ao carrinho, finalizar pedido.

Authentication

Use o mesmo token bearer da REST API:

Authorization: Bearer <customer_token>

Queries podem ser:

• Storefront / público — sem autenticação (ex.: listar produtos, categorias).
• Autenticado (customer) — usa customer token (ex.: customer, customerOrders).

Atenção: GraphQL no Magento 2 não aceita admin token. Para operações admin, use REST.

Schema & Introspection

O GraphQL do Magento é introspectável: acesse /graphql com uma ferramenta como GraphiQL, Altair ou Insomnia e explore o schema completo interativamente.

Performance

• O Magento usa Varnish para cachear queries (via HTTP cache headers).
• Adicione o header Store: <store_code> para queries scoped por store view.
• Use X-Magento-Cache-Id nos requests autenticados — melhora hit rate do cache.