Qué hace: busca los CFDI almacenados en MYSuite que coinciden con una Serie y un Folio determinados, y te devuelve cuántos encontró junto con el detalle de cada uno. La Serie y el Folio pueden venir del XML nativo que enviaste al timbrar o de la asignación configurada en el Portal Web de MYSuite.
Cuándo se usa: cuando tu sistema administrativo lleva el control de los comprobantes por Serie y Folio en lugar del Folio Fiscal, y necesitas localizar uno o verificar su existencia con esos datos.
Cuándo no usarla: esta transacción no devuelve los comprobantes, solo un conteo y su detalle resumido. Para obtener el XML o el PDF usa RETRIEVE_DOCUMENT. Si lo que conoces es el Número Interno de tu sistema, usa LOOKUP_ISSUED_INTERNAL_ID.
| Si tu integración… | Tu artículo es... |
|---|---|
| Busca por Serie y Folio enviando un cuerpo JSON por HTTP POST | Este artículo |
Busca por Serie y Folio enviando un sobre SOAP a FactWSFront |
LOOKUP_ISSUED_YEAR_BATCH_AND_SERIAL — CFDI + Timbrado (SOAP) |
| Conoce el Número Interno de tu sistema administrativo | LOOKUP_ISSUED_INTERNAL_ID — CFDI + Timbrado (API REST) - Request Transaction |
| Necesita el XML o el PDF de un comprobante ya identificado enviando un sobre SOAP a FactWSFront |
RETRIEVE_DOCUMENT — CFDI + Timbrado (API REST) - Request Transaction |
| Va a emitir un CFDI a partir de un XML Nativo | CONVERT_NATIVE_XML — CFDI + Timbrado (API REST) - Request Transaction |
Requestor y Entity.Dictionary con el atributo name igual a StoredXmlSelector y las cuatro entradas Batch, Serial, Branch y Year.Data1.Transaction con valor LOOKUP_ISSUED_YEAR_BATCH_AND_SERIAL, la cadena Base64 en Data1, Data2 y Data3 como cadenas vacías.POST al recurso /RequestTransaction con Content-Type: application/json.responseField.resultField.resultField = true indica que la consulta se ejecutó; resultField = false te lleva a Solución de problemas.responseDataField.responseData1Field tal cual: contiene la cantidad de comprobantes encontrados, como cadena.responseDataField.responseData2Field desde Base64 si el conteo es mayor que 0.DocsFoundBy con el detalle de cada comprobante localizado.uuid del detalle.issued, total y cancelled, o acota la búsqueda por Sucursal.Si algo falla, ve a Solución de problemas.
| 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 |
LOOKUP_ISSUED_YEAR_BATCH_AND_SERIAL |
| Naturaleza | Consulta. No modifica el estado de ningún comprobante |
| Ambiente | URL |
|---|---|
| Pruebas | https://api.mysuitetest.com/RequestTransaction |
| Producción | https://api.mysuitecfdi.com/RequestTransaction |
JES900109Q90 como RFC solicitante (Entity). La consulta solo alcanza a los comprobantes emitidos bajo ese emisor y en ese ambiente: una Serie y Folio timbrados en pruebas no se encuentran en producción, ni al contrario.Esta modalidad 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 proporciona MYSuite, relacionado con la seguridad de la transacción, con los procesos de autenticación y autorización |
Transaction |
string | Sí | Literal en mayúsculas | Método que quieres invocar. Para esta transacción: LOOKUP_ISSUED_YEAR_BATCH_AND_SERIAL |
Country |
string | Sí | Valor fijo MX |
Abreviatura del país |
Entity |
string | Sí | RFC (12–13 caracteres) | RFC de quien realiza la solicitud, la empresa que consulta desde su ERP. En test JES900109Q90 |
User |
string | Sí | GUID | Se repite el valor de Requestor |
UserName |
string | Sí | Country.Entity.Usuario_ERP |
Identifica al usuario del ERP que originó la solicitud. Ejemplo: MX.ETN040506RB3.Jan |
| Nombre | Tipo | Obligatorio | Límite | Formato | Descripción |
|---|---|---|---|---|---|
Data1 |
string | Sí | — | Base64 | Estructura Dictionary de criterios, codificada en Base64. Ver apartado 5 |
Data2 |
string | No | — | Cadena vacía "" |
Sin uso en esta transacción. El campo debe estar presente en el JSON con valor vacío |
Data3 |
string | No | — | Cadena vacía "" |
Sin uso en esta transacción. El campo debe estar presente en el JSON con valor vacío |
Data2 y Data3. Aquí los cuatro criterios se agrupan en una sola estructura dentro de Data1 codificada en Base64, Data2 y Data3 quedan vacíos. Las dos consultas no comparten la forma de recibir los criterios, aunque estén en la misma modalidad.Dictionary<Dictionary name="StoredXmlSelector">
<Entry k="Batch" v="[Serie del comprobante]"/>
<Entry k="Serial" v="[Folio del comprobante]"/>
<Entry k="Branch" v="[Sucursal, o vacío]"/>
<Entry k="Year" v="[Año de emisión, o vacío]"/>
</Dictionary>Entrada (k) |
Tipo | Obligatorio | Límite | Formato | Descripción |
|---|---|---|---|---|---|
Batch |
string | Sí | — | Texto | Serie del comprobante, en el valor v |
Serial |
string | Sí | El nodo Folio del XML Nativo admite hasta 40 caracteres. |
Texto | Folio del comprobante, en el valor v |
Branch |
string | No | El nodo Sucursal del XML Nativo admite hasta 128 caracteres. |
Texto, admite valor vacío | Sucursal que expresaste en el XML nativo de MYSuite. Si no tienes esa información puedes dejar la etiqueta en blanco: <Entry k="Branch" v=""/> |
Year |
string | No | 4 dígitos | Año en formato AAAA, admite valor vacío |
Año en que fue emitido el comprobante. Si no lo especificas, se busca en el actual |
name del Dictionary debe ser siempre StoredXmlSelector.Sin estructura. Ambos se envían como cadena vacía.
POST /RequestTransaction HTTP/1.1
Host: api.mysuitetest.com
Content-Type: application/json
{
"Requestor": "0c320b03-d4f1-47bc-9fb4-77995f9bf33e",
"Transaction": "LOOKUP_ISSUED_YEAR_BATCH_AND_SERIAL",
"Country": "MX",
"Entity": "JES900109Q90",
"User": "0c320b03-d4f1-47bc-9fb4-77995f9bf33e",
"UserName": "MX.JES900109Q90.Jan",
"Data1": "PERpY3Rpb25hcnkgbmFtZT0iU3RvcmVkWG1sU2VsZWN0b3IiPgogIDxFbnRyeSBrPSJCYXRjaCIgdj0iQUJCIi8+CiAgPEVudHJ5IGs9IlNlcmlhbCIgdj0iMTAiLz4KICA8RW50cnkgaz0iQnJhbmNoIiB2PSJBQkIiLz4KICA8RW50cnkgaz0iWWVhciIgdj0iMjAyNSIvPgo8L0RpY3Rpb25hcnk+",
"Data2": "",
"Data3": ""
}{
"requestField": {
"requestorField": "00000000-0000-0000-0000-000000000000",
"requestorNameField": null,
"requestorActiveField": true,
"transactionField": 243,
"countryField": "MX",
"entityField": "JES900109Q90",
"userField": "00000000-0000-0000-0000-000000000000",
"userNameField": "MX.JES900109Q90.Jan",
"idField": "5dad627c-caee-4e88-b904-f9a6d2c1bba9",
"timeStampField": "2026-09-23T11:55:53.8078657-06:00"
},
"responseField": {
"resultField": true,
"timeStampField": "2026-09-23T11:55:53.8255268-06:00",
"lastResultField": "",
"codeField": 1,
"descriptionField": "",
"hintField": "",
"dataField": " 12549 5dad627c-caee-4e88-b904-f9a6d2c1bba9",
"processorField": "TEST-BACK03",
"identifierField": null,
"batchIdentifierField": null
},
"responseDataField": {
"responseData1Field": "0",
"responseData2Field": "",
"responseData3Field": "",
"responseDataSetField": null
}
}
{
"requestField": {
"requestorField": "00000000-0000-0000-0000-000000000000",
"requestorNameField": null,
"requestorActiveField": true,
"transactionField": 243,
"countryField": "MX",
"entityField": "JES900109Q90",
"userField": "00000000-0000-0000-0000-000000000000",
"userNameField": "MX.JES900109Q90.Jan",
"idField": "815189ba-9c6d-42bd-987e-f92f9045cb82",
"timeStampField": "2026-09-23T11:58:58.3749416-06:00"
},
"responseField": {
"resultField": true,
"timeStampField": "2026-09-23T11:58:58.3939919-06:00",
"lastResultField": "",
"codeField": 1,
"descriptionField": "",
"hintField": "",
"dataField": " 12580 815189ba-9c6d-42bd-987e-f92f9045cb82",
"processorField": "TEST-BACK03",
"identifierField": null,
"batchIdentifierField": null
},
"responseDataField": {
"responseData1Field": "1",
"responseData2Field": "PERvY3NGb3VuZEJ5IGJhdGNoPSJBQkIiIHNlcmlhbD0iMTM1NDQiIGNvdW50PSIxIiB5ZWFyPSIyMDI2Ij4KPGRvYyBwb3M9IjEiPgo8Y3RyeT5NWDwvY3RyeT4KPHRheElkPkpFUzkwMDEwOVE5MDwvdGF4SWQ+Cjx1dWlkPjExMWQxMWIzLTdhYmYtNDhkYi1iN2Q1LTQ2NGY1MTY0YzU0ZDwvdXVpZD4KPGJyYW5jaD5BQkI8L2JyYW5jaD4KPGJhdGNoPkFCQjwvYmF0Y2g+CjxzZXJpYWw+MTM1NDQ8L3NlcmlhbD4KPGlzc3VlZD4yMDI2LTAzLTIwVDE3OjE4OjE5PC9pc3N1ZWQ+CjxjYW5jZWxsZWQvPgo8a2luZD4xPC9raW5kPgo8Y3VycmVuY3k+TVhOPC9jdXJyZW5jeT4KPHRvdGFsPjMwMjE1LjAwMDAwMDwvdG90YWw+CjwvZG9jPgo8L0RvY3NGb3VuZEJ5Pgo=",
"responseData3Field": "",
"responseDataSetField": null
}
}
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. Por seguridad se envían con "0" ceros. |
requestorNameField |
Nombre del solicitante. Puede llegar null |
requestorActiveField |
Booleano. Indica si el solicitante está activo |
transactionField |
Entero, no cadena: identificador numérico interno de 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 consulta se ejecutó correctamente |
codeField |
Entero. Código de resultado. Ver apartado 10 |
timeStampField |
Momento en que concluyó el procesamiento |
lastResultField · descriptionField · hintField |
Vacíos en consulta exitosa. Ver apartado 9 |
dataField |
Cadena de referencia interna del procesamiento |
processorField |
Servidor que atendió la solicitud. Dato a incluir al reportar incidencias |
identifierField · batchIdentifierField |
Llegan null. Esta transacción no devuelve datos de identificación del comprobante: el detalle viaja en responseData2Field |
responseDataField — resultado de la búsqueda:
| Campo | Contenido |
|---|---|
responseData1Field |
Cantidad de documentos encontrados. Llega como cadena JSON, no como número, y no viene en Base64 |
responseData2Field |
XML DocsFoundBy codificado en Base64, con el detalle de los documentos encontrados. No contiene los comprobantes en sí |
responseData3Field |
Vacío |
responseDataSetField |
Llega null |
Data1 va en Base64, pero en la respuesta responseData1Field llega en texto plano y solo responseData2Field viene codificado. Y el conteo llega entrecomillado en el JSON: es una cadena, no un número.responseData1Field devuelve 0 y responseData2Field llega vacío. El conteo se lee siempre ahí, no en resultField.DocsFoundBy (contenido de responseData2Field una vez decodificado)<DocsFoundBy batch="[Serie consultada]"
serial="[Folio consultado]"
count="[cantidad de documentos]"
year="[año consultado]">
<doc pos="[posición en el resultado]">
<ctry>...</ctry>
<taxId>...</taxId>
<uuid>...</uuid>
<branch>...</branch>
<batch>...</batch>
<serial>...</serial>
<issued>...</issued>
<cancelled/>
<kind>...</kind>
<currency>...</currency>
<total>...</total>
</doc>
</DocsFoundBy>| Elemento | Contenido |
|---|---|
@batch · @serial |
Serie y Folio consultados, como eco de los criterios |
@count |
Cantidad de documentos encontrados. Coincide con responseData1Field |
@year |
Año consultado |
doc/@pos |
Posición del documento dentro del resultado, comenzando en 1 |
ctry · taxId |
País y RFC del emisor |
uuid |
Folio Fiscal (UUID). Es la llave única real del comprobante y el dato que conviene registrar |
branch · batch · serial |
Sucursal, serie y folio del comprobante |
issued |
Fecha de emisión. Criterio útil para discriminar entre varios resultados |
cancelled |
Fecha de cancelación si el comprobante fue cancelado; vacío en caso contrario |
kind |
Tipo de documento: Ingreso, Egreso o Traslado. FACTURA = 1,
NOTA_DE_CREDITO = 2,
NOTA_DE_CARGO = 4,
CARTA_PORTE = 8,
RECIBO_DE_HONORARIOS = 16,
RECIBO_DE_ARRENDAMIENTO = 32,
RECIBO_DE_DONATIVOS = 64,
RECIBO_DE_PAGO_DE_PRIMAS = 128,
COMPROBANTE_DE_PAGO_A_PLAZOS = 256,
BOLETA_DE_EMPENO = 512,
RECIBO_DE_NOMINA = 1024,
RECIBO = 2048,
PAGO = 4096,
TRASLADO = 8192 |
currency · total |
Moneda y total del comprobante |
LOOKUP_ISSUED_INTERNAL_ID, con la diferencia de que los atributos del elemento raíz reflejan los criterios de esta búsqueda. El cuerpo mantiene los tres objetos del apartado 8. Cambia el contenido de responseField y las cargas llegan vacías.
| Campo | Contenido en error |
|---|---|
resultField |
false: la consulta no se pudo ejecutar |
codeField |
Código del error. 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 |
resultField = false significa que la consulta no se pudo ejecutar: no significa que el comprobante no exista. La ausencia de comprobante se expresa como resultField = true con conteo 0. Un proceso que confunda las dos señales concluirá que un comprobante no existe cuando en realidad la consulta falló.resultField = false dentro de un cuerpo JSON válido. Evalúa siempre ese campo y no asumas éxito por el código de estado HTTP. | Aspecto | Valor |
|---|---|
| Alcance temporal | Un año por consulta, determinado por la entrada Year. Si va vacía, se consulta el año en curso |
| Alcance por emisor | Limitado al RFC declarado en Entity y al ambiente en que consultas |
| Unicidad del criterio | Ninguna. Serie y Folio no son elementos de unicidad en la base de datos: la consulta puede devolver varios documentos |
| Idempotencia | Es una transacción de consulta: no modifica el estado de ningún comprobante, por lo que reintentarla no tiene efectos colaterales |
| Máximo de documentos en el detalle | Los que se envíen |
| Orden de los resultados | Ninguno |
| Timeout | 60 segundos en servidor front |
Serie y Folio del bloque AsignacionSolicitada del XML Nativo FactDocMX v8, o de la asignación configurada en el Portal Web de MYSuite. Ambos son opcionales en el CFDI conforme al Anexo 20.Problema. La consulta devuelve responseData1Field con valor 0 para un comprobante que sí está en MYSuite.
Entorno. CFDI + Timbrado · API REST · LOOKUP_ISSUED_YEAR_BATCH_AND_SERIAL.
Resolución. Revisa, en este orden: que la entrada Year corresponda al año de emisión, recordando que vacía significa año en curso; que la entrada Branch, si la enviaste con valor, sea la Sucursal del comprobante, y si dudas envíala vacía para no acotar la búsqueda; y que Batch y Serial coincidan exactamente con la Serie y el Folio registrados al emitir, sin espacios ni ceros de relleno que tu sistema pueda estar añadiendo.
Causa. Cualquiera de los cuatro criterios reduce el alcance. La Sucursal enviada con un valor incorrecto es la causa más silenciosa, porque es opcional y muchos integradores la llenan por costumbre.
Problema. El conteo es mayor que 1 y tu sistema esperaba un único resultado.
Entorno. CFDI + Timbrado · API REST · sistemas administrativos que usan Serie y Folio como identificador principal.
Resolución. No es un defecto de la plataforma: la Serie y el Folio no son elementos de unicidad. Decodifica responseData2Field y discrimina entre los elementos doc usando issued, total y cancelled. Si necesitas reducir el resultado a uno, acota la búsqueda enviando la Sucursal en Branch. A mediano plazo, registra el uuid en tu sistema y usa el Folio Fiscal como identificador.
Causa. El único elemento de unicidad en la base de datos es el Folio Fiscal. La unicidad de Serie y Folio debe garantizarla tu sistema administrativo, y si no lo hace, pueden coexistir comprobantes con la misma combinación.
Problema. La petición es rechazada o devuelve 0 al reutilizar la implementación de LOOKUP_ISSUED_INTERNAL_ID.
Entorno. CFDI + Timbrado · API REST · integraciones que implementan varias transacciones de consulta.
Resolución. Las dos consultas reciben los criterios de forma distinta, aunque estén en la misma modalidad. Aquí los cuatro criterios van agrupados en la estructura Dictionary dentro de Data1 y codificados en Base64, con Data2 y Data3 vacíos. En la otra transacción los criterios van en texto plano y se reparten entre Data1, Data2 y Data3. No es posible compartir la capa de armado de criterios entre ambas.
Causa. Cada transacción define su propio contrato para los tres campos de datos. La similitud de nombre y de propósito no implica similitud de contrato.
Problema. La deserialización falla en responseData1Field o el valor no se puede comparar numéricamente.
Entorno. CFDI + Timbrado · API REST · lenguajes con tipado estricto.
Resolución. El conteo viaja entrecomillado en el JSON, es decir, como cadena. Declara el campo como texto y conviértelo tú antes de compararlo. Y no intentes decodificarlo desde Base64: aunque la entrada sí va codificada, de la salida solo responseData2Field lo está.
Causa. Los tres campos de responseDataField comparten el tipo cadena, aunque uno de ellos transporte un número.
Problema. El deserializador devuelve valores nulos o lanza excepción al mapear la respuesta, aunque el cuerpo JSON llega completo.
Entorno. CFDI + Timbrado · API REST · integraciones nuevas, o migradas desde SOAP.
Resolución. Mapea los nombres exactos de la respuesta, que llevan el sufijo Field y no coinciden con los de la petición: resultField y no Result, responseData2Field y no ResponseData2. La ruta completa del conteo es responseDataField.responseData1Field.
Causa. La petición usa nombres en PascalCase sin sufijo y la respuesta usa camelCase con sufijo Field. Es asimétrica por diseño.
Problema. La consulta devuelve 0 para comprobantes emitidos en años anteriores.
Entorno. CFDI + Timbrado · API REST · conciliaciones históricas, o consultas hechas en enero sobre comprobantes de diciembre.
Resolución. Especifica el año de emisión en la entrada Year con formato de cuatro dígitos. La consulta abarca un año por llamada; para revisar varios años, ejecuta una consulta por año.
Causa. Con Year vacío la plataforma asume el año en curso. El caso de fin de año es especialmente engañoso: un comprobante emitido el 31 de diciembre no se encuentra si lo consultas en enero sin especificar el año.
En el CFDI, la serie y el folio son campos opcionales cuyo contenido queda a criterio del emisor: el SAT no los valida ni exige que sean únicos. El identificador real es el Folio Fiscal, el UUID que asigna el PAC al timbrar. MYSuite refleja esa realidad en su almacenamiento: la llave de unicidad es el UUID, no la combinación de serie y folio. De ahí que esta consulta pueda devolver más de un resultado sin que exista ningún error.
Porque muchos sistemas administrativos son anteriores al CFDI o fueron diseñados alrededor del concepto de folio consecutivo, y su control interno se lleva por serie y folio. Para ellos, buscar por UUID es imposible: no lo tienen registrado. Esta transacción les da una vía de acceso con los datos que sí manejan, a cambio de aceptar que el resultado puede ser ambiguo. La contrapartida está declarada en el propio contrato: la unicidad la debe garantizar el sistema administrativo, no la plataforma.
La operación RequestTransaction ofrece solo tres campos de datos para todas las transacciones de la plataforma. Cuando una transacción necesita más de tres criterios —aquí son cuatro: serie, folio, sucursal y año— no alcanzan los campos, y la solución es agrupar los criterios en una estructura y meterla completa en Data1. Codificarla en Base64 evita además que el XML de criterios tenga que escaparse dentro de un valor JSON. Es el mismo patrón que usa CONVERT_NATIVE_XML con el XML Nativo, aplicado aquí a un conjunto de criterios en lugar de a un documento.
Conviene notarlo porque sorprende: la modalidad REST intercambia JSON, pero los criterios de esta transacción son un XML codificado. La razón es que la estructura StoredXmlSelector es común a ambos transportes y se definió del lado del servidor antes de que existiera la modalidad REST. El resultado es una petición híbrida, y una capa de código que tu ERP tendrá que compartir con la implementación SOAP si opera las dos.
Un proceso que solo necesita saber si el comprobante existe puede decidir leyendo responseData1Field, sin decodificar nada. El detalle en responseData2Field sirve al segundo caso de uso, que es identificar cuál de los resultados corresponde al comprobante buscado y quedarse con su UUID. De ahí la codificación asimétrica de la respuesta: es la separación entre la señal y el detalle.
identifierField llega vacíoEn las transacciones de emisión y de recuperación, ese objeto trae los datos del comprobante. Aquí no puede: la consulta puede devolver varios documentos, y un objeto pensado para uno solo no sirve. Por eso el detalle viaja en un XML aparte, con capacidad para tantos elementos como haga falta. Verlo en null no es señal de que algo salió mal.
Las dos consultas devuelven la misma estructura DocsFoundBy y comparten el propósito de localizar comprobantes sin descargarlos, pero responden a necesidades distintas. Aquélla busca por el identificador que tu ERP generó antes de emitir, y su caso de uso central es la verificación antiduplicado tras una respuesta perdida. Ésta busca por los datos que el comprobante muestra en su cara visible, y su caso de uso central es la conciliación desde un sistema que lleva su control por serie y folio. También difieren en cómo reciben los criterios, lo que impide compartir la implementación.
La transacción es la misma operación de negocio en ambos transportes: mismos criterios, misma estructura de detalle, mismo resultado. 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.
Vía RequestTransaction