Árbol del API · Productos y precios › product

Detalle de un artículo

product

Tipo

Query

Devuelve

Product

Permiso de la llave

Articulos

Estable

Devuelve un artículo por su id, con su unidad, su familia y su control de inventario, y su precio para un cliente o una estructura de precios.

Si la llave no tiene el permiso, la respuesta es product: null sin error; un artículo que no existe responde NOT_FOUND. Llegan también los artículos inactivos y obsoletos.

price llega sólo si envías customerId o priceStructureId y la llave tiene además «Cliente». Es el precio de lista en la unidad del artículo, antes de descuentos e impuestos. Para el precio exacto de una partida, con descuentos e impuestos, cotiza la orden con quoteOrder.

product(
  id: ID!  customerId: ID  priceStructureId: ID
  currencyId: ID
): Product

# articulo.graphql
query Articulo($id: ID!, $cliente: ID!, $moneda: ID!) {
  product(id: $id, customerId: $cliente, currencyId: $moneda) {
    id
    idpart
    name
    description
    unit { id code name }
    inventoryControl { lot serial quantityDecimals }
    price {
      amount
      currency
      listId
      validUntil
      offer { amount validUntil }
    }
  }
}

Variables: {"id": "5521", "cliente": "1215", "moneda": "1"}

jq -n --rawfile q articulo.graphql \
  '{query: $q, variables: {"id":"5521","cliente":"1215","moneda":"1"}}' |
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("articulo.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: { id: "5521", cliente: "1215", moneda: "1" },
  }),
});
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.product);

import os, requests

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

r = requests.post(URL, headers=HEADERS, timeout=30, json={
    "query": QUERY,
    "variables": {"id": "5521", "cliente": "1215", "moneda": "1"},
})
r.raise_for_status()
body = r.json()
if "errors" in body:
    raise RuntimeError(body["errors"][0]["message"])
print(body["data"]["product"])

<?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('articulo.graphql'),
        'variables' => ['id' => '5521', 'cliente' => '1215', 'moneda' => '1'],
    ]),
]);
$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']['product'];

Respuesta 200 OK

{
  "data": {
    "product": {
      "id": "5521",
      "idpart": "TOR-0420",
      "name": "Tornillo hexagonal 1/4 x 2",
      "description": "Acero galvanizado grado 5\nCuerda estándar",
      "unit": {
        "id": "1",
        "code": "PZA",
        "name": "Pieza"
      },
      "inventoryControl": {
        "lot": false,
        "serial": false,
        "quantityDecimals": 0
      },
      "price": {
        "amount": "2.50",
        "currency": "MXN",
        "listId": "12",
        "validUntil": "2026-12-31T23:59:59.000000-06:00",
        "offer": {
          "amount": "2.20",
          "validUntil": "2026-11-15T23:59:59.000000-06:00"
        }
      }
    }
  }
}

Ver en el explorador

Argumentos

Argumento	Tipo	Descripción
Identificación
`id`ID!	ID!	Identificador del artículo, el mismo `id` que llega en `productsConnection`, `productSuggestions` o en las partidas de una orden. Obligatorio.
Precio
`customerId`ID	ID	Calcula `price` con la estructura de precios de este cliente: la auxiliar si tiene una y el artículo tiene precio en ella; 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

Product

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

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 el resultado llega null.

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.
`NOT_FOUND`	No hay un artículo con ese `id`, o no existe el cliente de `customerId`, la moneda de `currencyId` o, si pides `price`, la estructura de `priceStructureId`.	Revisa los identificadores.
`VALIDATION`	`priceStructureId` no es la estructura principal ni la auxiliar del cliente de `customerId`.	Omite `priceStructureId` o usa una estructura del cliente.
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