Árbol del API · Clientes › customerSuggestions

Buscar clientes

customerSuggestions

Tipo

Query

Devuelve

[CustomerSuggestion!]!

Permiso de la llave

Selects y autocompletes GraphQL

Estable

Busca clientes activos por nombre, clave, RFC o correo y devuelve hasta 20, ordenados por nombre.

Úsala para un buscador de clientes mientras el usuario escribe. A diferencia de customersConnection, busca el texto en cualquier parte, sólo trae clientes activos y no tiene páginas: si el cliente no está entre los 20 primeros, pide un texto más preciso.

Con el id elegido pide el detalle con customer(id:) o los valores iniciales de una orden con orderDefaults.

customerSuggestions(
  query: String!
): [CustomerSuggestion!]!

# buscar-clientes.graphql
query BuscarClientes($texto: String!) {
  customerSuggestions(query: $texto) {
    id
    code
    name
    rfc
    label
  }
}

Variables: {"texto": "garza"}

jq -n --rawfile q buscar-clientes.graphql \
  '{query: $q, variables: {"texto":"garza"}}' |
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-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: { texto: "garza" },
  }),
});
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.customerSuggestions);

import os, requests

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

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

<?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-clientes.graphql'),
        'variables' => ['texto' => 'garza'],
    ]),
]);
$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']['customerSuggestions'];

Respuesta 200 OK

{
  "data": {
    "customerSuggestions": [
      {
        "id": "1215",
        "code": "C-0042",
        "name": "Ferretería Hermanos Garza",
        "rfc": "XAXX010101000",
        "label": "C-0042 | Ferretería Hermanos Garza"
      },
      {
        "id": "1376",
        "code": "C-0063",
        "name": "Garza Construcciones",
        "rfc": "XAXX010101000",
        "label": "C-0063 | Garza Construcciones"
      }
    ]
  }
}

Ver en el explorador

Argumentos

Argumento	Tipo	Descripción
`query`String!	String!	Texto a buscar. Basta con que aparezca en cualquier parte del nombre, la clave, el RFC o el correo, sin distinguir mayúsculas: `"garza"` encuentra «Ferretería Hermanos Garza». Un número también encuentra al cliente con ese `id`. Con el texto vacío llegan los primeros 20 clientes activos por nombre. Obligatorio.

Lo que devuelve

[CustomerSuggestion!]!

Campos principales de CustomerSuggestion:

Campo	Tipo	Descripción
`id`ID!	ID!	Identificador del cliente; es el que se envía en `customerId`.
`code`String	String	Clave del cliente.
`name`String	String	Nombre del cliente.
`rfc`String	String	RFC del cliente.
`label`String!	String!	Clave y nombre del cliente para mostrar, p. ej. `C-0042 \| Ferretería Hermanos Garza`.

Ver todos los campos de CustomerSuggestion

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