# Listar constancias

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

Las constancias del emisor, 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, canceled, rejected o processing. |
| `recipient` | consulta |  | RFC del receptor. |
| `year` | consulta |  | Ejercicio, 4 dígitos. |

## 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.retentions.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.retentions.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->retentions->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.Retentions.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.Retentions.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.retentions().listAutoPaging()) {
    System.out.println(item.getId());
}
```

## Respuesta 200

Correcto.

Un objeto `RetentionList`:

| 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` | `"retention"` | sí | Qué tipo de objeto es («invoice», «customer»…). |
| `data[].issuer` | string | sí | El emisor (iss_…). |
| `data[].status` | `processing`, `valid`, `rejected`, `canceled` | sí | processing: el PAC no ha contestado. valid: timbrada. 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[].folio` | integer o null | sí | Folio (Folio). Fiscalisto asigna el siguiente de la serie; mande uno solo si debe ser ese. |
| `data[].internal_folio` | string o null | sí | Folio interno (FolioInt): RET1, RET2… |
| `data[].date` | string o null | sí | Fecha de emisión (Fecha), hora de la Ciudad de México. |
| `data[].code` | string | sí | Clave de la retención (CveRetenc), c_CveRetenc: 01 servicios profesionales, 05 arrendamiento, 14 dividendos, 16 intereses, 18 pagos al extranjero… Las claves 14, 16, 17 y 18 a 24 llevan su complemento (dividends, interest, trust_lease, foreign_payment, share_sale, prize, trust, retirement_plan, mortgage_interest, financial_derivatives); la 26 (plataformas tecnológicas) aún no se puede emitir. |
| `data[].description` | string o null | sí | Descripción de la retención (DescRetenc). |
| `data[].recipient` | objeto | sí | Receptor de la constancia (Receptor): nacional con RFC y código postal, o extranjero. |
| `data[].recipient.foreign` | boolean | sí | true si el receptor es extranjero (sin RFC). |
| `data[].recipient.tax_id` | string o null | sí | RFC (Rfc), 12 caracteres una persona moral y 13 una física. |
| `data[].recipient.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[].recipient.zip` | string |  | Código postal del domicilio fiscal, 5 dígitos, como en la constancia de situación fiscal. El de un emisor es el lugar de expedición (LugarExpedicion) de sus comprobantes. |
| `data[].recipient.curp` | string o null |  | CURP, 18 caracteres. |
| `data[].period` | objeto | sí | Periodo (Periodo): mes inicial, mes final y año. |
| `data[].period.year` | integer | sí | Año (Ejercicio). (de -9007199254740991 a 9007199254740991) |
| `data[].period.from_month` | integer | sí | Mes inicial (MesIni), 1 a 12. (de -9007199254740991 a 9007199254740991) |
| `data[].period.to_month` | integer | sí | Mes final (MesFin), 1 a 12, del mismo año. (de -9007199254740991 a 9007199254740991) |
| `data[].totals` | objeto | sí | Totales (Totales). |
| `data[].totals.operation` | number o null | sí | Monto total de la operación (MontoTotOperacion). |
| `data[].totals.taxed` | number o null | sí | Monto gravado (MontoTotGrav). Por omisión, operation menos exempt. |
| `data[].totals.exempt` | number o null | sí | Monto exento (MontoTotExent). Por omisión 0. |
| `data[].totals.withheld` | number o null | sí | Total retenido (MontoTotRet). |
| `data[].taxes` | arreglo de objeto | sí | Impuestos del comprobante, por tipo. |
| `data[].taxes[].tax` | string | sí | Impuesto: isr, iva o ieps (ImpuestoRet 001, 002, 003). |
| `data[].taxes[].base` | number | sí | Base del impuesto retenido (BaseRet). |
| `data[].taxes[].amount` | number | sí | Monto retenido (MontoRet). |
| `data[].taxes[].payment_type` | string | sí | Tipo de pago de la retención (TipoPagoRet): 01 definitivo IVA, 02 definitivo IEPS, 03 definitivo ISR, 04 provisional ISR. Por omisión el usual de cada impuesto. |
| `data[].dividends` | objeto |  | Complemento de dividendos. |
| `data[].interest` | objeto |  | Complemento de intereses. |
| `data[].foreign_payment` | objeto |  | Complemento de pagos a extranjeros. |
| `data[].trust_lease` | objeto |  | Complemento de arrendamiento en fideicomiso (Arrendamientoenfideicomiso 1.0), obligatorio con code 17. |
| `data[].share_sale` | objeto |  | Complemento de enajenación de acciones u operaciones de valores (EnajenaciondeAcciones 1.0), obligatorio con code 19. |
| `data[].prize` | objeto |  | Complemento de premios (Premios 1.0), obligatorio con code 20. Sus montos son los de totals. |
| `data[].trust` | objeto |  | Complemento de fideicomisos que no realizan actividades empresariales (Fideicomisonoempresarial 1.0), obligatorio con code 21. |
| `data[].retirement_plan` | objeto |  | Complemento de planes personales de retiro (Planesderetiro 1.1), obligatorio con code 22: lo del año anterior. |
| `data[].mortgage_interest` | objeto |  | Complemento de intereses reales deducibles por créditos hipotecarios (Intereseshipotecarios 1.0), obligatorio con code 23. |
| `data[].financial_derivatives` | objeto |  | Complemento de operaciones financieras derivadas de capital (Operacionesconderivados 1.0), obligatorio con code 24. |
| `data[].cancellation` | objeto o null | sí | La cancelación, si se pidió: estado, motivo, sustituto y cuándo. |
| `data[].cancellation.status` | string | 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.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.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[].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ó. |
| `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": "ret_OufpKqnrvx9p5tENFcmUXpXJ58XxnF67kv",
      "object": "retention",
      "livemode": false,
      "issuer": "iss_OufpKqnrvx9p",
      "status": "valid",
      "uuid": "9A6F6BF3-6786-4747-800A-C9964E6509AE",
      "folio": 1,
      "internal_folio": "RET1",
      "date": "2026-10-24T10:15:42",
      "code": "01",
      "description": null,
      "recipient": {
        "foreign": false,
        "tax_id": "PEPJ800101AB1",
        "legal_name": "JUAN PEREZ PEREZ",
        "zip": "33826",
        "curp": null
      },
      "period": {
        "year": 2026,
        "from_month": 9,
        "to_month": 9
      },
      "totals": {
        "operation": 10000,
        "taxed": 10000,
        "exempt": 0,
        "withheld": 2066.67
      },
      "taxes": [
        {
          "tax": "isr",
          "base": 10000,
          "amount": 1000,
          "payment_type": "04"
        },
        {
          "tax": "iva",
          "base": 10000,
          "amount": 1066.67,
          "payment_type": "01"
        }
      ],
      "cancellation": null,
      "email": null,
      "error": null,
      "created_at": "2026-10-24T10:15:42-06:00",
      "metadata": {
        "proveedor": "42"
      }
    }
  ],
  "has_more": false,
  "url": "/v1/retentions"
}
```

## 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.