Árbol del API · Clientes › customer

Detalle de un cliente

customer

Tipo

Query

Devuelve

CustomerDetail

Permiso de la llave

Cliente

Estable

Devuelve un cliente por su id, con su crédito y su saldo, sus lugares de entrega y contactos, sus órdenes de venta más recientes y sus facturas con saldo por cobrar.

Si la llave no tiene el permiso, la respuesta es customer: null sin error; un cliente que no existe responde NOT_FOUND. Así distingues una llave mal configurada de un id equivocado.

Las órdenes recientes (recentOrders) piden además «Ventas» en la llave y las facturas pendientes (pendingInvoices), «Facturación»; sin ellos, ese campo llega null y el resto del cliente llega completo. Las órdenes van de la más reciente a la más antigua y no incluyen cotizaciones de venta.

Para toda la historia del cliente, filtra por su id en customerId: sus órdenes de venta en ordersConnection, sus facturas en invoicesConnection y sus cobros en collectionsConnection.

customer(
  id: ID!
): CustomerDetail

# cliente.graphql
query Cliente($id: ID!) {
  customer(id: $id) {
    id
    code
    name
    rfc
    creditLimit
    creditCurrency
    balance
    overdueBalance
    availableCredit
    pendingInvoicesCount
    creditTerm { id name }
    priceStructure { id code name }
    addresses(first: 100) {
      nodes { id code street city state zip }
    }
    contacts { id name email principal }
    recentOrders(first: 3) {
      nodes { id folio status total }
    }
  }
}

Variables: {"id": "1215"}

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

import os, requests

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

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

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

Respuesta 200 OK

{
  "data": {
    "customer": {
      "id": "1215",
      "code": "C-0042",
      "name": "Ferretería Hermanos Garza",
      "rfc": "XAXX010101000",
      "creditLimit": "150000.00",
      "creditCurrency": "MXN",
      "balance": "48720.00",
      "overdueBalance": "12180.00",
      "availableCredit": "101280.00",
      "pendingInvoicesCount": 3,
      "creditTerm": {
        "id": "2",
        "name": "Crédito 30 días"
      },
      "priceStructure": {
        "id": "4",
        "code": "MAY",
        "name": "Mayoreo"
      },
      "addresses": {
        "nodes": [
          {
            "id": "93",
            "code": "MATRIZ",
            "street": "Av. Constitución",
            "city": "Monterrey",
            "state": "NLE",
            "zip": "64000"
          },
          {
            "id": "141",
            "code": "BOD-APO",
            "street": "Av. Industrias",
            "city": "Apodaca",
            "state": "NLE",
            "zip": "66600"
          }
        ]
      },
      "contacts": [
        {
          "id": "52",
          "name": "Jorge Garza",
          "email": "jorge@ferreteriagarza.example",
          "principal": true
        }
      ],
      "recentOrders": {
        "nodes": [
          {
            "id": "48190",
            "folio": "OV00509",
            "status": "CONFIRMED",
            "total": "18560.00"
          },
          {
            "id": "47955",
            "folio": "OV00471",
            "status": "SOLD",
            "total": "30160.00"
          },
          {
            "id": "47610",
            "folio": "OV00433",
            "status": "SOLD",
            "total": "12180.00"
          }
        ]
      }
    }
  }
}

Ver en el explorador

Argumentos

Argumento	Tipo	Descripción
`id`ID!	ID!	Identificador del cliente, el mismo `id` que llega en `customersConnection`, `customerSuggestions` o `Order.customer`. Obligatorio.

Lo que devuelve

CustomerDetail

Campos principales de CustomerDetail:

Campo	Tipo	Descripción
`id`ID!	ID!	Identificador del cliente; es el que se envía en `customerId`.
`code`String	String	Clave del cliente, p. ej. `C-0042`.
`name`String	String	Nombre del cliente.
`rfc`String	String	RFC del cliente.
`creditLimit`Money	Money	Límite de crédito, en la moneda de crédito (`creditCurrency`). Requiere «Cliente» en la llave; sin él llega `null`.
`creditCurrency`String	String	Clave SAT de la moneda de crédito, p. ej. `MXN`. El límite y los saldos están en esta moneda. Requiere «Cliente» en la llave; sin él llega `null`.
`balance`Money	Money	Saldo por cobrar: las parcialidades pendientes de sus facturas, vencidas y por vencer, menos los cobros que aún no se aplican a una factura. Es negativo si el cliente tiene saldo a favor. Requiere «Cliente» en la llave; sin él llega `null`.
`overdueBalance`Money	Money	Importe de las parcialidades ya vencidas, sin descontar los cobros por aplicar. Requiere «Cliente» en la llave; sin él llega `null`.
`availableCredit`Money	Money	Crédito disponible, `creditLimit` menos `balance`. Requiere «Cliente» en la llave; sin él llega `null`.
`pendingInvoicesCount`Int!	Int!	Número de facturas con saldo por cobrar, sin contar las facturas de anticipo. Requiere «Cliente» en la llave; sin él la petición responde HTTP 422.
`creditTerm`CreditTerm	CreditTerm	Término de crédito del cliente; es el que se propone en sus órdenes.
`priceStructure`PriceStructure	PriceStructure	Estructura de precios principal del cliente. Requiere «Cliente» en la llave; sin él llega `null`.
`auxPriceStructure`PriceStructure	PriceStructure	Estructura de precios auxiliar. Cuando el cliente tiene una, sus precios tienen prioridad sobre los de `priceStructure`. Requiere «Cliente» en la llave; sin él llega `null`.
`documentCurrency`Currency	Currency	Moneda de los documentos del cliente.
`addresses`CustomerAddressConnection!	CustomerAddressConnection!	Lugares de entrega del cliente, del modificado hace más tiempo al más reciente.20 por omisión, hasta 100 por página.
`contacts`[CustomerContact!]!	[CustomerContact!]!	Contactos del cliente, ordenados por nombre.
`recentOrders`OrderConnection	OrderConnection	Órdenes de venta del cliente, de la más reciente a la más antigua, sin cotizaciones de venta. Llegan 10 si no pides otro número con `first`. Requiere «Ventas» en la llave; sin él llega `null`.10 por omisión, hasta 100 por página.
`pendingInvoices`InvoiceConnection	InvoiceConnection	Facturas del cliente con saldo por cobrar, sin las facturas de anticipo. Con `search`, sólo las que tienen ese texto en el folio o en el UUID; si el texto aparece en el nombre o la clave del cliente, llegan todas. Requiere «Facturación» en la llave; sin él llega `null`.50 por omisión, hasta 100 por página.

Ver todos los campos de CustomerDetail

Permisos

Llave API Integraciones

Cliente

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 cliente con ese `id` en la empresa.	Revisa el `id`.
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