listInvoices()

Lista documentos de la cuenta y permite filtrar por texto y estado. Devuelve resúmenes, sin conceptos.

Permiso: invoice:read

listInvoices(
  input?: InvoiceListQuery,
  options?: RequestOptions
): Promise<InvoiceListItem[]>

Referencia HTTP: GET /invoices

• 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	InvoiceListQuery	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
status	"draft" | "issued" | "error" | "cancelled"	No	Estado del recurso o resultado de la cancelación; consulta las notas del método.
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.listInvoices(
  {
    "status": "issued",
    "limit": 50,
    "offset": 0
  },
)
console.log(resultado)

Respuesta

Resuelve una Promise<InvoiceListItem[]>. 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
folio	string	Sí	Folio del documento.
status	"draft" | "issued" | "error" | "cancelled"	Sí	Estado del recurso o resultado de la cancelación; consulta las notas del método.
receiverLegalName	string	Sí	Nombre fiscal del receptor guardado en el documento.
receiverEmail	string	No	Correo del receptor guardado en el documento.Formato: email
currency	"MXN" | "USD" | "EUR"	Sí	Moneda del cliente o del comprobante.
total	number	Sí	Importe total del documento. En cancelaciones externas se envía como string.
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
issuedAt	string	No	Fecha y hora de emisión, cuando está disponible.Formato: date-time
errorMessage	string	No	Mensaje asociado a un error del documento, cuando está disponible.

Ejemplo de respuesta

[
  {
    "id": "00112233-4455-4677-8899-aabbccddeeff",
    "folio": "A-1001",
    "receiverLegalName": "EMPRESA DE EJEMPLO",
    "currency": "MXN",
    "total": 1160,
    "createdAt": "2026-09-08T12:00:00Z",
    "updatedAt": "2026-09-08T12:00:00Z",
    "status": "issued",
    "issuedAt": "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.