Árbol del API · Productos y precios › productsConnection

Lista de artículos

productsConnection

Tipo

Query

Devuelve

ProductConnection!

Permiso de la llave

Articulos

Página

20 por omisión · máx. 100

Estable

Lista los artículos de la empresa, del modificado hace más tiempo al más reciente. Busca por clave, descripción o código de barras, filtra por familia y trae el precio de cada artículo para un cliente o una estructura de precios.

Úsala para sincronizar tu catálogo de artículos: la primera vez recorre la lista completa; después pide sólo lo modificado con updatedAfter. Un artículo que se desactiva deja de llegar, también con updatedAfter: para detectar esas bajas, recorre la lista completa de vez en cuando y compara.

Un cambio de precio no cambia el updatedAt del artículo. priceListEntriesConnection sigue los cambios de los precios de cada lista, pero el precio calculado también depende de la vigencia de las listas y de los precios por rango: vuelve a pedir price de vez en cuando.

price llega sólo si envías customerId o priceStructureId y la llave tiene además «Cliente»; si no, llega null. Es el precio de lista en la unidad del artículo, antes de descuentos e impuestos. Si la estructura no tiene listas vigentes en esa moneda, llega en "0.00".

productsConnection(
  first: Int  after: String  search: String
  familyId: ID  onlyActive: Boolean = true
  updatedAfter: DateTime  customerId: ID
  priceStructureId: ID  currencyId: ID
): ProductConnection!

# articulos.graphql
query Articulos($cliente: ID!, $moneda: ID!, $cursor: String) {
  productsConnection(
    first: 100
    after: $cursor
    customerId: $cliente
    currencyId: $moneda
  ) {
    nodes {
      id
      idpart
      name
      unit { code }
      family { code name }
      barcode
      price { amount currency validUntil }
      updatedAt
    }
    pageInfo { hasNextPage endCursor }
  }
}

Variables: {"cliente": "1215", "moneda": "1", "cursor": null}

jq -n --rawfile q articulos.graphql \
  '{query: $q, variables: {"cliente":"1215","moneda":"1","cursor":null}}' |
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("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: { cliente: "1215", moneda: "1", cursor: null },
  }),
});
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.productsConnection);

import os, requests

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

cursor, nodos = None, []
while True:
    r = requests.post(URL, headers=HEADERS, timeout=30, json={
        "query": QUERY,
        "variables": {"cliente": "1215", "moneda": "1", "cursor": cursor},
    })
    r.raise_for_status()
    body = r.json()
    if "errors" in body:
        raise RuntimeError(body["errors"][0]["message"])
    page = body["data"]["productsConnection"]
    nodos += page["nodes"]
    if not page["pageInfo"]["hasNextPage"]:
        break
    cursor = page["pageInfo"]["endCursor"]

<?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('articulos.graphql'),
        'variables' => ['cliente' => '1215', 'moneda' => '1', 'cursor' => null],
    ]),
]);
$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']['productsConnection'];

Respuesta 200 OK · 2 de 100 nodos

{
  "data": {
    "productsConnection": {
      "nodes": [
        {
          "id": "5521",
          "idpart": "TOR-0420",
          "name": "Tornillo hexagonal 1/4 x 2",
          "unit": {
            "code": "PZA"
          },
          "family": {
            "code": "FIJ",
            "name": "Fijación"
          },
          "barcode": "7501234500421",
          "price": {
            "amount": "2.50",
            "currency": "MXN",
            "validUntil": "2026-12-31T23:59:59.000000-06:00"
          },
          "updatedAt": "2026-10-18T13:02:57.640218-06:00"
        },
        {
          "id": "5530",
          "idpart": "TUE-0420",
          "name": "Tuerca hexagonal 1/4",
          "unit": {
            "code": "PZA"
          },
          "family": {
            "code": "FIJ",
            "name": "Fijación"
          },
          "barcode": "7501234500438",
          "price": {
            "amount": "1.00",
            "currency": "MXN",
            "validUntil": "2026-12-31T23:59:59.000000-06:00"
          },
          "updatedAt": "2026-10-20T09:14:02.118340-06:00"
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "WzEsInhpcG1zIiwidXBkYXRlZF9hdCIsZmFsc2UsIjIwMjYtMTAtMjBUMDk6MTQ6MDIuMTE4MzQwLTA2OjAwIiw1NTMwXQ=="
      }
    }
  }
}

Ver en el explorador

Argumentos

Argumento	Tipo	Descripción
Paginación
`first`Int	Int	Cuántos artículos devolver desde el inicio o desde `after`. Sin `first` llegan 20; si pides más de 100 recibes 100.
`after`String	String	Cursor de la página anterior (`pageInfo.endCursor`). Devuelve los artículos que siguen.
Filtros
`search`String	String	Artículos cuya clave, descripción o código de barras empieza con el texto, sin distinguir mayúsculas: `"tor"` encuentra `TOR-0420`. Para buscar palabras en cualquier parte de la descripción usa `productSuggestions`.
`familyId`ID	ID	Sólo los artículos de esta familia (`Product.family.id`).
`onlyActive`Boolean	Boolean	Por omisión llegan sólo los artículos activos. Con `false` llegan también los inactivos y los obsoletos. Por omisión: `true`
`updatedAfter`DateTime	DateTime	Sólo los artículos modificados después de este momento (ISO 8601 con desfase horario). Para sincronizar, envía el `updatedAt` más reciente que ya guardaste.
Precio
`customerId`ID	ID	Calcula `price` con la estructura de precios de este cliente: la auxiliar si tiene una (y la principal para los artículos que no tienen precio en la auxiliar); si no, la principal.
`priceStructureId`ID	ID	Calcula `price` con esta estructura de precios. Con `customerId` no hace falta; si envías los dos, ésta debe ser la principal o la auxiliar del cliente, y el precio sale de la del cliente.
`currencyId`ID	ID	Moneda del precio: sólo cuentan las listas de precios vigentes en esa moneda. Sin `currencyId` se usa la moneda de documentos del cliente o, sin cliente, la primera moneda registrada en la empresa. Envíala siempre.

Lo que devuelve

ProductConnection!

nodes[Product]Los artículos de esta página. La forma más corta de leerlos.

edges[ProductEdge]Los mismos artículos, cada uno con su cursor.

pageInfoPageInfo!Dónde estás en la lista.

hasNextPageBoolean!Hay más elementos después de esta página.

endCursorStringCursor del último elemento; pásalo en after para pedir la página siguiente.

hasPreviousPageBoolean!true si pediste esta página con after, es decir, si no es la primera.

startCursorStringCursor del primer elemento de esta página.

Campos principales de Product

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, p. ej. `TOR-0420`.
`name`String	String	Descripción principal del artículo.
`description`String	String	Descripción adicional, en una o dos líneas separadas por un salto de línea.
`unit`Unit	Unit	Unidad de medida del artículo; sus precios y cantidades están en esta unidad.
`family`ProductFamily	ProductFamily	Familia del artículo. Si pertenece a varias, llega sólo una.
`barcode`String	String	Código de barras; si tiene dos, el principal.
`imageUrl`String	String	Liga a la imagen del artículo. Está firmada y vence a los 7 días; `null` si no tiene imagen.
`price`ProductPrice	ProductPrice	Precio de lista en la unidad del artículo, antes de descuentos e impuestos. Llega sólo en `product` y `productsConnection` cuando envías `customerId` o `priceStructureId`; en los demás casos, como en las partidas de una orden, llega `null`. Requiere «Cliente» en la llave; sin él llega `null`.
`inventoryControl`InventoryControl	InventoryControl	Cómo controla el inventario el artículo, de los lotes y series al redondeo de cantidades.
`updatedAt`DateTime	DateTime	Fecha y hora de la última modificación del artículo; úsala con `productsConnection(updatedAfter:)`. Un cambio de precio no la mueve.

Ver todos los campos de Product

Paginación

first · after

Pide hasta 100 artículos por página junto con pageInfo. Repite la misma consulta pasando endCursor en after mientras hasNextPage sea true. El orden es estable: no se saltan artículos entre páginas. Más sobre paginación.

Si un artículo cambia mientras recorres la lista, pasa al final y te llega otra vez con sus datos nuevos: guarda por id.

Permisos

Llave API Integraciones

Articulos

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

Sin el permiso Sin error

La consulta responde sin error, pero nodes llega vacío y hasNextPage es false.

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.
`VALIDATION`	`priceStructureId` no es la estructura principal ni la auxiliar del cliente de `customerId`; o el cursor de `after` no tiene el formato de esta lista, o `first` es negativo.	Revisa la estructura de precios; usa el `endCursor` tal como llegó y con los mismos argumentos.
`NOT_FOUND`	El cliente de `customerId` o la moneda de `currencyId` no existe. Si pides `price`, también cuando la estructura de `priceStructureId` no existe.	Revisa los identificadores.
`argumentLiteralsIncompatible`	Un argumento escrito en la consulta no tiene el tipo esperado, como un `updatedAfter` que no es ISO 8601. Si el valor llega en una variable, el error trae `extensions.problems` y puede no traer `code`.	Corrige la consulta; reintentar no ayuda.
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