Timbrar un CFDI de retenciones (plataformas digitales)

Timbra la constancia mensual de Retenciones 2.0 con el complemento de Servicios de Plataformas Tecnológicas (CveRetenc 26).

Desde la v1.43.0. Es la constancia que una plataforma digital emite a cada prestador de servicios o vendedor, una por receptor y por mes. Mandas los servicios del periodo con la comisión de la plataforma en cada uno. La API deriva los montos que el SAT valida: MontoTotOperacion, el IVA trasladado de cada servicio, el ISR retenido, el IVA retenido, las exclusiones de efectivo y DifIVAEntregadoPrestServ.

La serie del comprobante es RET. folio en el recurso es el folio numérico interno, de la misma secuencia del emisor. folioText es el FolioInt que mandaste, o null. Si no mandas folio, el FolioInt timbrado es RET seguido de ese número. La moneda del recurso es MXN.

tipoServicio (c_TipoDeServ) decide las tasas. No lo adivines: está en GET /v1/catalogs/retenciones/tipo-servicio y, por MCP, en get_catalog con retenciones/tipo-servicio. Para una persona física prestadora la tasa de ISR depende del tipo y del Ejercicio: 06 (Otro tipo de servicios) es 2.5% en 2026 y retiene 50% del IVA; 09 (Enseñanza a distancia o test o ejercicios) no retiene ISR y retiene 100% del IVA. Los tipos 07 y 08 tampoco retienen ISR y retienen 100% del IVA. Una persona moral prestadora paga 2.5% de ISR en los tipos que sí retienen ISR, y isrTipoPagoRet queda en 04. XAXX010101000 es 20% de ISR y 100% de IVA. Un prestador XEXX010101000 no lleva ISR y retiene 100% del IVA. Si el RFC del emisor tiene 13 caracteres, no hay retención de ISR.

El timbrado es el mismo que el de las facturas: espera hasta unos 20 segundos por el UUID (201). Bajo carga extrema responde 202 y hay que consultar GET /v1/retenciones/{id}. Exige Idempotency-Key. Un replay trae Idempotency-Replayed: true.

Al timbrar, fallar o cancelarse se pueden avisar con los webhooks retencion.stamped, retencion.stamp_failed y retencion.cancelled, suscritos en POST /v1/webhook_endpoints.

Por MCP, create_retencion acepta el mismo cuerpo. La guía de producto está en retenciones de plataformas digitales.

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

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

Parámetros

Headers

Cuerpo (JSON)

Ejemplos

curl -X POST https://api.cfdi.express/v1/retenciones \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: retencion-2026-09-prestador-42" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "mkq2f8v3x1t7p9d4n6c0b5rz",
    "folio": "202609C0042",
    "ejercicio": 2026,
    "mes": 9,
    "periodicidad": "02",
    "tipoServicio": "05",
    "isrTipoPagoRet": "03",
    "receiver": {
      "rfc": "XAXX010101000",
      "name": "NOMBRE DEL PRESTADOR",
      "zip": "42501"
    },
    "servicios": [
      {
        "fecha": "2026-09-15",
        "formaPago": "02",
        "precioSinIva": 1000,
        "ivaTasa": 0.16,
        "comision": { "importe": 150, "porcentaje": 0.15 }
      }
    ]
  }'

Respuesta

{
  "id": "ret7k3q9x2m4v1t8p6d0n5cb",
  "object": "retencion",
  "livemode": false,
  "status": "stamped",
  "merchantId": "mkq2f8v3x1t7p9d4n6c0b5rz",
  "uuid": "9f1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
  "serie": "RET",
  "folio": 42,
  "folioText": "202609C0042",
  "fecha": "2026-10-01T10:00:00",
  "cveRetenc": "26",
  "ejercicio": 2026,
  "mes": 9,
  "periodicidad": "02",
  "tipoServicio": "05",
  "receiver": {
    "rfc": "XAXX010101000",
    "name": "NOMBRE DEL PRESTADOR",
    "zip": "42501"
  },
  "servicios": [
    {
      "fecha": "2026-09-15",
      "formaPago": "02",
      "precioSinIva": 1000,
      "ivaTasa": 0.16,
      "comision": { "importe": 150, "porcentaje": 0.15 }
    }
  ],
  "impRetenidos": [
    { "impuesto": "001", "baseRet": 1000, "montoRet": 200, "tipoPagoRet": "03", "tasa": 0.2 },
    { "impuesto": "002", "baseRet": 160, "montoRet": 160, "tipoPagoRet": "01", "tasa": 1 }
  ],
  "montoTotOperacion": 1000,
  "montoTotRet": 360,
  "isrRetenido": 200,
  "ivaRetenido": 160,
  "ivaTrasladado": 160,
  "difIvaEntregadoPrestServ": 0,
  "comisiones": 150,
  "currency": "MXN",
  "files": { "status": "pending" },
  "stampedAt": "2026-10-01T16:00:10.512Z",
  "createdAt": "2026-10-01T16:00:08.907Z"
}

Errores

Notas

• Los montos del ejemplo 201 los calcula la API a partir de precioSinIva. montoTotOperacion es la suma de esos precios en los servicios que llevan IVA (formaPago 09 no entra). El efectivo (formaPago 01) se excluye de las bases de ISR e IVA retenido. impRetenidos[].impuesto es 001 (ISR) o 002 (IVA). El IVA usa tipoPagoRet 01 (pago definitivo IVA). El ISR usa 03 o 04.
• Con RFC XAXX010101000 el ISR es 20% y el IVA retenido es 100%, así que difIvaEntregadoPrestServ queda en 0. El ejemplo asume un emisor con RFC de 12 caracteres: si el emisor es persona física (13 caracteres) no hay partida de ISR. XEXX010101000 es el prestador extranjero, no lleva receiver.zip, no retiene ISR y retiene 100% del IVA.
• Un 202 significa que el timbrado sigue en curso (status: "stamping"). Consulta GET /v1/retenciones/{id}.
• Cuando files.status es ready, files.xmlUrl, files.pdfUrl y files.zipUrl son URLs firmadas de 15 minutos. files.status también puede ser pending, processing o failed.
• La serie siempre es RET. folioText guarda el FolioInt del request. Si lo omites queda null y el FolioInt timbrado es RET más el folio numérico.
• El recurso trae object: "retencion" y status en stamping, stamped, stamp_failed, cancel_pending o cancelled.

Continuar