CANCELAR_RETENCION_SINGLE_MYSUITE_3 — SERVICIO CFDI + Timbrado (API REST) - Request Transaction

CANCELAR_RETENCION_SINGLE_MYSUITE_3 — SERVICIO CFDI + Timbrado (API REST) - Request Transaction

Estado Transacción: Vigente · Compatibilidad: CFDI de Retenciones e Información de Pagos · Esquema de cancelación vigente · Última revisión: 07/10/2026 · Próxima revisión: 07/01/2027 · Responsable: Jan Martínez


De un vistazo


Qué hace: cancela ante el SAT un comprobante de retenciones ya certificado, indicando el motivo. Te devuelve el acuse firmado digitalmente por la autoridad con el resultado de la cancelación.


Cuándo se usa: cuando una constancia de retenciones se emitió con errores o ampara una operación que no se llevó a cabo.


Cuándo no usarla: para cancelar CFDI ordinarios —ingreso, egreso, traslado, nómina o pago—, que usan CANCEL_DOCUMENT_3. Son procesos distintos ante el SAT, con esquemas, códigos y comportamientos distintos.


A diferencia de los CFDI ordinarios, aquí la cancelación es inmediata. La clave 1201 UUID Cancelado es un estado definitivo: el comprobante queda cancelado en esta misma llamada. No hay un proceso posterior que esperar ni una consulta de estado que hacer después. En un CFDI ordinario, en cambio, la clave 201 solo indica que la solicitud fue admitida a trámite.
Las retenciones tienen una ventana temporal para cancelarse. El acuse incluye un indicador de extemporaneidad, y el SAT puede rechazar la cancelación por estar fuera del periodo de la declaración anual que corresponde. No es una restricción que exista en los CFDI ordinarios.


Cómo saber si este es tu artículo

Si tu integración… Tu artículo es...
Cancela un comprobante de retenciones por RequestTransaction enviando un JSON por HTTP POST Este artículo
Hace lo mismo enviando un sobre SOAP a FactWSFront CANCELAR_RETENCION_SINGLE_MYSUITE_3 — CFDI + Timbrado (SOAP)
Cancela un CFDI de ingreso, egreso, traslado, nómina o pago enviando un JSON por HTTP POST CANCEL_DOCUMENT_3 — CFDI + Timbrado (API REST) - Request Transaction
Va a certificar un comprobante de retenciones enviando un JSON por HTTP POST FIRMAR_RETENCION — CFDI + Timbrado (API REST) - Request Transaction
Necesita el PDF de una retención enviando un JSON por HTTP POST GET_DOCUMENT_RETENCIONES — CFDI + Timbrado (API REST) - Request Transaction


Requisitos previos

  • Credenciales de integración vigentes que te proporciona MYSuite: Requestor y Entity.
  • El Folio Fiscal (UUID) de la retención, extraído del Timbre Fiscal Digital del comprobante que devolvió FIRMAR_RETENCION.
  • El motivo de cancelación, decidido por el área fiscal y no por el sistema.
  • Si el motivo es 01, el Folio Fiscal de la retención que sustituye a la cancelada, ya certificada.
  • CSD del emisor vigente en la plataforma: la solicitud de cancelación se firma.


Cómo hacerlo

  1. Recupera de tu sistema el Folio Fiscal de la retención que vas a cancelar.
    Resultado: el UUID que identifica el comprobante.
  2. Determina el motivo de cancelación. No es una decisión técnica: define cómo queda documentada la cancelación ante la autoridad.
    Resultado: la clave de motivo.
  3. Certifica primero la retención sustituta si el motivo es 01, y guarda su Folio Fiscal.
    Resultado: el UUID de sustitución disponible antes de cancelar.
  4. Construye el Dictionary con el atributo name igual a CancelInfo, con las entradas Motivo y FolioSustitucion, codifícalo en Base64.
    Resultado: la cadena que vas a poner en Data2.
  5. Arma el cuerpo JSON con los nueve campos: las credenciales, Transaction con valor CANCELAR_RETENCION_SINGLE_MYSUITE_3, el UUID en Data1 en texto plano, la cadena Base64 en Data2 y Data3 como cadena vacía.
    Resultado: petición lista. Fíjate en que Data1 no se codifica y Data2 sí.
  6. Envía la petición POST al recurso /RequestTransaction con Content-Type: application/json.
    Resultado: respuesta HTTP 200 con un cuerpo JSON de tres objetos.
  7. Lee responseField.resultField.
    Resultado: responseField = true te permite continuar; responseField = false te lleva a Solución de problemas.
  8. Lee responseDataField.responseData2Field tal cual, en texto plano: ahí viene la clave que devolvió el SAT con su descripción.
    Resultado: el desenlace de la cancelación, que aquí ya es definitivo.
  9. Decodifica responseDataField.responseData1Field desde Base64 para obtener el acuse en XML, con el estatus del folio, el motivo registrado, el indicador de extemporaneidad y el sello digital del SAT.
    Resultado: el acuse firmado, que es la evidencia de la cancelación.
  10. Conserva ese acuse junto a la retención cancelada. Está firmado por la autoridad y es la constancia del acto.
    Resultado: evidencia resguardada.
  11. Actualiza tu ERP marcando la retención como cancelada. Aquí sí puedes hacerlo con esta respuesta, a diferencia de los CFDI ordinarios.
    Resultado: retención cancelada y conciliada, sin pasos pendientes.

Si algo falla, ve a Solución de problemas.


Contrato técnico

1. Endpoint y operación

Protocolo HTTP/1.1 sobre HTTPS · arquitectura REST con cuerpo JSON
Método POST
Recurso /RequestTransaction
Content-Type application/json
Accept application/json
Valor Transaction CANCELAR_RETENCION_SINGLE_MYSUITE_3
Naturaleza Cancelación ante la autoridad. Síncrona y definitiva: concluye en esta llamada
Alcance Un comprobante por llamada.
Consumo No consume folios del paquete vigente


2. Ambientes

Ambiente URL
Pruebas https://api.mysuitetest.com/RequestTransaction
Producción https://api.mysuitecfdi.com/RequestTransaction

Un cliente CFDI + Timbrado (API REST) debe usar JES900109Q90 como Entity en pruebas; en producción, el RFC del emisor.


3. Autenticación

Esta vía no usa token: las credenciales viajan como campos del cuerpo JSON en cada petición.

Campo Tipo Obligatorio Formato Descripción
Requestor string Sí GUID Dato que MYSuite proporciona al emisor, relacionado con la seguridad de la transacción, autenticación y autorización
Transaction string Sí Literal en mayúsculas Método que quieres invocar. Para esta transacción: CANCELAR_RETENCION_SINGLE_MYSUITE_3
Country string Sí Valor fijo MX Abreviatura del país
Entity string Sí RFC (12–13 caracteres) RFC del emisor de la retención. En ambiente de test JES900109Q90
User string Sí GUID Se repite el valor de Requestor
UserName string Sí Country.Entity.Usuario_ERP Identifica al usuario del ERP. Ejemplo: MX.JES900109Q90.Jan


4. Parámetros de entrada

Nombre Tipo Obligatorio Formato Descripción
Data1 string Sí UUID, texto plano Folio Fiscal de la retención a cancelar. No se codifica en Base64
Data2 string Sí Base64 Dictionary con name="CancelInfo": motivo de la cancelación. Ver apartado 5
Data3 string No Cadena vacía "" Sin uso en esta transacción. El campo debe estar presente en el JSON con valor vacío
Asimetría de codificación dentro de la misma petición. Data1 va en texto plano y Data2 en Base64. La diferencia con CANCEL_DOCUMENT_3 es que en Data1 lleva un Dictionary StoredXmlSelector codificado, con el almacén, el país, el RFC del emisor, el UUID y el año. Aquí basta el UUID suelto. No se puede compartir la capa de armado de petición entre las dos cancelaciones.


5. Estructura de lo que se envía en Data1, Data2 y Data3

Data1 — Folio Fiscal

Valor sin estructura. El UUID de la retención, con sus 36 caracteres y sus guiones.

A diferencia de CANCEL_DOCUMENT_3, aquí no se envía el año de emisión. El Folio Fiscal basta para localizar la retención.

Data2 — Dictionary name="CancelInfo"

<Dictionary name="CancelInfo">
<Entry k="Motivo" v="[clave del motivo]"/>
<Entry k="FolioSustitucion" v="[UUID sustituto, o vacío]"/>
</Dictionary>
Entrada (k) Obligatorio Formato Descripción
Motivo Sí Dos dígitos Clave del motivo de cancelación: 01, 02, 03 ó 04
FolioSustitucion Condicional UUID, o cadena vacía Folio Fiscal de la retención que sustituye a la cancelada. Requerido cuando el motivo es 01; con cualquier otro motivo se envía el valor vacío

Es el mismo diccionario que usa CANCEL_DOCUMENT_3, con el mismo nombre y las mismas dos entradas: es la única parte del contrato que sí se comparte entre ambas cancelaciones.

Catálogo de motivos de cancelación
Clave Descripción Requiere folio de sustitución
01 Comprobante emitido con errores con relación Sí
02 Comprobante emitido con errores sin relación No
03 No se llevó a cabo la operación No
04 Operación nominativa relacionada en una factura global No


Info
El SAT valida estos valores: devuelve 1310 si el motivo no es válido, 1311 si el folio de sustitución no lo es y 1312 si lo envías cuando no corresponde.


Data3

Sin estructura. Se envía como cadena vacía.


6. Ejemplo de request

POST /RequestTransaction HTTP/1.1
Host: api.mysuitetest.com
Content-Type: application/json

{
"Requestor": "0c320b03-d4f1-47bc-9fb4-77995f9bf33e",
"Transaction": "CANCELAR_RETENCION_SINGLE_MYSUITE_3",
"Country": "MX",
"Entity": "JES900109Q90",
"User": "0c320b03-d4f1-47bc-9fb4-77995f9bf33e",
"UserName": "MX.JES900109Q90.Jan",
"Data1": "DE0A4A5B-7D7D-4215-88EE-B8FF50824450",
"Data2": "PERpY3Rpb25hcnkgbmFtZT0iQ2FuY2VsSW5mbyI+PEVudHJ5IGs9Ik1vdGl2byIgdj0iMDIiLz48RW50cnkgaz0iRm9saW9TdXN0aXR1Y2lvbiIgdj0iIi8+PC9EaWN0aW9uYXJ5Pg==",
"Data3": ""
}

Contenido de Data2 antes de codificar:

<Dictionary name="CancelInfo"><Entry k="Motivo" v="02"/><Entry k="FolioSustitucion" v=""/></Dictionary>


7. Ejemplo de response

Respuesta de una cancelación exitosa, obtenida en el ambiente de pruebas:

{
"requestField": {
"requestorField": "00000000-0000-0000-0000-000000000000",
"requestorNameField": null,
"requestorActiveField": true,
"transactionField": 293,
"countryField": "MX",
"entityField": "JES900109Q90",
"userField": "00000000-0000-0000-0000-000000000000",
"userNameField": "MX.JES900109Q90.Jan",
"idField": "59ba4a83-00e4-4d7f-b0c6-eef8e8d9340f",
"timeStampField": "2026-10-07T12:32:15.5002359-06:00"
},
"responseField": {
"resultField": true,
"timeStampField": "2026-10-07T12:32:16.8688942-06:00",
"lastResultField": "",
"codeField": 1,
"descriptionField": "",
"hintField": "",
"dataField": " 6659 59ba4a83-00e4-4d7f-b0c6-eef8e8d9340f",
"processorField": "TEST-BACK03",
"identifierField": null,
"batchIdentifierField": null
},
"responseDataField": {
"responseData1Field": "PD94bWwgdmVyc2lvbj0iMS4wIj8+PEFjdXNlIHhtbG5zOnhzZD0iaHR0cDovL3d3dy53My5vcmcvMjAwMS9YTUxTY2hlbWEiIHhtbG5zOnhzaT0iaHR0cDovL3d3dy53My5vcmcvMjAwMS9YTUxTY2hlbWEtaW5zdGFuY2UiIEZlY2hhPSIyMDI2LTEwLTA3VDEyOjMyOjE2LjcwNDg2MTUiIFJmY0VtaXNvcj0iSkVTOTAwMTA5UTkwIiBXb3JrUHJvY2Vzc0lkPSI1OGNjMzI5MS0wOGFjLTRiZTQtYjU0NC02MDQwNDlmZTNkNjUiIHhtbG5zPSJodHRwOi8vd3d3LnNhdC5nb2IubXgvZXNxdWVtYXMvcmV0ZW5jaW9ucGFnby8xIj48Rm9saW9zPjxVVUlEPkRFMEE0QTVCLTdEN0QtNDIxNS04OEVFLUI4RkY1MDgyNDQ1MDwvVVVJRD48RXN0YXR1c1VVSUQ+MTIwMTwvRXN0YXR1c1VVSUQ+PE1vdGl2bz4wMjwvTW90aXZvPjxFeHRlbXBvcmFuZW8+ZmFsc2U8L0V4dGVtcG9yYW5lbz48L0ZvbGlvcz48U2lnbmF0dXJlIElkPSJTZWxsb1NBVCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvMDkveG1sZHNpZyMiPjxTaWduZWRJbmZvPjxDYW5vbmljYWxpemF0aW9uTWV0aG9kIEFsZ29yaXRobT0iaHR0cDovL3d3dy53My5vcmcvVFIvMjAwMS9SRUMteG1sLWMxNG4tMjAwMTAzMTUiIC8+PFNpZ25hdHVyZU1ldGhvZCBBbGdvcml0aG09Imh0dHA6Ly93d3cudzMub3JnLzIwMDEvMDQveG1sZHNpZy1tb3JlI2htYWMtc2hhNTEyIiAvPjxSZWZlcmVuY2UgVVJJPSIiPjxUcmFuc2Zvcm1zPjxUcmFuc2Zvcm0gQWxnb3JpdGhtPSJodHRwOi8vd3d3LnczLm9yZy9UUi8xOTk5L1JFQy14cGF0aC0xOTk5MTExNiI+PFhQYXRoPm5vdChhbmNlc3Rvci1vci1zZWxmOjoqW2xvY2FsLW5hbWUoKT0nU2lnbmF0dXJlJ10pPC9YUGF0aD48L1RyYW5zZm9ybT48L1RyYW5zZm9ybXM+PERpZ2VzdE1ldGhvZCBBbGdvcml0aG09Imh0dHA6Ly93d3cudzMub3JnLzIwMDEvMDQveG1sZW5jI3NoYTUxMiIgLz48RGlnZXN0VmFsdWU+VWoxdVBYNmpwb0NTZnNUSDBHTHFxNmJySnFqMHdHVlE1OHZJQUtrK2tIVmtsVnNncUYvdDN4TnBsSnhORU1aSkxCVmd4ZWQrQ0g1bzg1Z0NyRE9zakE9PTwvRGlnZXN0VmFsdWU+PC9SZWZlcmVuY2U+PC9TaWduZWRJbmZvPjxTaWduYXR1cmVWYWx1ZT4xdTB5WHl1c2VrRm94dDFoczBhNCtuTFlLdWJPdGJTYXhvaXRCdXhyNWJXN2ZWYkhzMU50S0M5em1sNU50STBCNlhsMDlOMm8waFE1d2dNYTFOakZ3Zz09PC9TaWduYXR1cmVWYWx1ZT48S2V5SW5mbz48S2V5TmFtZT4zMDAwMTAwMDAwMDUwMDAwMjU1NDwvS2V5TmFtZT48S2V5VmFsdWU+PFJTQUtleVZhbHVlPjxNb2R1bHVzPmhVY1VPb0dFdFNEQWxyRjhLZWdRa0dLWThhREFlOXROUmtmNDh1ajErWWlyRFA0Y01FZDhZRWVsUVkxakx1MUdJTllLZjlOOVh4bU9mSGRMNEZVcitjdU9nckJ2aWFHV2NJc0pmWjgwSUdwdm94NmtVU0hvUnQraDMyeVFheVcwSHVOT3AwYjN5aUJwOVk2alRkWVRGVEFWemd6VWpmNExmVnQ4bjVGZWpWWjJ4RVJJeVJPbkdnYks4QTR4QnNQcEZhekhRa0syUENpWWUrTFlCbTBVeDlVWllrWUo5TXU5ckw1YzUxU2pncThKSmVrb3JwMEJ6ZkthZFJyU0VGeUQyWjZHd0IwUnN3akxaUXNwb2paR3hVbnFsYmxkdk82VGpGVVY0TVQ3RVY4UDdmMlZUUzB5cjRxU3d4MHkwODB6b0sxMENiSW9KWGZzRlJPSHlwRmo1dz09PC9Nb2R1bHVzPjxFeHBvbmVudD5BUUFCPC9FeHBvbmVudD48L1JTQUtleVZhbHVlPjwvS2V5VmFsdWU+PC9LZXlJbmZvPjwvU2lnbmF0dXJlPjwvQWN1c2U+",
"responseData2Field": "1201 UUID cancelado.",
"responseData3Field": "",
"responseDataSetField": null
}
}


8. Estructura de respuesta — éxito

El cuerpo de la respuesta es un objeto JSON con tres objetos de primer nivel. Todos los nombres de campo llevan el sufijo Field.

requestField — eco de la petición:

Campo Contenido
requestorField · userField GUID recibidos en la petición. Se envían valores en ceros por seguridad
requestorNameField Nombre del solicitante. Puede llegar null
requestorActiveField Booleano. Indica si el solicitante está activo
transactionField Entero. No lo uses para identificar la transacción
countryField · entityField · userNameField Eco de los valores recibidos
idField GUID de la operación en la plataforma. Dato a incluir al reportar incidencias
timeStampField Momento de recepción de la petición, con desplazamiento de zona horaria

responseField — resultado del procesamiento:

Campo Contenido
resultField Booleano. true cuando la solicitud se procesó ante el SAT
codeField Entero. Código de resultado de MYSuite. Ver apartado 10
timeStampField Momento en que concluyó el procesamiento
lastResultField · descriptionField · hintField Vacíos en cancelación exitosa. Ver apartado 9
dataField · processorField Referencia interna del procesamiento y Servidor que atendió la solicitud
identifierField Llega null. La transacción no devuelve datos del comprobante
batchIdentifierField Llega null
No esperes conciliar con esta respuesta. CANCEL_DOCUMENT_3 devuelve el identificador poblado —serie, folio, importe, receptor— y te permite verificar que cancelaste el comprobante correcto. Aquí ese objeto llega null, igual que en FIRMAR_RETENCION. El único dato de contraste disponible es el UUID dentro del acuse. Es el mismo patrón que en todo el ciclo de retenciones: la verificación tiene que apoyarse en lo que tu ERP ya tenía registrado.

responseDataField — resultado ante el SAT:

Campo Contenido
responseData1Field Acuse en Base64: XML firmado digitalmente por el SAT. Ver desglose siguiente
responseData2Field Clave del SAT en texto plano, con su descripción. No viene codificada
responseData3Field Vacío
responseDataSetField Llega null
El formato de la clave del SAT no es el mismo que en CANCEL_DOCUMENT_3. Aquí llega como 1201 UUID cancelado., sin el prefijo SAT: y sin guion separador; allí llega como SAT: 201 - UUID Admitido al proceso de cancelación. El catálogo oficial, por su parte, lo escribe UUID Cancelado con mayúscula inicial. No analices este campo por su texto: extrae el número, o mejor aún, lee el elemento EstatusUUID del acuse, que trae la clave sin formato.

Estructura del acuse (contenido de responseData1Field decodificado)

<?xml version="1.0"?>
<Acuse Fecha="2026-10-07T12:32:16.7048615"
RfcEmisor="JES900109Q90"
WorkProcessId="58cc3291-08ac-4be4-b544-604049fe3d65"
xmlns="http://www.sat.gob.mx/esquemas/retencionpago/1">
<Folios>
<UUID>DE0A4A5B-7D7D-4215-88EE-B8FF50824450</UUID>
<EstatusUUID>1201</EstatusUUID>
<Motivo>02</Motivo>
<Extemporaneo>false</Extemporaneo>
</Folios>
<Signature Id="SelloSAT" xmlns="http://www.w3.org/2000/09/xmldsig#">
...
</Signature>
</Acuse>
Elemento Contenido
@Fecha · @RfcEmisor Momento del acuse y RFC del emisor de la retención
@WorkProcessId Identificador del proceso en el SAT. No existe en el acuse de los CFDI ordinarios. Dato útil al escalar una incidencia ante la autoridad
Folios/UUID Folio Fiscal de la retención cancelada, en mayúsculas
Folios/EstatusUUID Clave que el SAT asignó. Es el mismo número de responseData2Field, sin texto alrededor. Es el valor sobre el que conviene ramificar
Folios/Motivo Motivo registrado por la autoridad. Permite verificar que se asentó el que enviaste
Folios/Extemporaneo Booleano. Indica si la cancelación se presentó fuera del periodo que corresponde. Ver apartado 11
Signature Id="SelloSAT" Sello digital del SAT. Hace del acuse una evidencia verificable de la cancelación
El espacio de nombres del acuse es http://www.sat.gob.mx/esquemas/retencionpago/1, distinto del http://cancelacfd.sat.gob.mx que usan los CFDI ordinarios. Si tu ERP analiza ambos acuses con el mismo código, tiene que contemplar los dos espacios de nombres y los dos conjuntos de elementos.

Claves del SAT en la cancelación de retenciones

Clave Significado Qué hacer
1201 UUID Cancelado Cancelación consumada. Marcar la retención como cancelada
1202 UUID Previamente cancelado Ya estaba cancelada. No es un error. Conciliar el estado en tu ERP
1203 UUID no corresponde con el emisor Revisar el Entity y el UUID enviado
1205 UUID no existe Verificar el Folio Fiscal y el ambiente en que operas
1310 Motivo no válido Revisar la clave enviada en Motivo
1311 Folio Sustitución no válido Verificar que el UUID sustituto exista y esté certificado
1312 Folio Sustitución no requerido Se envió un folio sustituto con un motivo distinto de 01
1313 Solicitud fuera de la declaración anual Venció la ventana para cancelar. Escalar al área fiscal
1314 Relación no válida Revisar la relación entre la retención cancelada y su sustituta

Para el resto de las claves del SAT y de MYSuite, consulta el Catálogo de códigos de error y notificación en Apartado 10.


9. Estructura de respuesta — error

El cuerpo mantiene los tres objetos del apartado 8. Cambia el contenido de responseField.

Campo Contenido en error
resultField false: la solicitud no se procesó
codeField Código del error de MYSuite. Ver apartado 10
lastResultField Identificador simbólico del error. Es el valor más estable para ramificar tu lógica
descriptionField · hintField Mensaje del error y sugerencia de corrección
processorField Servidor que atendió la solicitud
responseData1Field · responseData2Field Vacíos
Dos numeraciones en juego. codeField trae un código de MYSuite; responseData2Field trae una clave del SAT. Un error de MYSuite significa que la autoridad nunca se enteró; una clave del SAT significa que la solicitud llegó y obtuvo respuesta, aunque fuera un rechazo.


10. Códigos de Error


11. Límites y comportamiento

Aspecto Valor
Comprobantes por llamada Uno
Desenlace Definitivo en la misma llamada. La clave 1201 indica cancelación consumada, no solicitud admitida
Confirmación posterior No hace falta. No existe una transacción de consulta de estado para retenciones
Aceptación del receptor No aplica. Las retenciones no entran al mecanismo de oposición del receptor que rige a los CFDI ordinarios
Ventana temporal Existe. El acuse reporta extemporaneidad y el SAT puede rechazar con 1313 por estar fuera del periodo de la declaración anual.
Idempotencia Una segunda cancelación del mismo comprobante devuelve 1202 UUID Previamente cancelado, no una segunda cancelación
Efectos Irreversibles. Una retención cancelada no se puede revertir
Consumo de folios No se descuenta folio del paquete vigente
Timeout 60 segundos en servidor front
Recuperación ante TimeOut Si se pierde la respuesta, reintentar es seguro: la plataforma devolverá 1202 si la cancelación ya se había consumado. Es el único punto del ciclo de retenciones con una ruta de recuperación clara, a diferencia de FIRMAR_RETENCION


12. Versionado y cumplimiento

  • Esta transacción implementa la cancelación de CFDI de Retenciones e Información de Pagos bajo el esquema de cancelación vigente, con motivo obligatorio y folio de sustitución condicional.
  • El acuse viene firmado digitalmente por el SAT y constituye la evidencia de la cancelación. Consérvalo junto a la retención: es el documento que acredita el acto.
  • El motivo de cancelación es una declaración ante la autoridad, no un campo técnico. La decisión corresponde al área fiscal o contable.
  • El acuse usa el espacio de nombres retencionpago/1, propio de las retenciones, distinto del que usan los CFDI ordinarios.
  • Los CFDI ordinarios se cancelan con CANCEL_DOCUMENT_3, no con esta transacción.

Solución de problemas

"¿Tengo que consultar después si la retención quedó cancelada?"


Problema. El proceso replica el flujo de los CFDI ordinarios y busca una transacción de consulta de estado que no existe.

Entorno. CFDI + Timbrado · API REST · integraciones que ya implementaron la cancelación de CFDI ordinarios.

Resolución. No hace falta. La clave 1201 UUID Cancelado es definitiva: la retención quedó cancelada en esa misma llamada. Puedes marcarla como cancelada en tu ERP con esta respuesta. La transacción CONSULTAR_DOCUMENTO es para CFDI ordinarios y no aplica aquí.

Causa. En los CFDI ordinarios la clave 201 significa «admitido al proceso», y por eso exige una consulta posterior. En retenciones el proceso no existe: la cancelación es inmediata.

"Copié el código de CANCEL_DOCUMENT_3 y no funciona"


Problema. La petición es rechazada al reutilizar la implementación de la cancelación de CFDI ordinarios.

Entorno. CFDI + Timbrado · API REST · integraciones que cancelan ambos tipos de comprobante.

Resolución. Solo Data2 es idéntico entre las dos transacciones. Data1 cambia por completo: allí lleva un Dictionary StoredXmlSelector codificado en Base64, con almacén, país, RFC del emisor, UUID y año; aquí lleva el UUID suelto y en texto plano. Comparte el armado de CancelInfo y escribe el resto por separado.

Causa. El contrato de los tres campos de datos cambia en cada transacción, incluso entre dos que hacen lo mismo sobre familias documentales distintas.

"Me devuelve 1202 y creo que algo salió mal"


Problema. La clave del SAT es 1202 en lugar de 1201.

Entorno. CFDI + Timbrado · API REST · reintentos tras perder una respuesta.

Resolución. No salió nada mal: 1202 UUID Previamente cancelado indica que la retención ya estaba cancelada. Tu solicitud anterior sí llegó. Concilia el estado en tu ERP y continúa. Es también la razón por la que reintentar esta transacción es seguro.

Causa. Una solicitud previa se procesó correctamente aunque tu sistema no recibiera la respuesta.

"Me rechaza la cancelación por estar fuera de plazo"


Problema. La respuesta trae la clave 1313 Solicitud fuera de la declaración anual, o el acuse marca la cancelación como extemporánea.

Entorno. CFDI + Timbrado · API REST · cancelación de retenciones de ejercicios anteriores.

Resolución. No hay corrección técnica posible: la ventana para cancelar esa retención venció. Escálalo al área fiscal, porque la vía de solución es administrativa, no de integración. 
Causa. Las retenciones están ligadas a la declaración anual del ejercicio, y su cancelación tiene una ventana temporal que los CFDI ordinarios no tienen.

"La respuesta no trae ningún dato de la retención"


Problema. identifierField llega null y el proceso no puede verificar qué comprobante se canceló.

Entorno. CFDI + Timbrado · API REST · procesos con validación cruzada.

Resolución. El único dato de contraste está en el acuse: el elemento UUID dentro de Folios, que viene en mayúsculas. Compáralo sin distinguir mayúsculas y minúsculas contra el Folio Fiscal que enviaste. Para el resto de los datos del comprobante, apóyate en lo que tu ERP ya tenía registrado.

Causa. Ni la certificación ni la cancelación devuelven el objeto de identificación.

"Mi código no reconoce la clave del SAT"


Problema. La lógica que analiza responseData2Field funciona con los CFDI ordinarios y falla aquí.

Entorno. CFDI + Timbrado · API REST · integraciones que cancelan ambos tipos de comprobante.

Resolución. El formato del texto no coincide entre ambas cancelaciones: aquí llega como 1201 UUID cancelado. y en CANCEL_DOCUMENT_3 como SAT: 201 - UUID Admitido al proceso de cancelación. Deja de analizar el texto y lee el elemento EstatusUUID del acuse, que trae la clave sin formato y es estable en ambas transacciones.

Causa. El mismo campo de respuesta no comparte convención de redacción entre transacciones hermanas.

"Me rechaza el motivo o el folio de sustitución"


Problema. La respuesta trae las claves 1310, 1311 o 1312.

Entorno. CFDI + Timbrado · API REST · sustitución de retenciones.

Resolución. 1310 indica un motivo fuera del catálogo; revisa que la clave sea de 01 a 04 y lleve sus dos dígitos. 1311 indica que el UUID sustituto no es válido: tiene que corresponder a una retención ya certificada. 1312 indica lo contrario, que enviaste un folio de sustitución con un motivo que no lo requiere; con cualquier clave distinta de 01, esa entrada va vacía.

Causa. El SAT valida la coherencia entre el motivo y el folio de sustitución, rechaza tanto la ausencia como el exceso.


Para entender más

Por qué cancelar una retención es más simple que cancelar una factura

El esquema de cancelación vigente introdujo el derecho del receptor a oponerse a la cancelación de un CFDI. Por eso cancelar una factura es un proceso: se solicita, el SAT la admite a trámite, el receptor puede manifestarse y el desenlace llega después. Las retenciones no entran en ese mecanismo. Una constancia de retenciones documenta un impuesto retenido por quien la emite, y su cancelación no admite oposición del retenido.

De ahí se deriva todo lo demás: la clave 1201 es terminal en lugar de provisional, no existe una transacción de consulta de estado, y tu ERP puede marcar la retención como cancelada con la respuesta de esta llamada. Lo que en las facturas obliga a un tercer estado —«cancelación solicitada»— aquí no hace falta.

Una ausencia que no es un hueco

Conviene decirlo explícitamente porque es la pregunta que surge primero: que no exista una transacción equivalente a CONSULTAR_DOCUMENTO para retenciones no es una carencia de la plataforma. Es la consecuencia de que no haya nada que consultar. Cuando una operación concluye en la misma llamada, preguntar después por su estado no aportaría información nueva.

La ventana temporal, a cambio

Lo que las retenciones sí tienen y las facturas no, es un plazo. El acuse incluye un indicador de extemporaneidad y el SAT puede rechazar la solicitud por estar fuera del periodo de la declaración anual correspondiente. Tiene sentido: una constancia de retenciones alimenta una declaración, y cancelarla después de que esa declaración se presentó tendría efectos que el esquema prefiere evitar.

Para quien integra, esto cambia el orden de prioridades. En facturas, la pregunta operativa es «¿ya se canceló?»; en retenciones es «¿todavía estoy a tiempo?». Es una restricción de negocio, y conviene que el ERP la contemple antes de intentar la cancelación y no después del rechazo.

Por qué el criterio es solo el UUID

CANCEL_DOCUMENT_3 necesita cinco datos para localizar la factura: el almacén, el país, el RFC del emisor, el UUID y el año. Aquí basta el Folio Fiscal. La diferencia refleja el volumen: las retenciones son muchas menos que las facturas y no requieren la partición por año que la plataforma aplica a los CFDI ordinarios. El efecto práctico es agradable —menos criterios que reunir— y uno incómodo: el contrato de Data1 no se parece en nada entre las dos cancelaciones, aunque conceptualmente hagan lo mismo.

Qué aporta el acuse que no aporta la respuesta

El acuse trae tres cosas que no están en ningún otro lado: la clave del SAT sin texto alrededor, en EstatusUUID; el motivo tal como lo registró la autoridad, que permite verificar que se asentó el que enviaste; y el identificador del proceso en el SAT, útil al escalar una incidencia ante la autoridad. Además viene firmado, lo que lo convierte en evidencia verificable de la cancelación. Vale la pena conservarlo completo, no solo extraer el estatus.

Un reintento que sí es seguro

El ciclo de retenciones tiene un punto débil conocido: si se pierde la respuesta de FIRMAR_RETENCION, no queda ningún identificador del lado del cliente ni transacción de búsqueda para recuperarlo. Esta transacción es la excepción: como el criterio es el UUID y la plataforma responde 1202 cuando la retención ya estaba cancelada, reintentar es seguro y no produce efectos duplicados. Es el único tramo del ciclo con una ruta de recuperación clara.

Dos acuses que no se parecen

El acuse de las retenciones usa el espacio de nombres retencionpago/1 y trae elementos que el de los CFDI ordinarios no tiene: el motivo, el indicador de extemporaneidad y el identificador de proceso. El de las facturas usa cancelacfd.sat.gob.mx y se limita al folio y su estatus. Si tu ERP archiva ambos con el mismo código, tendrá que contemplar dos espacios de nombres y dos conjuntos de elementos. No es un detalle menor al construir un repositorio único de acuses.

Por qué SOAP y REST se documentan por separado

La transacción es la misma operación de negocio en ambos transportes: mismo criterio, mismo diccionario de motivo, mismo acuse. Lo que cambia es todo lo que rodea al dato: los encabezados, la forma del cuerpo, la nomenclatura de la respuesta y la manera de leerla. Documentar ambos en un solo artículo obligaría al lector a descartar la mitad del contrato técnico en cada consulta, y es precisamente donde se originan los errores de integración.


Transacciones del servicio CFDI + Timbrado (API REST)


Vía RequestTransaction


      Emisión
      Consulta y Recuperación
      Validación y Recepción
      CFDI de Retenciones


Vía JsonServiceCall

      Autenticación (obtención de token)
      Emisión
      Consulta y Recuperación
      Esquema de cancelación