listCustomers()

Busca clientes de la cuenta con un filtro de texto y paginación por offset.

Permiso: customer:read

listCustomers(
  input?: CustomerListQuery,
  options?: RequestOptions
): Promise<CustomerRecord[]>

Referencia HTTP: GET /customers

• Devuelve un arreglo, sin meta.pagination ni hasMore. El límite del servidor es 50 por defecto, con máximo de 100. Para recorrer páginas, aumenta offset y termina cuando recibas menos elementos que limit; consulta la guía de paginación del SDK.

Parámetros

Argumento	Tipo	Obligatorio	Uso
input	CustomerListQuery	No	Se puede omitir; el valor predeterminado es {}.
options	RequestOptions	No	signal e idempotencyKey; consulta las opciones por solicitud.

Opciones por solicitud: signal e idempotencyKey.

Los campos siguientes corresponden a input en TypeScript. Un campo opcional se puede omitir; null solo se admite cuando aparece en su tipo. Las validaciones de negocio se ejecutan en el servidor.

Campo	Tipo	Obligatorio	Descripción
query	string	No	Texto de búsqueda. No es un identificador exacto ni un cursor.Mínimo 1 carácter. Máximo 120 caracteres
limit	number (entero)	No	Cantidad máxima de elementos por página. El servidor usa 50 si se omite.Mínimo: 1. Máximo: 100
offset	number (entero)	No	Cantidad de elementos que se saltan. El servidor usa 0 si se omite.Mínimo: 0. Máximo: 1000000

Ejemplo

Usa el cliente factucat de Instala y conecta. Los IDs y datos fiscales de este ejemplo son ilustrativos: reemplázalos por los registros de tu cuenta y ambiente.

const resultado = await factucat.listCustomers(
  {
    "query": "AAA010101AAA",
    "limit": 50,
    "offset": 0
  },
)
console.log(resultado)

Respuesta

Resuelve una Promise<CustomerRecord[]>. El valor recibido es directamente data, sin el envoltorio HTTP ni sus metadatos.

Elemento del arreglo

Campo	Tipo	Obligatorio	Descripción
id	string	Sí	ID de FactuCat del recurso. No es el UUID fiscal.Formato: uuid
userId	string	Sí	ID de la cuenta propietaria del recurso.Mínimo 1 carácter
legalName	string	Sí	Nombre o razón social del receptor.
rfc	string	Sí	RFC del receptor.
postalCode	string	Sí	Código postal fiscal, como cadena de cinco dígitos.
taxRegime	string	Sí	Clave del régimen fiscal del receptor.
preferredCfdiUse	string | null	No	Uso de CFDI preferido del cliente (clave SAT, por ejemplo G03). Opcional.
fiscalResidence	string	No	Clave del país de residencia fiscal, cuando aplica.
taxId	string	No	Identificación tributaria extranjera, cuando aplica.
email	string	No	Correo del cliente.Formato: email
whatsappPhone	string	No	Teléfono de WhatsApp del cliente.
sendInvoices	boolean	Sí	Preferencia de entrega de comprobantes al cliente; las opciones del timbrado también controlan los envíos.
invoiceLanguage	"es" | "en"	Sí	Idioma preferido del cliente para la factura.
currency	"MXN" | "USD" | "EUR"	Sí	Moneda del cliente o del comprobante.
createdAt	string	Sí	Fecha y hora de creación en formato ISO 8601; se devuelve como string.Formato: date-time
updatedAt	string	Sí	Fecha y hora de última actualización en formato ISO 8601.Formato: date-time

Ejemplo de respuesta

[
  {
    "id": "10112233-4455-4677-8899-aabbccddeeff",
    "userId": "usuario_ejemplo",
    "legalName": "EMPRESA DE EJEMPLO",
    "rfc": "AAA010101AAA",
    "postalCode": "06000",
    "taxRegime": "601",
    "sendInvoices": false,
    "invoiceLanguage": "es",
    "currency": "MXN",
    "createdAt": "2026-09-08T12:00:00Z",
    "updatedAt": "2026-09-08T12:00:00Z"
  }
]

Las fechas se entregan como cadenas ISO 8601. Un campo opcional puede estar ausente. Tipos, paginación y archivos.

La promesa se rechaza si la API devuelve un error, falla la conexión o los datos no cumplen el contrato. Cómo manejar los errores.