FISCALISTO / API / REFERENCIA
Timbrar una constancia de retenciones POST
Timbra una constancia de retenciones e información de pagos (Retenciones 2.0) con los folios RET1, RET2… del emisor. Una vez por Idempotency-Key; con send_email y email la manda al receptor al timbrarla.
Descargar el PDF GET
La representación impresa de la constancia.
Una constancia de retenciones con su estado, sus impuestos retenidos y, si se mandó, a quién.
bearerAuthAutorizaciónBearer <llave>Su llave secreta: fk_test_… en pruebas, fk_live_… en producción. Desarrolladores › Llaves.
id*stringEl id del objeto.
issuer?stringCon un UUID en vez del id, el emisor (iss_…) si la cuenta tiene varios.
refresh?booleantrue para preguntar su estado al SAT ahora (cancelaciones en espera).
Correcto.
application/jsonUna constancia de retenciones e información de pagos (CFDI de retenciones 2.0).
id*stringIdentificador del objeto, con su prefijo (iss_, inv_, ret_, cus_, prd_, emp_, bat_, brn_, whs_, stm_, adj_, evt_, whe_).
livemode*booleantrue en producción (llaves fk_live_), false en pruebas (fk_test_). Lo de pruebas no vale ante el SAT.
object*stringQué tipo de objeto es («invoice», «customer»…).
issuer*stringEl emisor (iss_…).
status*stringprocessing: el PAC no ha contestado. valid: timbrada. rejected: el SAT o el PAC no la aceptaron (ver error). canceled: cancelada.
"processing""valid""rejected""canceled"uuid*|Folio fiscal que asigna el SAT (UUID del Timbre Fiscal Digital), en mayúsculas.
folio*|Folio (Folio). Fiscalisto asigna el siguiente de la serie; mande uno solo si debe ser ese.
internal_folio*|Folio interno (FolioInt): RET1, RET2…
date*|Fecha de emisión (Fecha), hora de la Ciudad de México.
code*stringClave 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.
description*|Descripción de la retención (DescRetenc).
recipient*Receptor de la constancia (Receptor): nacional con RFC y código postal, o extranjero.
period*Periodo (Periodo): mes inicial, mes final y año.
totals*Totales (Totales).
taxes*array<>Impuestos del comprobante, por tipo.
dividends?Complemento de dividendos.
interest?Complemento de intereses.
foreign_payment?Complemento de pagos a extranjeros.
trust_lease?Complemento de arrendamiento en fideicomiso (Arrendamientoenfideicomiso 1.0), obligatorio con code 17.
share_sale?Complemento de enajenación de acciones u operaciones de valores (EnajenaciondeAcciones 1.0), obligatorio con code 19.
prize?Complemento de premios (Premios 1.0), obligatorio con code 20. Sus montos son los de totals.
trust?Complemento de fideicomisos que no realizan actividades empresariales (Fideicomisonoempresarial 1.0), obligatorio con code 21.
retirement_plan?Complemento de planes personales de retiro (Planesderetiro 1.1), obligatorio con code 22: lo del año anterior.
mortgage_interest?Complemento de intereses reales deducibles por créditos hipotecarios (Intereseshipotecarios 1.0), obligatorio con code 23.
financial_derivatives?Complemento de operaciones financieras derivadas de capital (Operacionesconderivados 1.0), obligatorio con code 24.
cancellation*|La cancelación, si se pidió: estado, motivo, sustituto y cuándo.
email*|El envío por correo: a quién, con copia a quién y cuándo (null si no se ha enviado).
error*|Por qué el SAT o el PAC no lo aceptaron: mensaje, código del SAT y texto original.
created_at*|Cuándo se creó, ISO 8601 con la hora de la Ciudad de México (-06:00).
metadata*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.
warnings?array<string>Avisos que no impidieron timbrar (por ejemplo, el XML se guardará después).
email_error?stringPor qué no se pudo mandar el correo; el comprobante sí se timbró.
curl -X GET 'https://api.fiscalisto.com/v1/retentions/string' \ -H 'Authorization: Bearer fk_test_…'{ "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" }}