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

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

Estado Transacción: Vigente · Compatibilidad: XML Nativo (FactDocMX) v8 · Última revisión: 07/08/2026 · Próxima revisión: 07/11/2026 · Responsable: Jan Martínez


De un vistazo


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.


La Serie y el Folio no identifican de forma única a un comprobante. El elemento de unicidad en la base de datos es el Folio Fiscal (UUID). Puede existir más de un documento del mismo emisor con la misma Serie y Folio, así que esta consulta puede devolver varios resultados sin que haya error alguno. Si tu sistema depende de que la combinación sea única, esa unicidad la debe garantizar el propio sistema administrativo: MYSuite no la impone.
Advertencia de homonimia. Existe la misma transacción en la modalidad CFDI + Timbrado sobre SOAP. Cada transporte se documenta en un artículo independiente. Este cubre exclusivamente API REST.


Cómo saber si este es tu artículo


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


Requisitos previos

  • Credenciales de integración vigentes que te proporciona MYSuite: Requestor y Entity.
  • La Serie y el Folio del comprobante, tal como quedaron registrados al emitir.
  • El año de emisión, si el comprobante no es del año en curso.
  • Que tu sistema administrativo garantice la unicidad de la combinación Serie + Folio, si vas a tratar el resultado como un único comprobante.


Cómo hacerlo

  1. Recupera de tu sistema administrativo la Serie y el Folio del comprobante que quieres localizar.
    Resultado: los dos criterios obligatorios de la búsqueda.
  2. Determina la Sucursal y el año de emisión. Ambos son opcionales: la Sucursal puedes dejarla en blanco y, si no especificas el año, se busca en el actual.
    Resultado: los criterios opcionales definidos, o la decisión de omitirlos.
  3. Construye la estructura Dictionary con el atributo name igual a StoredXmlSelector y las cuatro entradas Batch, Serial, Branch y Year.
    Resultado: un XML de criterios bien formado.
  4. Codifica la estructura completa en Base64, en una sola línea.
    Resultado: la cadena que vas a poner en Data1.
  5. Arma el cuerpo JSON con los nueve campos: las credenciales, Transaction con valor LOOKUP_ISSUED_YEAR_BATCH_AND_SERIAL, la cadena Base64 en Data1, Data2 y Data3 como cadenas vacías.
    Resultado: un JSON válido con los nueve campos presentes.
  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: resultField = true indica que la consulta se ejecutó; resultField = false te lleva a Solución de problemas.
  8. Lee responseDataField.responseData1Field tal cual: contiene la cantidad de comprobantes encontrados, como cadena.
    Resultado: el conteo, sin necesidad de decodificar nada.
  9. Decodifica responseDataField.responseData2Field desde Base64 si el conteo es mayor que 0.
    Resultado: el XML DocsFoundBy con el detalle de cada comprobante localizado.
  10. Interpreta el conteo:
    • 0 — no existe comprobante con esa Serie y Folio en el año y la Sucursal consultados.
    • 1 — comprobante localizado. Toma el uuid del detalle.
    • Mayor que 1 — existen varios comprobantes con esa Serie y Folio. No es un error: la combinación no es llave única. Discrimina por issued, total y cancelled, o acota la búsqueda por Sucursal.

    Resultado: el comprobante identificado, o la constancia de que no existe con esos criterios.
  11. Registra en tu sistema el Folio Fiscal obtenido, de modo que las consultas siguientes sobre ese comprobante puedas hacerlas por su llave única.
    Resultado: comprobante trazable por UUID y no solo por Serie y Folio.

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 LOOKUP_ISSUED_YEAR_BATCH_AND_SERIAL
Naturaleza Consulta. No modifica el estado de ningún comprobante


2. Ambientes

Ambiente URL
Pruebas https://api.mysuitetest.com/RequestTransaction
Producción https://api.mysuitecfdi.com/RequestTransaction
Restricción del ambiente de pruebas. Un cliente CFDI + Timbrado (API REST) debe usar 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.


3. Autenticación

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


4. Parámetros de entrada

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
Diferencia con LOOKUP_ISSUED_INTERNAL_ID. Allí los tres campos viajan en texto plano, la Sucursal y el año ocupan 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.


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

Data1 — estructura 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
El atributo name del Dictionary debe ser siempre StoredXmlSelector.

Data2 y Data3

Sin estructura. Ambos se envían 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": "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": ""
}


7. Ejemplo de response

{
"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
}
}

Ejemplo de response: Caso con 1 CFDI encontrado:

{
"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
}
}

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. 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
Asimetría de codificación. La entrada 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.
Cuando no hay coincidencias: responseData1Field devuelve 0 y responseData2Field llega vacío. El conteo se lee siempre ahí, no en resultField.


Estructura del XML 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

Es la misma estructura que devuelve LOOKUP_ISSUED_INTERNAL_ID, con la diferencia de que los atributos del elemento raíz reflejan los criterios de esta búsqueda. 


9. Estructura de respuesta — error

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
Distinción necesaria. 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ó.
Un error de negocio se reporta con 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. 


10. Códigos de Error


11. Límites y comportamiento


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


12. Versionado y cumplimiento

  • La transacción no depende de la versión del CFDI: consulta comprobantes ya emitidos, cualquiera que sea la versión con la que se timbraron.
  • La Serie y el Folio provienen de los nodos 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.

Solución de problemas

"Me devuelve 0 aunque la factura existe"


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.

"Me devuelve varios comprobantes con la misma serie y folio"


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.

"Copié el código de la otra búsqueda y no funciona"


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.

"El conteo me llega como texto y mi código espera un número"


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.

"Mi código no encuentra los campos de la respuesta"


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.

"Busco un comprobante del año pasado y no lo encuentra"


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.


Para entender más

Por qué la Serie y el Folio no identifican un comprobante

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.

Por qué entonces existe esta transacción

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.

Por qué los criterios viajan como Dictionary y en Base64

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.

Una estructura XML dentro de una petición JSON

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.

Por qué el conteo y el detalle viajan separados

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.

Por qué identifierField llega vacío

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

En qué se diferencia de LOOKUP_ISSUED_INTERNAL_ID

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.

Por qué SOAP y REST se documentan por separado

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.


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