Árbol del API · Productos y precios › productSuggestions

Buscar artículos

productSuggestions

Tipo

Query

Devuelve

[ProductSuggestion!]!

Permiso de la llave

Selects y autocompletes GraphQL

Estable

Busca artículos por clave, descripción o código de barras y devuelve hasta 50, ordenados por clave.

Úsala para un buscador de artículos mientras el usuario escribe. A diferencia de productsConnection, busca palabras en cualquier parte de la descripción, no tiene páginas y, si no envías onlyActive: true, también trae artículos inactivos. No trae precios: pide el artículo elegido con product(id:) y customerId.

productSuggestions(
  query: String!  familyIds: [ID!]  onlyActive: Boolean
): [ProductSuggestion!]!

# buscar-articulos.graphql
query BuscarArticulos($texto: String!) {
  productSuggestions(query: $texto, onlyActive: true) {
    id
    idpart
    name
    unit { id code }
  }
}

Variables: {"texto": "tornillo 1/4"}

jq -n --rawfile q buscar-articulos.graphql \
  '{query: $q, variables: {"texto":"tornillo 1/4"}}' |
curl https://mi-empresa.advantacloud.com/graphql \
  -H "Authorization: Bearer $ADVANTA_API_KEY" \
  -H "Content-Type: application/json" \
  --data @-

import { readFile } from "node:fs/promises";

const query = await readFile("buscar-articulos.graphql", "utf8");

const res = await fetch("https://mi-empresa.advantacloud.com/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ADVANTA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query,
    variables: { texto: "tornillo 1/4" },
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);

const { data, errors } = await res.json();
if (errors) throw new Error(errors[0].extensions?.code ?? errors[0].message);
console.log(data.productSuggestions);

import os, requests

URL = "https://mi-empresa.advantacloud.com/graphql"
HEADERS = {"Authorization": f"Bearer {os.environ['ADVANTA_API_KEY']}"}
QUERY = open("buscar-articulos.graphql").read()

r = requests.post(URL, headers=HEADERS, timeout=30, json={
    "query": QUERY,
    "variables": {"texto": "tornillo 1/4"},
})
r.raise_for_status()
body = r.json()
if "errors" in body:
    raise RuntimeError(body["errors"][0]["message"])
print(body["data"]["productSuggestions"])

<?php
$ch = curl_init('https://mi-empresa.advantacloud.com/graphql');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('ADVANTA_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'query' => file_get_contents('buscar-articulos.graphql'),
        'variables' => ['texto' => 'tornillo 1/4'],
    ]),
]);
$respuesta = curl_exec($ch);
$estatus = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($respuesta === false || $estatus !== 200) {
    throw new RuntimeException("HTTP $estatus " . curl_error($ch));
}
$body = json_decode($respuesta, true);
if (!empty($body['errors'])) {
    throw new RuntimeException($body['errors'][0]['message']);
}
$resultado = $body['data']['productSuggestions'];

Respuesta 200 OK

{
  "data": {
    "productSuggestions": [
      {
        "id": "5521",
        "idpart": "TOR-0420",
        "name": "Tornillo hexagonal 1/4 x 2",
        "unit": {
          "id": "1",
          "code": "PZA"
        }
      },
      {
        "id": "5524",
        "idpart": "TOR-0425",
        "name": "Tornillo hexagonal 1/4 x 2 1/2",
        "unit": {
          "id": "1",
          "code": "PZA"
        }
      }
    ]
  }
}

Ver en el explorador

Argumentos

Argumento	Tipo	Descripción
Búsqueda
`query`String!	String!	Texto a buscar. Encuentra los artículos cuya clave contiene el texto, cuyo código de barras es exactamente el texto o cuya descripción contiene todas sus palabras, en cualquier orden y sin distinguir mayúsculas: `"tornillo 1/4"` encuentra «Tornillo hexagonal 1/4 x 2». Con el texto vacío llegan los primeros 50 artículos por clave. Obligatorio.
Filtros
`familyIds`[ID!]	[ID!]	Sólo los artículos de alguna de estas familias. Una lista vacía no devuelve artículos.
`onlyActive`Boolean	Boolean	`true`: sólo los artículos activos. Si lo omites o envías `false`, llegan también los inactivos y los obsoletos.

Lo que devuelve

[ProductSuggestion!]!

Campos principales de ProductSuggestion:

Campo	Tipo	Descripción
`id`ID!	ID!	Identificador del artículo; es el que se envía en `productId`.
`idpart`String	String	Clave del artículo.
`name`String	String	Descripción principal del artículo.
`unit`SuggestedUnit	SuggestedUnit	Unidad de medida del artículo.

Ver todos los campos de ProductSuggestion

Permisos

Llave API Integraciones

Selects y autocompletes GraphQL

La llave ve los registros de toda la empresa del subdominio.

Sin el permiso Sin error

La consulta responde sin error, pero la lista llega vacía.

Así lo conserva el API para las integraciones que ya lo usan: revisa los permisos de la llave si una lista llega vacía sin razón.

Errores

Código	Cuándo ocurre	Qué hacer
HTTP 401	Falta el header `Authorization` o la llave no existe en la empresa del subdominio. La respuesta no trae cuerpo.	Revisa la llave y el subdominio. No reintentes.
HTTP 422	Falla interna o dato rechazado al guardar. El cuerpo es `{"error": …}`, sin `data`.	Si no cambiaste nada, reintenta con espera exponencial.

Los errores de la consulta llegan con HTTP 200 en errors, con su código en extensions.code. Revisa siempre errors, no sólo el estatus HTTP. Errores y reintentos.

Relacionadas

Schema del 26 oct 2026 · Ver cambios¿Algo no cuadra? Repórtalo en ayuda.advanta.mx