CONSULT_DOCUMENT — SERVICIO CFDI + Timbrado (API REST) - JsonServiceCall

CONSULT_DOCUMENT — SERVICIO CFDI + Timbrado (API REST) - JsonServiceCall

Estado Transacción: Vigente · Compatibilidad: Esquema de cancelación Vigente · Última revisión: 09/10/2026 · Próxima revisión: 09/01/2027 · Responsable: Jan Martínez


De un vistazo


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.
Lo que devuelve esta transacción no es un acuse en sentido legal, porque no viene firmado digitalmente por el SAT. El acuse firmado es el que entrega CANCEL_XML_3 al solicitar la cancelación. Esto es información, no evidencia.
Necesitas un token. Esta vía exige autenticarse primero con AUTHENTICATE, y el token rota en cada llamada: la petición siguiente debe usar el último token devuelto.


Cómo saber si este es tu artículo

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


Requisitos previos

  • Un token vigente, obtenido con AUTHENTICATE.
  • El Folio Fiscal (UUID) del comprobante y el RFC de su emisor.
  • El año y el mes de emisión.
  • Saber si el comprobante es emitido o recibido, porque cambia el valor de docType.


Cómo hacerlo

  1. Obtén un token con AUTHENTICATE, o toma el último que te devolvió la transacción anterior.
    Resultado: el token con el que vas a autenticar esta llamada.
  2. Determina si el comprobante es emitido o recibido: define el valor de docType, issued o received.
    Resultado: el tipo de documento que vas a consultar.
  3. Reúne el RFC del emisor, el UUID del comprobante, el año y el mes en que se emitió.
    Resultado: los criterios de la consulta.
  4. Construye el objeto JSON con docType, emisor, folioFiscal, year y month. Serialízalo con la librería JSON de tu lenguaje.
    Resultado: un JSON válido de cinco campos, sin espacios sobrantes dentro de los valores.
  5. Codifica ese objeto en Base64, sin saltos de línea intermedios.
    Resultado: la cadena que vas a poner en jsonData.
  6. Arma el cuerpo de la petición con los tres campos: jsonData con esa cadena, token con el token vigente y transactionName con el literal CONSULT_DOCUMENT.
    Resultado: petición lista.
  7. Envía la petición al recurso /JsonServiceCall.
    Resultado: respuesta con un cuerpo JSON de cinco campos.
  8. Lee result y comprueba que errorCode sea 0.
    Resultado: confirmación de que la consulta se ejecutó; cualquier otro valor te lleva a Solución de problemas.
  9. Guarda el nuevo token de la respuesta, sustituyendo el anterior.
    Resultado: sesión viva para la siguiente llamada.
  10. Interpreta payload como texto JSON, sin decodificar desde Base64. Obtienes un objeto con ResponseData1, ResponseData2 y ResponseData3.
    Resultado: los dos formatos del resultado, todavía codificados.
  11. Decodifica 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.
    Resultado: CodigoEstatus, EsCancelable, Estado, EstatusCancelacion y ValidacionEFOS.
  12. Evalúa juntos los dos campos que importan: Estado dice qué es el comprobante hoy y EstatusCancelacion dice en qué punto va el trámite. Leer solo uno lleva a conclusiones equivocadas.
    Resultado: el estado real del comprobante.
  13. Actualiza tu ERP con el resultado, y repite la consulta más adelante si la cancelación sigue en proceso.
    Resultado: estado conciliado contra el SAT, no supuesto.

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
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


2. Ambientes

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


3. Autenticación

Campo Tipo Obligatorio Descripción
token string Sí Valor obtenido de AUTHENTICATE, o el último devuelto por cualquier transacción posterior
El token rota, y en error no se renueva. Cada transacción exitosa devuelve un token nuevo que sustituye al anterior, pero una respuesta de error devuelve 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.


4. Parámetros de entrada

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


5. Estructura de lo que se envía en jsonData

{
"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
Envía year y month como cadenas.  


6. Ejemplo de request

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

{
"jsonData": "ewogICAgZG9jVHlwZTogImlzc3VlZCIsCiAgICBlbWlzb3I6ICJKRVM5MDAxMDlROTAiLCAgIAogICAgZm9saW9GaXNjYWw6ICIgMmM4MjcxZGUtYmMyNi00MThhLTg3YWYtYzc5ZDcxY2YyMTE3IiwKICAgIHllYXI6ICIyMDI2IiwKICAgIG1vbnRoOiAiMDUiCn0=",
"token": "OxbZPD1Gd9hUomWYNBUGWkzja54cEGlnz9LLPKZY+pI0+bfE1ldh8TKjBK02xvy5Wk/9aExJIGxIvrXhoAm2ewGlECiO5cDfLIXuMajbIcs=",
"transactionName": "CONSULT_DOCUMENT"
}


7. Ejemplo de response

{
"result": true,
"payload": "{\"ResponseData1\":\"eyJDb2RpZ29Fc3RhdHVzIjoiUyAtIENvbXByb2JhbnRlIG9idGVuaWRvIHNhdGlzZmFjdG9yaWFtZW50ZS4iLCJFc0NhbmNlbGFibGUiOiJDYW5jZWxhYmxlIHNpbiBhY2VwdGFjacOzbiIsIkVzdGFkbyI6IlZpZ2VudGUiLCJFc3RhdHVzQ2FuY2VsYWNpb24iOiJFbiBwcm9jZXNvIiwiVmFsaWRhY2lvbkVGT1MiOiIyMDAifQ==\",\"ResponseData2\":\"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjxBY3VzZSB4bWxuczp4c2k9Imh0dHA6Ly93d3cudzMub3JnLzIwMDEvWE1MU2NoZW1hLWluc3RhbmNlIiB4bWxuczp4c2Q9Imh0dHA6Ly93d3cudzMub3JnLzIwMDEvWE1MU2NoZW1hIj4NCiAgPEV4dGVuc2lvbkRhdGEgLz4NCiAgPENvZGlnb0VzdGF0dXM+UyAtIENvbXByb2JhbnRlIG9idGVuaWRvIHNhdGlzZmFjdG9yaWFtZW50ZS48L0NvZGlnb0VzdGF0dXM+DQogIDxFc0NhbmNlbGFibGU+Q2FuY2VsYWJsZSBzaW4gYWNlcHRhY2nDs248L0VzQ2FuY2VsYWJsZT4NCiAgPEVzdGFkbz5WaWdlbnRlPC9Fc3RhZG8+DQogIDxFc3RhdHVzQ2FuY2VsYWNpb24+RW4gcHJvY2VzbzwvRXN0YXR1c0NhbmNlbGFjaW9uPg0KICA8VmFsaWRhY2lvbkVGT1M+MjAwPC9WYWxpZGFjaW9uRUZPUz4NCjwvQWN1c2U+\",\"ResponseData3\":\"\"}",
"token": "OxbZPD1Gd9hUomWYNBUGWkzja54cEGlnz9LLPKZY+pI0+bfE1ldh8TKjBK02xvy5Wk/9aExJIGxIvrXhoAm2e1CdNL9QjX4g9mTcS7/nP0k=",
"errorMsg": "",
"errorCode": 0
}


8. Estructura de respuesta — éxito

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. 


Contenido de 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
Los dos primeros traen lo mismo en dos formatos. No hace falta leer ambos: elige uno. ResponseData1 es el más cómodo si trabajas con JSON.
Diferencia con CANCEL_XML_3, la transacción que se invoca justo antes en este flujo. Allí ResponseData2 llega en texto plano; aquí llega en Base64.


Los cinco campos del estado

{
"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).
Lee 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.


9. Estructura de respuesta — error

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
Tres señales distintas, no una. 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.


10. Códigos de Error


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
Aquí todos los códigos son seguros de reintentar. Es una consulta: reintentarla no produce efectos sobre ningún comprobante.


11. Límites y comportamiento

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


12. Versionado y cumplimiento

  • Esta transacción forma parte del esquema de cancelación Vigente y es el complemento obligado de CANCEL_XML_3: sin ella no hay forma de saber si una cancelación se consumó.
  • Lo que devuelve no es un acuse en sentido legal, porque no viene firmado digitalmente por el SAT. El documento con valor probatorio es el acuse CancelaCFDResult que entrega la solicitud de cancelación. Conserva aquél, no éste.
  • Los valores de los cinco campos los define el SAT, no MYSuite: la plataforma los traslada.
  • 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.

Solución de problemas

"No encuentra el comprobante y los datos parecen correctos"


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.

"No puedo decodificar el payload"


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.

"Mi código funcionaba con la solicitud de cancelación y aquí falla"


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.

"Me dice Vigente y En proceso al mismo tiempo"


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.

"No sé qué significa la validación EFOS"


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.

Resolución. Es el resultado de verificar al emisor contra las listas del artículo 69-B del Código Fiscal de la Federación, que señalan a contribuyentes con operaciones presuntamente inexistentes. Tiene consecuencias sobre la deducibilidad de sus comprobantes, así que conviene registrarlo y escalarlo al área fiscal, no descartarlo. 
Causa. El campo no viene documentado en el artículo fuente más allá de su nombre.

"Llevo días consultando y sigue en proceso"


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.

"Quiero guardar esto como comprobante de la cancelación"


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.


Para entender más

Por qué esta consulta es obligatoria y no opcional

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.

Por qué hacen falta dos campos para describir el estado

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.

Por qué conviene consultar antes de cancelar, no solo después

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.

Qué hace esta respuesta y qué no hace

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.

Un campo que hace más de lo que parece

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.

Por qué el resultado viene en dos formatos

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.

Por qué cada vía se documenta por separado

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.


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