Constancias de retenciones

Cuando una empresa le paga a una persona física por honorarios o arrendamiento, le retiene ISR e IVA y debe darle una constancia de retenciones: un CFDI de Retenciones 2.0, distinto de una factura, con lo que pagó y lo que retuvo en el periodo. Con la API la timbra con los mismos folios (RET1, RET2…), revisiones y timbres que Retenciones en la app. Cada constancia usa un timbre; cancelarla no cuesta.

Timbrar unaCopiar enlace a esta sección

Lo que le retuvo en septiembre a un abogado por $10,000 de honorarios: 10% de ISR y dos terceras partes del IVA.

curl https://api.fiscalisto.com/v1/retentions \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ret-2026-09-gora" \
  -d '{
    "code": "01",
    "recipient": {
      "tax_id": "GORA800101AB1",
      "legal_name": "ANA GÓMEZ RUIZ",
      "zip": "06000"
    },
    "period": { "year": 2026, "month": 9 },
    "totals": { "operation": 10000 },
    "taxes": [
      { "tax": "isr", "base": 10000, "amount": 1000 },
      { "tax": "iva", "base": 10000, "amount": 1066.67 }
    ],
    "send_email": true,
    "email": "ana@example.com"
  }'

La respuesta es la constancia (ret_…) con status: "valid", su uuid, su folio en internal_folio y el total retenido en totals.withheld. Llega también el webhook retention.stamped. Con send_email el receptor recibe el PDF y el XML en email.

Las claves que el SAT pide con complemento llevan su objeto, con los nombres de la referencia:

Cada objeto va solo con su clave; con otra contesta 400. Sin él, la constancia contesta 422 retention_invalid y dice qué falta. La clave 26 (servicios mediante plataformas tecnológicas) aún no se puede emitir: contesta 422.

{
  "code": "20",
  "recipient": { "tax_id": "PEPJ800101AB1", "legal_name": "JUAN PEREZ", "zip": "06700" },
  "period": { "year": 2026, "month": 9 },
  "totals": { "operation": 50000 },
  "taxes": [{ "tax": "isr", "base": 50000, "amount": 500, "payment_type": "03" }],
  "prize": { "state": "09" }
}

La misma Idempotency-Key otra vez contesta la misma constancia, sin timbrar otra. Si el SAT la rechaza, contesta 422 retention_rejected con su código en sat_code, y llega retention.failed.

Mandarla por correo despuésCopiar enlace a esta sección

curl https://api.fiscalisto.com/v1/retentions/ret_PhBIUaMpw23r7krC5Vs3pDT6dB7C2wuY0D/send \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "ana@example.com, contabilidad@example.com" }'

Sin to, va al correo que tiene guardado el receptor. Si no se pudo mandar, contesta email_failed y dice por qué; dos envíos a la vez de la misma constancia también (el segundo no se manda).

DescargarlaCopiar enlace a esta sección

GET /v1/retentions/{id}/pdf da el PDF y /xml el XML timbrado. GET /v1/retentions las lista, las más recientes primero, y filtra por status (valid, canceled, rejected, processing), por recipient (un RFC) y por year.

CancelarlaCopiar enlace a esta sección

curl https://api.fiscalisto.com/v1/retentions/ret_PhBIUaMpw23r7krC5Vs3pDT6dB7C2wuY0D/cancel \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "motive": "02" }'

Una constancia se cancela de inmediato: el receptor no tiene que aceptarlo. Llega retention.canceled. Con el motivo 01 (tenía errores y otra la sustituye), timbre antes la correcta y mándela en substitution (su ret_… o su UUID): debe ser otra constancia vigente del mismo emisor.