Qué hace: consulta al SAT el estado de cancelación de un CFDI y te devuelve cinco datos: si el comprobante se obtuvo correctamente, si es cancelable y bajo qué condiciones, en qué estado está, en qué punto va su cancelación (si la hay), y el resultado de la verificación del emisor contra las listas del artículo 69-B.
Cuándo se usa: después de solicitar una cancelación con CANCEL_XML_3 (para saber si se consumó); antes de solicitarla (para saber si el comprobante es cancelable) y, al recibir una factura de un proveedor (para verificar su estado y su validación EFOS).
Cuándo no usarla: no cancela nada, solo informa. Para solicitar la cancelación usa CANCEL_XML_3. Para recuperar el XML o el PDF de un comprobante, usa RETRIEVE_DOCUMENT.
Estado y EstatusCancelacion son dos cosas distintas. Un comprobante puede aparecer como Vigente y al mismo tiempo tener su cancelación En proceso. No se contradicen: el primero dice qué es el comprobante hoy ante el SAT, el segundo dice en qué punto va el trámite. Tu ERP debe leer los dos.CANCEL_XML_3 al solicitar la cancelación. Esto es información, no evidencia.| Si tu integración… | Tu artículo es... |
|---|---|
Consulta el estado de cancelación enviando un sobre SOAP con transactionName igual a CONSULT_DOCUMENT |
Este artículo |
Consulta enviando JSON al recurso /JsonServiceCall de API REST |
CONSULT_DOCUMENT — CFDI + Timbrado (API REST) - JsonServiceCall |
Consulta por RequestTransaction, con credenciales en cada petición |
CONSULTAR_DOCUMENTO — CFDI + Timbrado (API REST) - Request Transaction |
| Va a solicitar la cancelación de un CFDI | CANCEL_XML_3 — Servicio EndPoint |
AUTHENTICATE.docType.AUTHENTICATE, o toma el último que te devolvió la transacción anterior.docType.docType, emisor, folioFiscal, year y month. Serialízalo con la librería JSON de tu lenguaje.ws:JsonServiceCall y sus tres elementos hijos: ws:jsonData con el JSON, ws:transactionName con el literal CONSULT_DOCUMENT y ws:token con el token vigente.factwsfront.asmx del ambiente que te corresponda.JsonServiceCallResult y analízalo como JSON.Result, Payload, ErrorMsg, ErrorCode y Token.Result y comprueba que ErrorCode sea 0.Token de la respuesta, sustituyendo el anterior.Payload como texto JSON, sin decodificar desde Base64. Obtienes un objeto con ResponseData1, ResponseData2 y ResponseData3.ResponseData1 desde Base64 para obtener los cinco datos del estado en JSON. Es el más cómodo de procesar; ResponseData2 trae lo mismo en XML (basta con uno de los dos).CodigoEstatus, EsCancelable, Estado, EstatusCancelacion y ValidacionEFOS.Estado y EstatusCancelacion. Leer solo uno lleva a conclusiones equivocadas.Si algo falla, ve a Solución de problemas.
| Arquitectura | Híbrida. Sobre SOAP en la petición y en la respuesta; JSON crudo en la petición y JSON dentro del elemento de resultado en la respuesta |
|---|---|
| Versión de SOAP | SOAP 1.2 · espacio de nombres http://www.w3.org/2003/05/soap-envelope |
| Espacio de nombres del servicio | http://www.fact.com.mx/schema/ws |
| Operación SOAP | JsonServiceCall, dentro de soap:Body |
| Transacción | CONSULT_DOCUMENT, indicada en ws:transactionName |
| Naturaleza | Consulta ante la autoridad. No modifica el estado de ningún comprobante |
| Autenticación | Token en el elemento ws:token, obtenido con AUTHENTICATE |
| Consumo | No consume folios del paquete vigente |
ws:jsonData, ws:transactionName y ws:token aparecen como opcionales en el contrato del servicio, pero los tres son necesarios para que la transacción se ejecute.| Ambiente | URL |
|---|---|
| Pruebas | https://www.mysuitetest.com/mx.com.fact.wsfront/factwsfront.asmx |
| Producción | https://www.mysuitecfdi.com/mx.com.fact.wsfront/factwsfront.asmx |
| Elemento | Tipo | Obligatorio | Descripción |
|---|---|---|---|
ws:token |
string | Sí | Valor obtenido de la transacción AUTHENTICATE, o el último devuelto por cualquier transacción posterior |
No se envían credenciales por petición. El RFC del emisor del comprobante va dentro de jsonData, en el campo emisor.
| Elemento | Tipo | Obligatorio | Formato | Descripción |
|---|---|---|---|---|
ws:jsonData |
string | Sí | JSON crudo, escapado para XML | Objeto JSON con los criterios de la consulta. Ver apartado 5 |
ws:transactionName |
string | Sí | Literal | Transacción. Para ésta: CONSULT_DOCUMENT |
ws:token |
string | Sí | Texto | Valor obtenido de la transacción AUTHENTICATE |
{
"docType": "issued",
"emisor": "[RFC del emisor]",
"folioFiscal": "[UUID del CFDI]",
"year": "[año de emisión]",
"month": "[mes de emisión]"
}| Campo | Obligatorio | Formato | Descripción |
|---|---|---|---|
docType |
Sí | issued · received |
Tipo de documento que se quiere consultar: emitido o recibido |
emisor |
Sí | RFC | RFC del emisor de la factura cuyo estado de cancelación se consulta |
folioFiscal |
Sí | UUID | UUID del CFDI cuyo estado de cancelación se consulta (36 caracteres) |
year |
Sí | Año AAAA, entre comillas |
Año en que fue emitido el CFDI |
month |
Sí | Mes MM, entre comillas |
Mes en que fue emitido el CFDI |
| Carácter | Escapado como |
|---|---|
& |
& |
< |
< |
> |
> |
Aquí el riesgo es bajo, porque los criterios son un RFC, un UUID y tres valores cortos. Aun así conviene aplicar el escape de forma sistemática en toda la modalidad.
POST /mx.com.fact.wsfront/factwsfront.asmx HTTP/1.1
Host: www.mysuitetest.com
Content-Type: application/soap+xml; charset=utf-8
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:ws="http://www.fact.com.mx/schema/ws">
<soap:Header/>
<soap:Body>
<ws:JsonServiceCall>
<ws:jsonData>{
docType: "issued",
emisor: "JES900109Q90",
folioFiscal: "aa3aa9de-d88d-4fc0-9ec9-449838987abd",
year: "2026",
month: "10"
}</ws:jsonData>
<ws:transactionName>CONSULT_DOCUMENT</ws:transactionName>
<ws:token>[último token devuelto]</ws:token>
</ws:JsonServiceCall>
</soap:Body>
</soap:Envelope>Respuesta de una consulta exitosa, obtenida en el ambiente de pruebas:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<JsonServiceCallResponse xmlns="http://www.fact.com.mx/schema/ws">
<JsonServiceCallResult>
{"Result":true,
"Payload":"{\"ResponseData1\":\"eyJDb2RpZ29Fc3RhdHVzIjoiUyAtIENvbXByb2JhbnRlIG9idGVuaWRvIHNhdGlzZmFjdG9yaWFtZW50ZS4iLCJFc0NhbmNlbGFibGUiOiJDYW5jZWxhYmxlIGNvbiBhY2VwdGFjacOzbiIsIkVzdGFkbyI6IlZpZ2VudGUiLCJFc3RhdHVzQ2FuY2VsYWNpb24iOiJFbiBwcm9jZXNvIiwiVmFsaWRhY2lvbkVGT1MiOiIyMDAifQ==\",\"ResponseData2\":\"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjxBY3VzZSB4bWxuczp4c2Q9Imh0dHA6Ly93d3cudzMub3JnLzIwMDEvWE1MU2NoZW1hIiB4bWxuczp4c2k9Imh0dHA6Ly93d3cudzMub3JnLzIwMDEvWE1MU2NoZW1hLWluc3RhbmNlIj4NCiAgPEV4dGVuc2lvbkRhdGEgLz4NCiAgPENvZGlnb0VzdGF0dXM+UyAtIENvbXByb2JhbnRlIG9idGVuaWRvIHNhdGlzZmFjdG9yaWFtZW50ZS48L0NvZGlnb0VzdGF0dXM+DQogIDxFc0NhbmNlbGFibGU+Q2FuY2VsYWJsZSBjb24gYWNlcHRhY2nDs248L0VzQ2FuY2VsYWJsZT4NCiAgPEVzdGFkbz5WaWdlbnRlPC9Fc3RhZG8+DQogIDxFc3RhdHVzQ2FuY2VsYWNpb24+RW4gcHJvY2VzbzwvRXN0YXR1c0NhbmNlbGFjaW9uPg0KICA8VmFsaWRhY2lvbkVGT1M+MjAwPC9WYWxpZGFjaW9uRUZPUz4NCjwvQWN1c2U+\",\"ResponseData3\":\"\"}",
"ErrorMsg":"",
"ErrorCode":0,
"Token":"[token nuevo]"}
</JsonServiceCallResult>
</JsonServiceCallResponse>
</soap:Body>
</soap:Envelope>Contenido de ResponseData1 una vez decodificado:
{
"CodigoEstatus":"S - Comprobante obtenido satisfactoriamente.",
"EsCancelable":"Cancelable con aceptación",
"Estado":"Vigente",
"EstatusCancelacion":"En proceso",
"ValidacionEFOS":"200"
}El mismo contenido en ResponseData2, una vez decodificado:
<?xml version="1.0" encoding="utf-8"?>
<Acuse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ExtensionData />
<CodigoEstatus>S - Comprobante obtenido satisfactoriamente.</CodigoEstatus>
<EsCancelable>Cancelable con aceptación</EsCancelable>
<Estado>Vigente</Estado>
<EstatusCancelacion>En proceso</EstatusCancelacion>
<ValidacionEFOS>200</ValidacionEFOS>
</Acuse>Dentro de JsonServiceCallResult viaja un objeto JSON plano de cinco campos, en PascalCase.
| Campo | Tipo | Contenido |
|---|---|---|
Result |
booleano | Indica si la transacción fue exitosa |
Payload |
string | Cadena de texto que contiene un JSON. No viene en Base64. Ver desglose siguiente |
Token |
string | Token nuevo para la siguiente llamada |
ErrorCode |
entero | Código de error. 0 significa que no hubo error |
ErrorMsg |
string | Descripción del error. Llega vacío en caso exitoso |
Payload no está codificado en esta transacción. Llega como texto JSON escapado dentro del campo: lo que necesitas es analizarlo, no decodificarlo. Es el mismo comportamiento que en CANCEL_XML_3, y distinto del de las demás transacciones de la modalidad, donde Payload sí viene en Base64. Las dos transacciones del flujo de cancelación rompen el patrón del resto.Payload| Elemento | Codificación | Contenido |
|---|---|---|
ResponseData1 |
Base64 | Estructura en formato JSON del resultado de la consulta de estado de cancelación |
ResponseData2 |
Base64 | La misma estructura en formato XML: el elemento Acuse |
ResponseData3 |
— | Vacío |
ResponseData1 es el más cómodo si trabajas con JSON.ResponseData1, ResponseData2 y ResponseData3 son la nomenclatura de RequestTransaction, no la propia de esta modalidad. Ocurre igual en CANCEL_XML_3: las dos transacciones del flujo de cancelación devuelven la respuesta de la otra vía envuelta en el sobre de ésta.| Campo | Qué responde | Valores observados |
|---|---|---|
CodigoEstatus |
Si la consulta localizó el comprobante ante el SAT. Es el resultado de la consulta, no del comprobante | S - Comprobante obtenido satisfactoriamente; Código y Descripción. |
EsCancelable |
Si el comprobante admite cancelación y bajo qué condiciones. Determina si el trámite requerirá la aceptación del receptor | Valores: Cancelable sin aceptación o Cancelable con aceptación |
Estado |
Qué es el comprobante hoy ante el SAT | Estado del CFDI ante el SAT: Vigente o Cancelado |
EstatusCancelacion |
En qué punto va el trámite de cancelación, si existe alguno. Vacío cuando no se ha solicitado | Valores: En proceso, No Cancelable, Cancelado sin aceptación, Cancelado con aceptación, Cancelado plazo vencido y Solicitud rechazada |
ValidacionEFOS |
Resultado de la verificación del emisor contra las listas del artículo 69-B del Código Fiscal de la Federación | Valores:
Código= 100 Este código de respuesta se presentará cuando la validación del RFC Emisor del CFDI se encuentre dentro de la lista de Empresa que Factura Operaciones Simuladas (EFOS)Código=200 Este código de respuesta se presentará cuando la validación del RFC Emisor del CFDI no se encuentre dentro de la lista de Empresa que Factura Operaciones Simuladas (EFOS). |
Estado y EstatusCancelacion juntos. Pueden valer Vigente y En proceso a la vez, y no es contradictorio: el comprobante sigue surtiendo efectos mientras el trámite avanza. Un ERP que decida solo con Estado tratará como plenamente vigente un comprobante cuya cancelación ya está en curso; uno que decida solo con EstatusCancelacion lo dará por cancelado antes de tiempo.No cancelable. Significa que el comprobante no admite cancelación en absoluto, lo que es distinto de requerir la aceptación del receptor. Consultarlo antes de intentar la cancelación evita una solicitud condenada a fallar.| Campo | Contenido en error |
|---|---|
Result |
false |
ErrorCode |
Código distinto de 0. Ver apartado 10 |
ErrorMsg |
Descripción del error |
Payload |
null |
Token |
null, conservar el token anterior tras un fallo |
Result dice si la consulta se ejecutó; CodigoEstatus dice si el SAT localizó el comprobante; Estado dice qué es el comprobante. Un error de consulta no significa que el comprobante no exista, y un comprobante no localizado no significa que la consulta haya fallado.| Código | Significado | Causa | Remedio |
|---|---|---|---|
0 |
Sin error | La consulta se ejecutó. El estado se lee en Payload |
— |
101 |
Token expirado | La vida del token expiró | Autenticarte de nuevo con AUTHENTICATE y reintentar |
102 |
Token inválido | Al desencriptar y analizar la información de autenticación, la operación falla | Revisar que envíes el último token devuelto, completo y sin alterar |
| Aspecto | Valor |
|---|---|
| Comprobantes por llamada | Uno. El criterio es un único folioFiscal |
| Alcance | Comprobantes emitidos y recibidos, según docType, del ambiente en que consultas |
| Efectos | Ninguno. No cancela, no modifica y no notifica |
| Idempotencia | Es una consulta: reintentarla no tiene efectos colaterales |
| Consumo de folios | No consume folios del paquete vigente |
| Frecuencia recomendada de consulta | En MYSuite realizamos una consulta de manera automática cada 24 horas (una vez que se solicitó cancelar un CFDI) |
| Timeout | 60 segundos en servidor front |
CANCEL_XML_3: sin ella no hay forma de saber si una cancelación se consumó.ValidacionEFOS remite al artículo 69-B del Código Fiscal de la Federación, que tiene consecuencias sobre la deducibilidad de los comprobantes del emisor..asmx que atiende EndPoint es el mismo que atiende la modalidad SOAP clásica. Un cambio en ese servicio afecta a ambas modalidades.Problema. El intento de decodificar Payload desde Base64 produce un error o un valor sin sentido, aunque la misma rutina funciona en otras transacciones de la modalidad.
Entorno. EndPoint · integraciones que usan varias transacciones.
Resolución. En esta transacción Payload no viene codificado: es una cadena de texto que contiene un JSON escapado. Analízala directamente. Después sí tendrás que decodificar ResponseData1 o ResponseData2, que vienen ambos en Base64.
Causa. El tratamiento de Payload no es uniforme en esta modalidad: aquí y en CANCEL_XML_3 llega sin codificar; en las demás, en Base64.
Problema. La petición se procesa correctamente pese a que el jsonData no pasa la validación de un analizador estándar.
Entorno. EndPoint · integraciones que partieron de los ejemplos del portal.
Resolución. El analizador de la plataforma es tolerante y acepta desviaciones como las claves sin comillas. Eso explica por qué varios ejemplos del portal parecen funcionar. Aun así, serializa con la librería JSON de tu lenguaje: esa tolerancia no está declarada, no forma parte del contrato y puede retirarse sin aviso, y el día que eso ocurra tu integración dejará de funcionar sin que hayas cambiado nada.
Causa. Comportamiento no documentado del analizador.
Problema. La respuesta parece contradictoria y el ERP no sabe qué estado asignar al comprobante.
Entorno. EndPoint · seguimiento de cancelaciones.
Resolución. No es contradictorio. Estado dice qué es el comprobante hoy ante el SAT, y EstatusCancelacion dice en qué punto va el trámite. Mientras la cancelación avanza, el comprobante sigue vigente. Contempla en tu ERP un tercer estado, del tipo «cancelación solicitada».
Causa. Se esperaba un único campo de estado. La cancelación bajo el esquema Vigente es un proceso, no un acto instantáneo.
Problema. La solicitud de cancelación falla y no queda claro por qué.
Entorno. EndPoint · flujo de cancelación.
Resolución. Consulta primero el estado con esta transacción y revisa EsCancelable. Si devuelve No cancelable, el comprobante no admite cancelación y la solicitud estaba condenada a fallar. Si indica que requiere aceptación del receptor, la demora es parte del procedimiento y no hay nada que corregir del lado técnico.
Causa. Se solicitó la cancelación sin comprobar antes si el comprobante la admitía.
Problema. La respuesta trae un valor en ValidacionEFOS y el proceso no sabe qué hacer con él.
Entorno. EndPoint · recepción de facturas de proveedores.
Problema. El código que recorre la respuesta buscando elementos XML no localiza Result, Payload ni los demás.
Entorno. EndPoint · integraciones nuevas, o migradas desde la modalidad SOAP.
Resolución. No son elementos XML. El contenido de JsonServiceCallResult es una cadena de texto que contiene un objeto JSON. Extrae esa cadena y analízala con tu librería JSON.
Causa. EndPoint es una modalidad híbrida: sobre SOAP, contenido JSON.
Problema. El proceso archiva la respuesta de esta consulta como evidencia del trámite.
Entorno. EndPoint · resguardo documental.
Resolución. Lo que devuelve esta transacción no viene firmado digitalmente por el SAT, así que en sentido legal no es un acuse. El documento con valor probatorio es el que devuelve CANCEL_XML_3 al solicitar la cancelación. Guarda aquél; éste úsalo como información operativa.
Causa. El elemento se llama Acuse en el XML, lo que induce a tratarlo como tal.
Solicitar una cancelación y saber si se consumó son dos operaciones distintas porque, bajo el esquema Vigente, cancelar dejó de ser un acto instantáneo. La solicitud se presenta, el SAT la gestiona y, en varios supuestos, el receptor puede oponerse. Entre la solicitud y el desenlace hay un intervalo que puede durar días, y durante ese intervalo el comprobante sigue surtiendo efectos. Sin esta consulta, el emisor no tiene forma de saber en qué quedó el trámite.
Estado responde «qué es este comprobante ahora» y EstatusCancelacion responde «qué está pasando con él». Un solo campo no puede decir ambas cosas: si colapsara las dos, un comprobante con cancelación en curso tendría que aparecer como vigente —ocultando el trámite— o como cancelado —afirmando algo falso—. La separación es la que permite que un ERP represente correctamente la situación intermedia.
La consecuencia de diseño para quien integra es que el modelo de datos necesita un tercer estado. Los sistemas que solo contemplan vigente y cancelado terminan forzando la realidad para que quepa en dos casillas.
El campo EsCancelable dice de antemano si el comprobante admite cancelación y bajo qué condiciones. Que exista un valor No cancelable lo hace especialmente útil: distingue entre un trámite que va a tardar porque depende del receptor y uno que no va a ocurrir en absoluto. Consultarlo antes de solicitar cambia la expectativa del proceso y evita escalamientos por algo que la respuesta ya anticipaba.
El XML que devuelve se llama Acuse, pero no viene firmado por el SAT. La distinción importa cuando hay que demostrar algo: el acuse de la solicitud de cancelación sí está sellado por la autoridad y sirve como evidencia de que el trámite se presentó en una fecha determinada; éste es una fotografía del estado en el momento de preguntar, útil para operar pero no para probar.
ValidacionEFOS no habla del comprobante sino de quien lo emitió: verifica al emisor contra las listas del artículo 69-B del Código Fiscal, que señalan a contribuyentes con operaciones presuntamente inexistentes. Que venga incluido en una consulta de estado de cancelación es casi un efecto colateral afortunado, porque convierte esta transacción en una herramienta de revisión de proveedores además de una de seguimiento. Para un área de cuentas por pagar, ese dato puede ser el más valioso de los cinco.
El mismo contenido llega en JSON y en XML, cada uno en su propio campo. No hay diferencia de información entre ambos: es una cortesía hacia integraciones construidas con herramientas distintas. Lo único que conviene evitar es leer los dos, que duplica el trabajo sin añadir nada.
La transacción es la misma operación de negocio en las cuatro modalidades: mismos criterios, mismos cinco campos de respuesta. Lo que cambia es todo lo que rodea al dato: el modelo de credenciales, el formato de los criterios, su codificación y la nomenclatura de la respuesta. Documentarlas juntas obligaría al lector a descartar tres cuartas partes del contrato técnico en cada consulta, y es precisamente donde se originan los errores de integración.