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ó la cancelación); antes de solicitarla (para saber si el comprobante es cancelable y si requerirá la aceptación del receptor); 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.AUTHENTICATE, y el token rota en cada llamada: la petición siguiente debe usar el último token devuelto.| Si tu integración… | Tu artículo es... |
|---|---|
Consulta el estado de cancelación de un CFDI por JsonServiceCall, con token |
Este artículo |
Consulta lo mismo por RequestTransaction, con credenciales en cada petición |
CONSULTAR_DOCUMENTO — CFDI + Timbrado (API REST) - Request Transaction |
Hace lo mismo enviando un sobre SOAP a FactWSFront |
CONSULTAR_DOCUMENTO — CFDI + Timbrado (SOAP) |
| Va a solicitar la cancelación de un CFDI | CANCEL_XML_3 — CFDI + Timbrado (API REST) - JsonServiceCall |
| Necesita el XML o el PDF del comprobante | RETRIEVE_DOCUMENT — CFDI + Timbrado (API REST) - JsonServiceCall |
AUTHENTICATE.docType.AUTHENTICATE, o toma el último que te devolvió la transacción anterior.docType, issued o received.docType, emisor, folioFiscal, year y month. Serialízalo con la librería JSON de tu lenguaje.jsonData.jsonData con esa cadena, token con el token vigente y transactionName con el literal CONSULT_DOCUMENT./JsonServiceCall.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 y basta con uno de los dos.CodigoEstatus, EsCancelable, Estado, EstatusCancelacion y ValidacionEFOS.Estado dice qué es el comprobante hoy y EstatusCancelacion dice en qué punto va el trámite. Leer solo uno lleva a conclusiones equivocadas.Si algo falla, ve a Solución de problemas.
| Protocolo | HTTP/1.1 sobre HTTPS · arquitectura REST con cuerpo JSON |
|---|---|
| Recurso | /JsonServiceCall |
| Método | POST |
| Content-Type | application/json |
| Campo que selecciona la transacción | transactionName, con el valor CONSULT_DOCUMENT |
| Naturaleza | Consulta ante la autoridad. No modifica el estado de ningún comprobante |
| Autenticación | Token en el cuerpo, obtenido con AUTHENTICATE |
| Consumo |
No consume folio del paquete vigente
|
| Ambiente | URL |
|---|---|
| Pruebas | https://api.mysuitetest.com/JsonServiceCall |
| Producción | https://api.mysuitecfdi.com/JsonServiceCall |
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
token |
string | Sí | Valor obtenido de AUTHENTICATE, o el último devuelto por cualquier transacción posterior |
token en null. Tras un fallo conserva el token que ya tenías. No se envían Country, Entity ni UserName. El RFC del emisor del comprobante va dentro de jsonData, en el campo emisor.
| Campo | Tipo | Obligatorio | Formato | Descripción |
|---|---|---|---|---|
jsonData |
string | Sí | Base64 | Los datos en forma de objeto JSON que conforman la materia prima para solicitar el estado de cancelación de un CFDI ante el SAT. Ver apartado 5 |
token |
string | Sí | Texto | Token de seguridad vigente |
transactionName |
string | Sí | Literal | Transacción. Para esta: CONSULT_DOCUMENT |
{
"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 |
Año en que fue emitido el CFDI |
month |
Sí | Mes MM |
Mes en que fue emitido el CFDI |
year y month como cadenas. POST /JsonServiceCall HTTP/1.1
Host: api.mysuitetest.com
Content-Type: application/json
{
"jsonData": "ewogICAgZG9jVHlwZTogImlzc3VlZCIsCiAgICBlbWlzb3I6ICJKRVM5MDAxMDlROTAiLCAgIAogICAgZm9saW9GaXNjYWw6ICIgMmM4MjcxZGUtYmMyNi00MThhLTg3YWYtYzc5ZDcxY2YyMTE3IiwKICAgIHllYXI6ICIyMDI2IiwKICAgIG1vbnRoOiAiMDUiCn0=",
"token": "OxbZPD1Gd9hUomWYNBUGWkzja54cEGlnz9LLPKZY+pI0+bfE1ldh8TKjBK02xvy5Wk/9aExJIGxIvrXhoAm2ewGlECiO5cDfLIXuMajbIcs=",
"transactionName": "CONSULT_DOCUMENT"
}{
"result": true,
"payload": "{\"ResponseData1\":\"eyJDb2RpZ29Fc3RhdHVzIjoiUyAtIENvbXByb2JhbnRlIG9idGVuaWRvIHNhdGlzZmFjdG9yaWFtZW50ZS4iLCJFc0NhbmNlbGFibGUiOiJDYW5jZWxhYmxlIHNpbiBhY2VwdGFjacOzbiIsIkVzdGFkbyI6IlZpZ2VudGUiLCJFc3RhdHVzQ2FuY2VsYWNpb24iOiJFbiBwcm9jZXNvIiwiVmFsaWRhY2lvbkVGT1MiOiIyMDAifQ==\",\"ResponseData2\":\"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjxBY3VzZSB4bWxuczp4c2k9Imh0dHA6Ly93d3cudzMub3JnLzIwMDEvWE1MU2NoZW1hLWluc3RhbmNlIiB4bWxuczp4c2Q9Imh0dHA6Ly93d3cudzMub3JnLzIwMDEvWE1MU2NoZW1hIj4NCiAgPEV4dGVuc2lvbkRhdGEgLz4NCiAgPENvZGlnb0VzdGF0dXM+UyAtIENvbXByb2JhbnRlIG9idGVuaWRvIHNhdGlzZmFjdG9yaWFtZW50ZS48L0NvZGlnb0VzdGF0dXM+DQogIDxFc0NhbmNlbGFibGU+Q2FuY2VsYWJsZSBzaW4gYWNlcHRhY2nDs248L0VzQ2FuY2VsYWJsZT4NCiAgPEVzdGFkbz5WaWdlbnRlPC9Fc3RhZG8+DQogIDxFc3RhdHVzQ2FuY2VsYWNpb24+RW4gcHJvY2VzbzwvRXN0YXR1c0NhbmNlbGFjaW9uPg0KICA8VmFsaWRhY2lvbkVGT1M+MjAwPC9WYWxpZGFjaW9uRUZPUz4NCjwvQWN1c2U+\",\"ResponseData3\":\"\"}",
"token": "OxbZPD1Gd9hUomWYNBUGWkzja54cEGlnz9LLPKZY+pI0+bfE1ldh8TKjBK02xvy5Wk/9aExJIGxIvrXhoAm2e1CdNL9QjX4g9mTcS7/nP0k=",
"errorMsg": "",
"errorCode": 0
}El cuerpo es un objeto JSON de cinco campos, el mismo sobre que usan todas las transacciones de esta vía.
| 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 directo: lo que necesitas es analizarlo, no decodificarlo. payload
| Elemento | Codificación | Contenido |
|---|---|---|
ResponseData1 |
Base64 | Estructura en formato JSON del resultado de la solicitud de estado de cancelación realizada |
ResponseData2 |
Base64 | La misma estructura pero en formato XML. Elemento Acuse |
ResponseData3 |
— | Vacío |
ResponseData1 es el más cómodo si trabajas con JSON.CANCEL_XML_3, la transacción que se invoca justo antes en este flujo. Allí ResponseData2 llega en texto plano; aquí llega en Base64.{
"CodigoEstatus": "S - Comprobante obtenido satisfactoriamente.",
"EsCancelable": "Cancelable sin aceptación",
"Estado": "Vigente",
"EstatusCancelacion": "En proceso",
"ValidacionEFOS": "200"
}El mismo contenido en XML, dentro de ResponseData2:
<?xml version="1.0" encoding="utf-8"?>
<Acuse ...>
<ExtensionData />
<CodigoEstatus>...</CodigoEstatus>
<EsCancelable>...</EsCancelable>
<Estado>...</Estado>
<EstatusCancelacion>...</EstatusCancelacion>
<ValidacionEFOS>...</ValidacionEFOS>
</Acuse>| Campo | Qué responde | Valor observado |
|---|---|---|
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.| Campo | Contenido en error |
|---|---|
result |
false |
errorCode |
Código distinto de 0. Ver apartado 10 |
errorMsg |
Descripción del error |
payload |
null |
token |
null. Conserva el token anterior: en error no se renueva |
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 | Venció el tiempo de vida del token | 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 el servidor front |
CANCEL_XML_3: sin ella no hay forma de saber si una cancelación se consumó.CancelaCFDResult que entrega la solicitud de cancelación. Conserva aquél, no éste.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.Problema. La consulta no localiza un comprobante que sí existe.
Entorno. CFDI + Timbrado · API REST · JsonServiceCall.
Resolución. Revisa el valor de folioFiscal carácter por carácter: un espacio inicial o final invalida la búsqueda sin producir un mensaje claro, y es un error fácil de heredar al copiar el UUID desde una hoja de cálculo o desde el ejemplo del portal. Verifica después que docType corresponda — issued si lo emitiste tú, received si te lo emitieron— y que el año y el mes sean los de emisión del comprobante, no los del mes en curso.
Causa. El espacio sobrante en el UUID es la causa más silenciosa de las tres.
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 vía.
Entorno. CFDI + Timbrado · API REST · JsonServiceCall · integraciones que usan varias transacciones.
Resolución. En esta transacción payload no viene codificado: es una cadena de texto que contiene un JSON. 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 vía: aquí y en CANCEL_XML_3 llega sin codificar; en las demás, en Base64.
Problema. La capa que lee ResponseData2 deja de funcionar al pasar de CANCEL_XML_3 a esta transacción.
Entorno. CFDI + Timbrado · API REST · JsonServiceCall · flujo completo de cancelación.
Resolución. En CANCEL_XML_3, ResponseData2 llega en texto plano; aquí llega en Base64. Es la misma posición de campo con codificación distinta en dos transacciones que se usan una detrás de otra. Escribe una capa de lectura por transacción.
Causa. Las dos transacciones del flujo de cancelación no comparten convención de codificación.
Problema. La respuesta parece contradictoria y el ERP no sabe qué estado asignar al comprobante.
Entorno. CFDI + Timbrado · API REST · JsonServiceCall · 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.
Causa. Se esperaba un único campo de estado. La cancelación bajo el esquema Vigente es un proceso, no un acto instantáneo, y por eso necesita dos campos para describirse.
Problema. La respuesta trae un valor en ValidacionEFOS y el proceso no sabe qué hacer con él.
Entorno. CFDI + Timbrado · API REST · JsonServiceCall · recepción de facturas de proveedores.
Problema. La cancelación no avanza y el proceso no sabe si esperar o escalar.
Entorno. CFDI + Timbrado · API REST · JsonServiceCall · seguimiento de cancelaciones.
Resolución. Revisa el valor de EsCancelable: si el comprobante requiere la aceptación del receptor, el trámite depende de que éste responda o de que venza el plazo para hacerlo, y no hay nada que corregir del lado técnico. Si indica que es cancelable sin aceptación y aun así no avanza, escala a Soporte.
Causa. El esquema Vigente da derecho al receptor a oponerse en varios supuestos, y en esos casos la demora es parte del procedimiento.
Problema. El proceso archiva la respuesta de esta consulta como evidencia del trámite.
Entorno. CFDI + Timbrado · API REST · JsonServiceCall · 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 acuse CancelaCFDResult que devuelve CANCEL_XML_3 al solicitar la cancelación, y ése sí trae el sello del SAT. 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. El propio portal advierte que no lo es.
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.
El campo EsCancelable dice de antemano si el comprobante admite cancelación y si requerirá la aceptación del receptor. Consultarlo antes de solicitar cambia la expectativa del proceso: si el trámite va a depender de un tercero, conviene saberlo al iniciarlo y no cuatro días después, cuando alguien pregunta por qué sigue en proceso.
El XML que devuelve se llama Acuse, pero no viene firmado por el SAT, y el propio portal lo advierte. 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. Conviene archivar el primero y tratar el segundo como información.
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. Quien trabaja con JSON procesa el primero; quien tiene una canalización basada en XML usa el segundo. 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 los tres transportes: 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, la nomenclatura de la respuesta y su codificación. Documentarlos juntos obligaría al lector a descartar dos tercios del contrato técnico en cada consulta, y es precisamente donde se originan los errores de integración.
Vía RequestTransaction