Documentación / API / Retenciones (plataformas digitales)

Listar CFDIs de retenciones

GEThttps://api.cfdi.express/v1/retencionesAPI key

Lista las constancias de retenciones con filtros por emisor, estatus, UUID, RFC del prestador, ejercicio y mes. Paginación por cursor.

Desde la v1.43.0. Cada elemento es un recurso retencion, el mismo de POST /v1/retenciones.

Por MCP, list_retenciones acepta los mismos filtros.

Autenticación

Authorization: Bearer sk_test_... | sk_live_...

El header x-account-id indica la cuenta. Si no eres miembro, la respuesta es 403.

Parámetros

Query string

Campo	Tipo	Descripción
limit	integer	Elementos por página. Entre 1 y 100. Default 10.
starting_after	string	Id de la última retención de la página anterior (cursor), mientras has_more sea true.
merchantId	string	Filtra por emisor.
status	string	stamping, stamped, stamp_failed, cancel_pending o cancelled.
uuid	string	Busca por folio fiscal (UUID) del SAT.
receiverRfc	string	RFC de un prestador. Con XEXX010101000 lista a todos los prestadores extranjeros.
ejercicio	integer	Año reportado.
mes	integer	Mes reportado, de 1 a 12.
createdFrom	string	Fecha ISO 8601 mínima de creación.
createdTo	string	Fecha ISO 8601 máxima de creación.

Ejemplos

cURL

curl -G https://api.cfdi.express/v1/retenciones \
  -H "Authorization: Bearer sk_test_..." \
  --data-urlencode "status=stamped" \
  --data-urlencode "ejercicio=2026" \
  --data-urlencode "mes=9" \
  --data-urlencode "limit=20"

Respuesta

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "ret7k3q9x2m4v1t8p6d0n5cb",
      "object": "retencion",
      "livemode": false,
      "status": "stamped",
      "merchantId": "mkq2f8v3x1t7p9d4n6c0b5rz",
      "uuid": "9f1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
      "cveRetenc": "26",
      "ejercicio": 2026,
      "mes": 9,
      "periodicidad": "02",
      "tipoServicio": "05",
      "montoTotOperacion": 1000,
      "montoTotRet": 360,
      "createdAt": "2026-10-01T16:00:08.907Z"
    }
  ],
  "has_more": false
}

Errores

Status	code	Cuándo aparece
401	unauthorized	Falta el header Authorization o la llave es inválida.
429	rate_limited	Excediste el límite de requests por minuto de tu cuenta (300 por default). La respuesta incluye Retry-After.

Continuar

POSTTimbrar retención GETConsultar retención