GraphQL / Headless API

OmniBuy expone una API GraphQL que te permite construir storefronts headless, apps móviles o integraciones personalizadas usando exactamente los datos que necesitas.

Endpoint

POST https://{tenant}.omnibuy.net/graphql

También hay un playground interactivo disponible en:

GET https://{tenant}.omnibuy.net/graphql

Autenticación

Todas las peticiones requieren dos headers:

Authorization: Bearer <access_token>
X-Tenant-ID: <tu-tenant-id>

Las queries y mutaciones marcadas como [admin] requieren un token con scope de administrador. Las operaciones públicas (catálogo, carrito, reseñas) solo necesitan un token de cliente o de API key pública.

Queries disponibles

Catálogo

# Listar productos con filtros
query {
  products(filter: { status: "active" }, limit: 20) {
    edges {
      node {
        id
        title
        handle
        variants {
          id
          price
          compareAtPrice
          inventoryQuantity
        }
        images {
          url
          altText
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# Obtener un producto por ID
query {
  product(id: "uuid-aqui") {
    id
    title
    descriptionHtml
    collections {
      id
      title
    }
  }
}

Carrito

# Obtener carrito
query {
  cart(id: "uuid-carrito") {
    id
    lines {
      id
      quantity
      variant {
        id
        title
        price
      }
    }
    subtotal
    total
  }
}

Órdenes (cliente autenticado)

query {
  orders(limit: 10) {
    edges {
      node {
        id
        number
        status
        total
        createdAt
        lineItems {
          title
          quantity
          price
        }
      }
    }
  }
}

Analytics (solo admin)

query {
  analytics(range: { start: "2026-01-01", end: "2026-04-01" }) {
    totalRevenue
    totalOrders
    averageOrderValue
    topProducts {
      productId
      title
      revenue
    }
  }
}

Mutaciones disponibles

Carrito

# Agregar ítem al carrito
mutation {
  addToCart(
    cartId: "uuid-carrito"
    input: { variantId: "uuid-variante", quantity: 2 }
  ) {
    id
    lines {
      id
      quantity
    }
    total
  }
}

# Actualizar cantidad
mutation {
  updateCartItem(
    cartId: "uuid-carrito"
    itemId: "uuid-linea"
    quantity: 3
  ) {
    id
    total
  }
}

# Eliminar ítem
mutation {
  removeFromCart(
    cartId: "uuid-carrito"
    itemId: "uuid-linea"
  ) {
    id
    lines {
      id
    }
  }
}

Reseñas

mutation {
  createReview(input: {
    productId: "uuid-producto"
    rating: 5
    title: "Excelente producto"
    body: "Llegó rápido y en perfecto estado."
  }) {
    id
    rating
    status
  }
}

Perfil de cliente

mutation {
  updateProfile(input: {
    firstName: "Ana"
    lastName: "García"
    phone: "+51912345678"
  }) {
    id
    firstName
    lastName
    email
  }
}

Paginación

Todas las listas usan paginación cursor-based con el patrón Connection:

query {
  products(limit: 25, cursor: "cursor-opaco") {
    edges {
      node { id title }
      cursor
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
  }
}

Para obtener la siguiente página, pasa endCursor como el parámetro cursor de la siguiente query.

Manejo de errores

Los errores de GraphQL siguen el estándar con el array errors:

{
  "errors": [
    {
      "message": "Product not found",
      "extensions": {
        "code": "RESOURCE_NOT_FOUND",
        "path": ["product"]
      }
    }
  ]
}

Código	Descripción
UNAUTHENTICATED	Token ausente o inválido
FORBIDDEN	Sin permisos suficientes (requiere admin)
RESOURCE_NOT_FOUND	El recurso solicitado no existe
VALIDATION_ERROR	Input inválido

SDKs

Los SDKs de OmniBuy soportan GraphQL de forma nativa:

// JavaScript / TypeScript
import { OmniBuyClient } from '@omnibuy/sdk';

const client = new OmniBuyClient({
  tenantId: 'mi-tenant',
  accessToken: 'token',
});

const { products } = await client.graphql.query(`
  query { products(limit: 5) { edges { node { id title } } } }
`);

// Go
result, err := client.GraphQL.Query(ctx, `
  query { products(limit: 5) { edges { node { id title } } } }
`, nil)