Primeros pasos
Envía tu primera consulta GraphQL a Storefront API con variables, fetch o @ecomiq/storefront.
Última actualización:
GraphQL es un método adicional para consumir lecturas seleccionadas de Storefront API. REST sigue disponible para el resto de operaciones.
Qué aprenderás
En esta guía aprenderás a:
- enviar un documento GraphQL mediante
POST /graphql; - resolver la tienda con
x-Store-Domain; - separar los valores dinámicos en
variables; - ejecutar la misma consulta con cURL,
fetchy@ecomiq/storefront; - validar
datacon Zod al usar el SDK.
Solo lecturas seleccionadas
El schema expone Query, pero no Mutation. Carritos, checkout, cuentas de cliente, geografía, tracking, analítica y cualquier escritura continúan en REST.
Requisitos
Necesitas el slug o uno de los dominios configurados de la tienda. Ese valor se envía en x-Store-Domain y determina el contexto y la visibilidad de los datos.
Endpoint
| Elemento | Valor |
|---|---|
| Método | POST |
| URL | https://storefront.ecomiq.pe/graphql |
| Content type | application/json |
| Contexto de tienda | x-Store-Domain: <slug-o-dominio> |
| Body | query y, cuando corresponda, variables |
Los IDs devueltos por la API son opacos. Consérvalos como strings y reenvíalos sin intentar construirlos o interpretarlos.
1. Escribe la consulta
Esta operación obtiene el contexto básico de la tienda y el perfil público de un seller:
query SellerPage($slug: String!) {
store {
id
name
currency
}
seller(slug: $slug) {
id
name
slug
}
}$slug se declara como String!, por lo que la operación requiere una variable con ese nombre:
{
"slug": "acme"
}Usa variables para los valores dinámicos. No interpoles texto del usuario dentro del documento GraphQL.
2. Ejecuta la consulta con cURL
Envía el documento y sus variables como JSON:
curl --request POST "https://storefront.ecomiq.pe/graphql" \
--header "Content-Type: application/json" \
--header "x-Store-Domain: mi-tienda" \
--data-binary '{
"query": "query SellerPage($slug: String!) { store { id name currency } seller(slug: $slug) { id name slug } }",
"variables": { "slug": "acme" }
}'Una ejecución correcta contiene los campos solicitados dentro de data:
{
"data": {
"store": {
"id": "7204558912004325301",
"name": "Mi tienda",
"currency": "PEN"
},
"seller": {
"id": "7204558912004325310",
"name": "Acme",
"slug": "acme"
}
}
}GraphQL devuelve únicamente los campos incluidos en el selection set.
3. Ejecuta la consulta con fetch
Cuando llamas al endpoint directamente, debes enviar el contexto de tienda en cada petición:
const query = `
query SellerPage($slug: String!) {
store { id name currency }
seller(slug: $slug) { id name slug }
}
`;
const variables = { slug: "acme" };
const response = await fetch("https://storefront.ecomiq.pe/graphql", {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-Store-Domain": "mi-tienda",
},
body: JSON.stringify({ query, variables }),
});
const result = await response.json();
if (!response.ok || result.errors?.length) {
throw new Error(result.errors?.[0]?.message ?? `HTTP ${response.status}`);
}
console.log(result.data.store, result.data.seller);Una respuesta GraphQL puede incluir errors incluso con HTTP 200. Consulta la guía de errores GraphQL para manejar el envelope completo.
4. Usa @ecomiq/storefront
En código server-side de una tienda creada con el SDK, createClient() toma el dominio y la URL de la configuración. El método graphql() recibe el documento, un schema Zod para validar data y las variables opcionales:
import { createClient, z } from "@ecomiq/storefront";
const SellerPageData = z.object({
store: z.object({
id: z.string(),
name: z.string(),
currency: z.string(),
}),
seller: z.object({
id: z.string(),
name: z.string(),
slug: z.string(),
}),
});
const document = `
query SellerPage($slug: String!) {
store { id name currency }
seller(slug: $slug) { id name slug }
}
`;
const api = createClient();
const data = await api.graphql(document, SellerPageData, {
slug: "acme",
});
console.log(data.store, data.seller);El cliente envía POST /graphql con x-Store-Domain. Si la respuesta contiene errors o data no cumple el schema Zod, lanza GraphQLResponseError.
Siguientes pasos
Errores GraphQL
Maneja data, errors y los códigos públicos de los resolvers.
Referencia GraphQL
Consulta las lecturas GraphQL disponibles en Storefront API.
Catálogo REST
Usa REST para las operaciones que no forman parte del schema GraphQL.
SDK Storefront
Configura y desarrolla una tienda con @ecomiq/storefront.