# Listar facturas

`GET https://api.fiscalisto.com/v1/invoices`

Las más recientes primero.

## Parámetros

| Nombre | Dónde | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `limit` | consulta |  | Cuántos por página, de 1 a 100. Por omisión 10. |
| `starting_after` | consulta |  | El id del último de la página anterior, para la siguiente. |
| `issuer` | consulta |  | El emisor (iss_…). Puede omitirse si la llave o la cuenta tienen uno solo. |
| `status` | consulta |  | valid, pending, canceled, rejected o processing. |
| `type` | consulta |  | I, E, P, T o N. |
| `customer` | consulta |  | RFC del cliente o su id (cus_…). |
| `payment_status` | consulta |  | Facturas de ingreso por lo que deben: unpaid, partial, open (unpaid o partial) o paid. |
| `created_gte` | consulta |  | Creadas desde, en ISO 8601. Un día solo (2026-10-01) cuenta desde su inicio en hora de la Ciudad de México. |
| `created_lte` | consulta |  | Creadas hasta, en ISO 8601. Un día solo (2026-10-31) incluye el día completo en hora de la Ciudad de México. |

## Con el SDK de TypeScript

```ts
import { Fiscalisto } from "fiscalisto";

// La llave viene de FISCALISTO_API_KEY.
const fiscalisto = new Fiscalisto();

for await (const item of fiscalisto.invoices.list()) {
  console.log(item.id);
}
```

## Con el SDK de Python

```python
from fiscalisto import Fiscalisto

# La llave viene de FISCALISTO_API_KEY.
fiscalisto = Fiscalisto()

for item in fiscalisto.invoices.list():
    print(item["id"])
```

## Con el SDK de PHP

```php
<?php

use Fiscalisto\Fiscalisto;

// La llave viene de FISCALISTO_API_KEY.
$fiscalisto = new Fiscalisto();

foreach ($fiscalisto->invoices->list() as $item) {
    echo $item['id'], "\n";
}
```

## Con el SDK de .NET

```csharp
using Fiscalisto;

// La llave viene de FISCALISTO_API_KEY.
var fiscalisto = new FiscalistoClient();

await foreach (var item in fiscalisto.Invoices.ListAutoPagingAsync())
    Console.WriteLine(item.Id);
```

## Con el SDK de Go

```go
package main

import (
	"context"
	"fmt"
	"log"

	fiscalisto "fiscalisto.com/go"
)

func main() {
	// La llave viene de FISCALISTO_API_KEY.
	client, err := fiscalisto.NewClient("")
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.Background()

	for item, err := range client.Invoices.ListAutoPaging(ctx, nil) {
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(item.ID)
	}
}
```

## Con el SDK de Java

```java
import com.fiscalisto.FiscalistoClient;

// La llave viene de FISCALISTO_API_KEY.
var fiscalisto = new FiscalistoClient();

for (var item : fiscalisto.invoices().listAutoPaging()) {
    System.out.println(item.getId());
}
```

## Respuesta 200

Correcto.

Un objeto `InvoiceList`:

| Campo | Tipo | Siempre viene | Descripción |
| --- | --- | --- | --- |
| `object` | `"list"` | sí | Qué tipo de objeto es («invoice», «customer»…). |
| `data` | arreglo de objeto | sí | Los objetos de esta página. |
| `data[].id` | string | sí | Identificador del objeto, con su prefijo (iss_, inv_, ret_, cus_, prd_, emp_, bat_, brn_, whs_, stm_, adj_, evt_, whe_). |
| `data[].livemode` | boolean | sí | true en producción (llaves fk_live_), false en pruebas (fk_test_). Lo de pruebas no vale ante el SAT. |
| `data[].object` | `"invoice"` | sí | Qué tipo de objeto es («invoice», «customer»…). |
| `data[].issuer` | string | sí | El emisor (iss_…). |
| `data[].branch` | string o null | sí | La sucursal (brn_…) desde donde se timbró, o null (el domicilio fiscal del emisor). Sus pagos y notas de crédito la siguen. |
| `data[].type` | `I`, `E`, `P`, `T`, `N` | sí | Tipo de comprobante (TipoDeComprobante): I ingreso, E egreso, P pago, T traslado, N nómina. |
| `data[].status` | `processing`, `pending`, `valid`, `rejected`, `canceled` | sí | processing: el PAC no ha contestado (se resuelve sola; escuche invoice.stamped). valid: timbrada. pending: timbrada con una cancelación en espera del cliente. rejected: el SAT o el PAC no la aceptaron (ver error). canceled: cancelada. |
| `data[].uuid` | string o null | sí | Folio fiscal que asigna el SAT (UUID del Timbre Fiscal Digital), en mayúsculas. |
| `data[].series` | string o null | sí | Serie (Serie), hasta 25 caracteres. Cada serie lleva sus propios folios. |
| `data[].folio` | string o null | sí | Folio (Folio). Fiscalisto asigna el siguiente de la serie; mande uno solo si debe ser ese. |
| `data[].date` | string o null | sí | Fecha de emisión (Fecha), hora de la Ciudad de México. |
| `data[].customer` | objeto | sí | Cliente (Receptor): el id de uno de su catálogo (cus_…) o sus datos en un objeto. |
| `data[].customer.tax_id` | string o null | sí | RFC (Rfc), 12 caracteres una persona moral y 13 una física. |
| `data[].customer.legal_name` | string o null | sí | Nombre o razón social tal como está en la constancia de situación fiscal, sin el régimen de capital (sin «S.A. de C.V.»). |
| `data[].customer.tax_system` | string |  | Régimen fiscal (RegimenFiscal), clave de c_RegimenFiscal: 601, 612, 626… |
| `data[].customer.zip` | string |  | Código postal del domicilio fiscal del cliente (DomicilioFiscalReceptor), 5 dígitos. |
| `data[].customer.foreign` | objeto |  | Si es extranjero: su país de residencia (ResidenciaFiscal, c_Pais) y su número de registro tributario (NumRegIdTrib), con el RFC genérico XEXX010101000. |
| `data[].use` | string o null | sí | Uso del CFDI (UsoCFDI), clave de c_UsoCFDI. Por omisión G03, o S01 con régimen 616. |
| `data[].payment_form` | string o null | sí | Forma de pago (FormaPago), clave de c_FormaPago: 01 efectivo, 03 transferencia, 04 tarjeta de crédito, 28 débito, 99 por definir… Obligatoria con PUE; con PPD es 99. |
| `data[].payment_method` | string o null | sí | Método de pago (MetodoPago): PUE (una sola exhibición, por omisión) o PPD (en parcialidades o diferido, se cobra con complementos de pago). |
| `data[].currency` | string | sí | Moneda, clave ISO 4217 de c_Moneda (MXN, USD, EUR…). Por omisión MXN. |
| `data[].exchange_rate` | number o null | sí | Tipo de cambio a pesos (TipoCambio). Obligatorio si la moneda no es MXN; use el del DOF del día anterior. |
| `data[].items` | arreglo de objeto | sí | Conceptos (Conceptos), al menos uno. |
| `data[].subtotal` | number o null | sí | Suma de los importes antes de impuestos y descuentos (SubTotal). |
| `data[].discount` | number o null | sí | Descuento (Descuento). |
| `data[].taxes` | objeto o null | sí | Impuestos del comprobante, por tipo. |
| `data[].taxes.iva` | number o null | sí | IVA trasladado. |
| `data[].taxes.ieps` | number o null | sí | IEPS trasladado. |
| `data[].taxes.iva_withheld` | number o null | sí | IVA retenido. |
| `data[].taxes.isr_withheld` | number o null | sí | ISR retenido. |
| `data[].taxes.local_transferred` | number o null | sí | Impuestos locales trasladados. |
| `data[].taxes.local_withheld` | number o null | sí | Impuestos locales retenidos. |
| `data[].total` | number o null | sí | Total en la moneda del comprobante (Total). |
| `data[].payment_status` | `paid`, `partial`, `unpaid` o null | sí | Si ya se cobró (Cuentas por cobrar): paid, partial (complementos de pago o notas de crédito por una parte) o unpaid. Una PUE está paid, salvo con paid_later hasta POST /v1/invoices/{id}/mark_paid. null si no es de ingreso o no está vigente. |
| `data[].amount_due` | number o null | sí | Lo que falta por cobrar, en su moneda, o null. |
| `data[].amount_paid` | number o null | sí | Lo cobrado: complementos de pago y notas de crédito vigentes, o todo si es PUE pagada. null si no aplica. |
| `data[].related` | objeto o null | sí | CFDI relacionados (CfdiRelacionados): tipo de relación de c_TipoRelacion y los UUID. |
| `data[].payment` | objeto o null |  | Solo en un complemento de pago (type P). |
| `data[].payment.date` | string o null | sí | Fecha del pago (FechaPago). |
| `data[].payment.payment_form` | string o null | sí | Forma de pago (FormaPago), clave de c_FormaPago: 01 efectivo, 03 transferencia, 04 tarjeta de crédito, 28 débito, 99 por definir… Obligatoria con PUE; con PPD es 99. |
| `data[].payment.currency` | string | sí | Moneda del pago (MonedaP). |
| `data[].payment.exchange_rate` | number o null | sí | Tipo de cambio a pesos (TipoCambio). Obligatorio si la moneda no es MXN; use el del DOF del día anterior. |
| `data[].payment.amount` | number | sí | Monto del pago (Monto). |
| `data[].payment.operation_number` | string o null | sí | Número de operación del pago (NumOperacion), como el rastreo SPEI. |
| `data[].payment.documents` | arreglo de objeto | sí | Las facturas que paga (DoctoRelacionado). |
| `data[].payment.documents[].uuid` | string | sí | Folio fiscal que asigna el SAT (UUID del Timbre Fiscal Digital), en mayúsculas. |
| `data[].payment.documents[].series` | string o null | sí | Serie de la factura pagada. |
| `data[].payment.documents[].folio` | string o null | sí | Folio de la factura pagada. |
| `data[].payment.documents[].currency` | string | sí | Moneda de la factura pagada (MonedaDR). |
| `data[].payment.documents[].partiality` | integer | sí | Número de parcialidad (NumParcialidad). (de -9007199254740991 a 9007199254740991) |
| `data[].payment.documents[].previous_balance` | number | sí | Saldo anterior de la factura (ImpSaldoAnt). |
| `data[].payment.documents[].amount` | number | sí | Lo que se paga de esa factura (ImpPagado), en la moneda de la factura. |
| `data[].payment.documents[].remaining` | number | sí | Saldo insoluto después de este pago (ImpSaldoInsoluto). |
| `data[].payroll` | objeto |  | Solo en un recibo de nómina (type N). |
| `data[].payroll.periodicity` | string | sí | Periodicidad del pago (PeriodicidadPago): 02 semanal, 03 catorcenal, 04 quincenal (por omisión), 05 mensual. |
| `data[].payroll.period` | objeto | sí | Periodo (Periodo): mes inicial, mes final y año. |
| `data[].payroll.period.start` | string | sí | Primer día del periodo (FechaInicialPago), AAAA-MM-DD. |
| `data[].payroll.period.end` | string | sí | Último día del periodo (FechaFinalPago), AAAA-MM-DD. |
| `data[].payroll.period.payment_date` | string | sí | Fecha de pago (FechaPago), AAAA-MM-DD. Por omisión el último día del periodo. |
| `data[].payroll.days` | number | sí | Días pagados (NumDiasPagados). Por omisión, todos los del periodo que le tocan. |
| `data[].payroll.employer` | objeto | sí | El patrón (Emisor del complemento): registro patronal y CURP si es persona física. |
| `data[].payroll.employer.employer_registration` | string o null | sí | Registro patronal ante el IMSS (RegistroPatronal), 11 caracteres. Necesario para timbrar nómina. |
| `data[].payroll.employer.curp` | string o null | sí | CURP, 18 caracteres. |
| `data[].payroll.employee` | objeto | sí | El empleado (emp_…). |
| `data[].payroll.employee.id` | string o null | sí | Identificador del objeto, con su prefijo (iss_, inv_, ret_, cus_, prd_, emp_, bat_, brn_, whs_, stm_, adj_, evt_, whe_). |
| `data[].payroll.employee.number` | string | sí | Número de empleado (NumEmpleado). |
| `data[].payroll.employee.curp` | string | sí | CURP, 18 caracteres. |
| `data[].payroll.employee.social_security_number` | string o null | sí | Número de seguridad social (NumSeguridadSocial), 11 dígitos. |
| `data[].payroll.employee.start_date` | string | sí | Fecha de inicio de la relación laboral (FechaInicioRelLaboral), AAAA-MM-DD. |
| `data[].payroll.employee.contract_type` | string | sí | Tipo de contrato (TipoContrato), c_TipoContrato. Por omisión 01, por tiempo indeterminado. |
| `data[].payroll.employee.unionized` | boolean | sí | true si es sindicalizado (Sindicalizado). |
| `data[].payroll.employee.workday_type` | string | sí | Tipo de jornada (TipoJornada), c_TipoJornada. Por omisión 01, diurna. |
| `data[].payroll.employee.regime_type` | string | sí | Tipo de régimen (TipoRegimen): 02 sueldos y salarios. |
| `data[].payroll.employee.department` | string o null |  | Departamento (Departamento). |
| `data[].payroll.employee.position` | string o null |  | Puesto (Puesto). |
| `data[].payroll.employee.risk_class` | string o null | sí | Clase de riesgo del puesto ante el IMSS (RiesgoPuesto), 1 a 5. Por omisión 1. |
| `data[].payroll.employee.contribution_base_salary` | number o null | sí | Salario base de cotización (SalarioBaseCotApor). |
| `data[].payroll.employee.integrated_daily_salary` | number o null | sí | Salario diario integrado (SalarioDiarioIntegrado): no menor al salario diario. |
| `data[].payroll.employee.state` | string | sí | Entidad federativa donde trabaja (ClaveEntFed): JAL, CMX, NLE… |
| `data[].payroll.perceptions` | arreglo de objeto | sí | Percepciones (Percepcion): sueldo y demás, gravado y exento. |
| `data[].payroll.perceptions[].type` | string | sí | Tipo de percepción (TipoPercepcion), c_TipoPercepcion: 001 sueldos… |
| `data[].payroll.perceptions[].key` | string | sí | Clave del patrón (Clave). |
| `data[].payroll.perceptions[].concept` | string | sí | Concepto (Concepto). |
| `data[].payroll.perceptions[].taxed` | number | sí | Importe gravado (ImporteGravado). |
| `data[].payroll.perceptions[].exempt` | number | sí | Importe exento (ImporteExento). |
| `data[].payroll.deductions` | arreglo de objeto | sí | Deducciones (Deduccion): ISR, cuotas IMSS y demás. |
| `data[].payroll.deductions[].type` | string | sí | Tipo de deducción (TipoDeduccion), c_TipoDeduccion: 001 IMSS, 002 ISR… |
| `data[].payroll.deductions[].key` | string | sí | Clave del patrón (Clave). |
| `data[].payroll.deductions[].concept` | string | sí | Concepto (Concepto). |
| `data[].payroll.deductions[].amount` | number | sí | Importe (Importe). |
| `data[].payroll.other_payments` | arreglo de objeto | sí | Otros pagos (OtroPago): subsidio para el empleo. |
| `data[].payroll.other_payments[].type` | string | sí | Tipo de otro pago (TipoOtroPago), c_TipoOtroPago: 002 subsidio para el empleo. |
| `data[].payroll.other_payments[].key` | string | sí | Clave del patrón (Clave). |
| `data[].payroll.other_payments[].concept` | string | sí | Concepto (Concepto). |
| `data[].payroll.other_payments[].amount` | number | sí | Importe pagado (Importe). |
| `data[].payroll.other_payments[].subsidy_caused` | number |  | Subsidio causado (SubsidioCausado). |
| `data[].payroll.other_payments[].subsidy_applied` | number |  | Del subsidio causado, el ISR que evitó (no va en el XML). |
| `data[].global` | objeto |  | Solo en una factura global. |
| `data[].cancellation` | objeto o null | sí | La cancelación, si se pidió: estado, motivo, sustituto y cuándo. |
| `data[].cancellation.status` | string o null | sí | pending (espera la respuesta del cliente), accepted (cancelada), rejected (el cliente la rechazó) o lapsed (venció; puede pedirla otra vez). |
| `data[].cancellation.motive` | string o null | sí | Motivo de cancelación (c_MotivoCancelacion): 01 con errores con relación (lleva substitution), 02 con errores sin relación (por omisión), 03 no se llevó a cabo, 04 solo en una factura global, cuando una venta incluida se facturó a nombre del cliente. |
| `data[].cancellation.substitution` | string o null | sí | El comprobante que sustituye a este (su id o su UUID), con el motivo 01. |
| `data[].cancellation.canceled_at` | string (date-time) o null | sí | Cuándo se canceló. |
| `data[].email` | objeto o null | sí | El envío por correo: a quién, con copia a quién y cuándo (null si no se ha enviado). |
| `data[].email.to` | string o null | sí | A quién (correos separados por comas). |
| `data[].email.cc` | string o null | sí | Con copia (correos separados por comas). |
| `data[].email.sent_at` | string (date-time) o null | sí | Cuándo se envió. |
| `data[].error` | objeto o null | sí | Por qué el SAT o el PAC no lo aceptaron: mensaje, código del SAT y texto original. |
| `data[].error.message` | string | sí | Qué pasó y cómo corregirlo, para una persona. |
| `data[].error.sat_code` | string o null | sí | Código del SAT o del PAC (CFDI40xxx). |
| `data[].error.raw` | string | sí | El texto original del PAC. |
| `data[].recurring_invoice` | string o null | sí | La factura recurrente (rin_…) que la timbró sola, o null si se timbró con una llamada. |
| `data[].created_at` | string (date-time) o null | sí | Cuándo se creó, ISO 8601 con la hora de la Ciudad de México (-06:00). |
| `data[].metadata` | objeto | sí | Sus propios datos: hasta 50 llaves de 40 caracteres con valores de texto de hasta 500. No van al CFDI; vuelven en el objeto y en los webhooks. |
| `data[].warnings` | arreglo de string |  | Avisos que no impidieron timbrar (por ejemplo, el XML se guardará después). |
| `data[].email_error` | string |  | Por qué no se pudo mandar el correo; el comprobante sí se timbró. |
| `data[].substitutes` | objeto |  | La factura que esta sustituyó y si quedó cancelada. |
| `data[].substitutes.invoice` | string | sí | La factura sustituida (inv_…). |
| `data[].substitutes.canceled` | boolean | sí | true si la sustituida ya quedó cancelada. |
| `data[].substitutes.cancel_error` | string |  | Por qué no se pudo cancelar la sustituida (cancélela con POST /v1/invoices/{id}/cancel). |
| `data[].advance_application` | objeto |  | La aplicación del anticipo: método, nota de aplicación y su estado. |
| `data[].advance_application.advance` | string o null | sí | El anticipo, como factura (inv_…). |
| `data[].advance_application.advance_uuid` | string | sí | El folio fiscal del anticipo. |
| `data[].advance_application.method` | `egreso`, `remanente` | sí | egreso (la factura completa y después una nota de crédito por el anticipo, opción A) o remanente (la factura solo por lo que falta, opción B). |
| `data[].advance_application.status` | `done`, `credit_note_pending` | sí | done (listo) o credit_note_pending (falta timbrar la nota de aplicación: repita la solicitud con la misma Idempotency-Key). |
| `data[].advance_application.credit_note` | string o null | sí | La nota de aplicación del anticipo (inv_…), con method egreso. |
| `data[].advance_application.credit_note_error` | string |  | Por qué no se timbró la nota de aplicación (repita con la misma Idempotency-Key). |
| `has_more` | boolean | sí | true si hay más: pida la siguiente con starting_after igual al id del último. |
| `url` | string | sí | La ruta de esta lista. |

```json
{
  "object": "list",
  "data": [
    {
      "id": "inv_OufpKqnrvx9p0Nfbydl9jG4UNGeTYcvdrg",
      "object": "invoice",
      "livemode": false,
      "issuer": "iss_OufpKqnrvx9p",
      "branch": null,
      "type": "I",
      "status": "valid",
      "uuid": "5F1E8C2A-3B7D-4C9E-A1B2-C3D4E5F60718",
      "series": null,
      "folio": "1",
      "date": "2026-10-24T10:15:42",
      "customer": {
        "tax_id": "ICV060329BY0",
        "legal_name": "INMOBILIARIA CVA",
        "tax_system": "601",
        "zip": "33826"
      },
      "use": "I04",
      "payment_form": "03",
      "payment_method": "PUE",
      "currency": "MXN",
      "exchange_rate": null,
      "items": [
        {
          "description": "Mensualidad",
          "product_key": "86121700",
          "unit_key": "E48",
          "unit_name": "Unidad de servicio",
          "sku": "MEN-1",
          "quantity": 2,
          "unit_price": 2500,
          "taxability": "02",
          "iva": "0.16"
        }
      ],
      "subtotal": 5000,
      "discount": 0,
      "taxes": {
        "iva": 800,
        "ieps": 0,
        "iva_withheld": 0,
        "isr_withheld": 0,
        "local_transferred": 0,
        "local_withheld": 0
      },
      "total": 5800,
      "payment_status": "paid",
      "amount_due": 0,
      "amount_paid": 5800,
      "related": null,
      "cancellation": null,
      "email": null,
      "error": null,
      "recurring_invoice": null,
      "created_at": "2026-10-24T10:15:42-06:00",
      "metadata": {}
    }
  ],
  "has_more": false,
  "url": "/v1/invoices"
}
```

## Errores

Puede responder 400, 401, 403, 404, 429, 500 con el cuerpo de error de siempre; cada código está en https://fiscalisto.com/docs/api/errores.md.