Árbol del API · Clientes › customersConnection

Lista de clientes

customersConnection

Tipo

Query

Devuelve

CustomerConnection

Permiso de la llave

Cliente

Página

20 por omisión · máx. 100

Estable

Lista los clientes de la empresa, del modificado hace más tiempo al más reciente. Busca por nombre, RFC, correo o clave, trae sólo los que tienen saldo por cobrar o los modificados desde un momento, y recorre el resultado por páginas con cursores.

Úsala para sincronizar tu catálogo de clientes: la primera vez recorre la lista completa; después pide sólo lo modificado con updatedAfter y el updatedAt más reciente que guardaste. Para traer un cliente con sus órdenes recientes y sus facturas pendientes usa customer(id:).

updatedAfter sigue los cambios de los datos del cliente. Su saldo, sus lugares de entrega y sus contactos pueden cambiar sin que cambie updatedAt: si los guardas, vuelve a pedirlos de vez en cuando.

Llegan todos los clientes de la empresa, también los inactivos. Los importes de crédito (creditLimit, balance, overdueBalance, availableCredit) están en la moneda de crédito del cliente, creditCurrency.

customersConnection(
  first: Int  after: String  search: String
  withPendingBalance: Boolean  updatedAfter: DateTime
): CustomerConnection

# clientes.graphql
query Clientes($desde: DateTime, $cursor: String) {
  customersConnection(first: 100, after: $cursor, updatedAfter: $desde) {
    nodes {
      id
      code
      name
      rfc
      email
      creditLimit
      creditCurrency
      balance
      priceStructure { id code }
      salesperson { id name }
      updatedAt
    }
    pageInfo { hasNextPage endCursor }
  }
}

Variables: {"desde": "2026-10-01T00:00:00-06:00", "cursor": null}

jq -n --rawfile q clientes.graphql \
  '{query: $q, variables: {"desde":"2026-10-01T00:00:00-06:00","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("clientes.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: { desde: "2026-10-01T00:00:00-06:00", 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.customersConnection);

import os, requests

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

cursor, nodos = None, []
while True:
    r = requests.post(URL, headers=HEADERS, timeout=30, json={
        "query": QUERY,
        "variables": {"desde": "2026-10-01T00:00:00-06:00", "cursor": cursor},
    })
    r.raise_for_status()
    body = r.json()
    if "errors" in body:
        raise RuntimeError(body["errors"][0]["message"])
    page = body["data"]["customersConnection"]
    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('clientes.graphql'),
        'variables' => ['desde' => '2026-10-01T00:00:00-06:00', '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']['customersConnection'];

Respuesta 200 OK · 2 de 100 nodos

{
  "data": {
    "customersConnection": {
      "nodes": [
        {
          "id": "1302",
          "code": "C-0057",
          "name": "Materiales del Norte",
          "rfc": "XAXX010101000",
          "email": "compras@materialesdelnorte.example",
          "creditLimit": "80000.00",
          "creditCurrency": "MXN",
          "balance": "0.00",
          "priceStructure": {
            "id": "5",
            "code": "MEN"
          },
          "salesperson": {
            "id": "18",
            "name": "Laura Méndez"
          },
          "updatedAt": "2026-10-21T10:18:44.530211-06:00"
        },
        {
          "id": "1215",
          "code": "C-0042",
          "name": "Ferretería Hermanos Garza",
          "rfc": "XAXX010101000",
          "email": "pagos@ferreteriagarza.example",
          "creditLimit": "150000.00",
          "creditCurrency": "MXN",
          "balance": "48720.00",
          "priceStructure": {
            "id": "4",
            "code": "MAY"
          },
          "salesperson": {
            "id": "18",
            "name": "Laura Méndez"
          },
          "updatedAt": "2026-10-22T16:05:31.412907-06:00"
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "WzEsInh2Y21zIiwidXBkYXRlZF9hdCIsZmFsc2UsIjIwMjYtMTAtMjJUMTY6MDU6MzEuNDEyOTA3LTA2OjAwIiwxMjE1XQ=="
      }
    }
  }
}

Ver en el explorador

Argumentos

Argumento	Tipo	Descripción
Paginación
`first`Int	Int	Cuántos clientes 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 clientes que siguen.
Filtros
`search`String	String	Clientes cuyo nombre, RFC, correo o clave empieza con el texto, sin distinguir mayúsculas: `"ferre"` encuentra «Ferretería Hermanos Garza», pero `"garza"` no. Para buscar en cualquier parte del nombre usa `customerSuggestions`.
`withPendingBalance`Boolean	Boolean	`true`: sólo los clientes con al menos una factura con saldo por cobrar, sin contar las facturas de anticipo. Esas facturas están en `invoicesConnection` con `customerId` y `onlyPending: true`.
`updatedAfter`DateTime	DateTime	Sólo los clientes modificados después de este momento (ISO 8601 con desfase horario). Para sincronizar, envía el `updatedAt` más reciente que ya guardaste.

Lo que devuelve

CustomerConnection

nodes[Customer]Los clientes de esta página. La forma más corta de leerlos.

edges[CustomerEdge]Los mismos clientes, 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 Customer

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.
`email`String	String	Correo electrónico.
`phone`String	String	Teléfono.
`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`.
`priceStructure`PriceStructure	PriceStructure	Estructura de precios principal del cliente. Requiere «Cliente» en la llave; sin él llega `null`.
`salesperson`Employee	Employee	Vendedor asignado al 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.
`updatedAt`DateTime	DateTime	Fecha y hora de la última modificación del cliente; úsala con `customersConnection(updatedAfter:)`.

Ver todos los campos de Customer

Paginación

first · after

Pide hasta 100 clientes 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 clientes entre páginas. Más sobre paginación.

Si un cliente cambia mientras recorres la lista, pasa al final y te llega otra vez con sus datos nuevos: guarda por id. Los lugares de entrega de cada cliente (addresses) son otra conexión con su propio límite de 100.

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.
`VALIDATION`	El cursor de `after` no tiene el formato de esta lista, o `first` es negativo.	Usa el `endCursor` tal como llegó y con los mismos argumentos; si lo perdiste, reinicia sin `after`.
`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