Qué hace: busca los CFDI emitidos y almacenados en MYSuite cuyo Número Interno coincide con el que consultas, te devuelve cuántos encontró junto con el detalle de cada uno. El Número Interno es el identificador único de una transacción, llamada, operación o registro en tu ERP.
Cuándo se usa: para el control de la no duplicidad de comprobantes. El escenario central es una emisión cuya respuesta no llegó: como no sabes si el CFDI se timbró y no conoces el Folio Fiscal que MYSuite pudo haberle asignado, preguntas por el Número Interno, que sí conoces de antemano, antes de decidir si reintentas.
Cuándo no usarla: esta transacción no devuelve los comprobantes, solo un conteo y su detalle resumido. Tampoco sirve si tu ERP no envió el Número Interno al emitir: sin ese dato el comprobante no es localizable por esta vía.
numDocs. Si el comprobante ya existe, no vuelvas a enviarlo a generar.& como &, < como < y > como >.RequestTransaction, aquí solo puedes acotar por Número Interno y por Sucursal.| Si tu integración… | Tu artículo es... |
|---|---|
Consulta por Número Interno enviando un sobre SOAP a factwsfront.asmx con la operación JsonServiceCall |
Este artículo |
Consulta lo mismo enviando JSON al recurso /JsonServiceCall de API REST |
LOOKUP_ISSUED_INTERNAL_ID — CFDI + Timbrado (API REST) - JsonServiceCall |
Consulta por RequestTransaction, con credenciales en cada petición |
LOOKUP_ISSUED_INTERNAL_ID — CFDI + Timbrado (API REST) - Request Transaction |
| Envía sobres SOAP con las operaciones clásicas y recibe XML | LOOKUP_ISSUED_INTERNAL_ID — CFDI + Timbrado (SOAP) |
| Va a emitir un CFDI por esta misma modalidad | CONVERT_NATIVE_XML4 — SERVICIO ENDPOINT |
AUTHENTICATE.AUTHENTICATE, o toma el último que te devolvió la transacción anterior.internalid y, si quieres acotar, branch. Serialízalo con la librería JSON de tu lenguaje, no a mano.&, < y >. Aquí no hay Base64 que te proteja de ellos.ws:JsonServiceCall y sus tres elementos hijos: ws:jsonData con el JSON, ws:transactionName con el literal LOOKUP_ISSUED_INTERNAL_ID y ws:token con el token vigente.factwsfront.asmx del ambiente que te corresponda.JsonServiceCallResult y analízalo como JSON. No lo recorras como XML.Result, Payload, ErrorMsg, ErrorCode y Token.Result y comprueba que ErrorCode sea 0.Token de la respuesta, sustituyendo el anterior.Payload desde Base64. Obtienes directamente el objeto de resultado, sin envoltura: una sola capa.numDocs y el detalle en docs.numDocs antes de decidir si reintentas la emisión:uuid del detalle para actualizar tu ERP.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 | LOOKUP_ISSUED_INTERNAL_ID, indicada en ws:transactionName |
| Naturaleza | Consulta. No modifica el estado de ningún comprobante |
| Autenticación | Token en el elemento ws:token, obtenido con AUTHENTICATE |
| Consumo |
No consume folio del paquete vigente
|
4. Las transacciones de emisión de esta modalidad sí lo llevan porque distinguen la versión del CFDI. Ésta no depende de la versión: busca comprobantes ya emitidos, cualquiera que sea aquella con la que se timbraron.| 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 |
La consulta solo alcanza a los comprobantes del ambiente en que operas: un Número Interno timbrado en pruebas no se encuentra desde producción, ni al contrario. En el ambiente de pruebas el RFC emisor es JES900109Q90.
| 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 |
El elemento ws:JsonServiceCall lleva tres elementos hijos.
| Elemento | Tipo | Obligatorio | Formato | Descripción |
|---|---|---|---|---|
ws:jsonData |
string | Sí | JSON crudo, escapado para XML | Los datos en forma de objeto JSON que conforman la materia prima para buscar el CFDI. Ver apartado 5 |
ws:transactionName |
string | Sí | Literal | Transacción. Para ésta: LOOKUP_ISSUED_INTERNAL_ID |
ws:token |
string | Sí | Texto | Valor obtenido de la transacción AUTHENTICATE |
{
"internalid": "[Número Interno a buscar]",
"branch": "[Sucursal, opcional]"
}| Campo | Obligatorio | Formato | Descripción |
|---|---|---|---|
internalid |
Sí | Texto | Número Interno que se desea buscar, tal como lo enviaste al emitir |
branch |
No | Texto | Sucursal, para el caso en que quieras buscar por alguna en concreto, es decir si el documento se emitió desde una sucursal |
RequestTransaction reciben el año como tercer criterio y documentan que, si va vacío, se busca en el año en curso. Esta vía no tiene ese parámetro, igual que API REST por JsonServiceCall. | Carácter | Escapado como |
|---|---|
& |
& |
< |
< |
> |
> |
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>{"internalid": "1",
"branch": "ABB"}</ws:jsonData>
<ws:transactionName>LOOKUP_ISSUED_INTERNAL_ID</ws:transactionName>
<ws:token>[último token devuelto]</ws:token>
</ws:JsonServiceCall>
</soap:Body>
</soap:Envelope><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":"eyJpbnRlcm5hbGlkIjoiMSIsIm51bURvY3MiOjUsImRvY3MiOlt7InBvcyI6IjEiLCJjdHJ5IjoiTVgiLCJ0YXhJZCI6IkpFUzkwMDEwOVE5MCIsInV1aWQiOiJiZWNiYjI0My0yMWU2LTQ0YjYtODlmNy1kMmM5ZTU0NmYzYjMiLCJicmFuY2giOiJBQkIiLCJiYXRjaCI6IkFCQiIsInNlcmlhbCI6IjEzODIwIiwiaXNzdWVkIjoiMjAyNi0wOS0xMVQwMjoyNTowNyIsImNhbmNlbGxlZCI6IjIwMjYtMDktMTRUMTI6Mjg6NTgiLCJraW5kIjoiMSIsImN1cnJlbmN5IjoiTVhOIiwidG90YWwiOiI0MjAuMDAwMDAwIn0seyJwb3MiOiIyIiwiY3RyeSI6Ik1YIiwidGF4SWQiOiJKRVM5MDAxMDlROTAiLCJ1dWlkIjoiN2M3YjgwYzUtNGIzZi00OTFhLWI0ZGYtY2I0N2VlYmNiODcyIiwiYnJhbmNoIjoiQUJCIiwiYmF0Y2giOiJBQkIiLCJzZXJpYWwiOiIxMzgxOSIsImlzc3VlZCI6IjIwMjYtMDktMTFUMDE6MTY6NDEiLCJjYW5jZWxsZWQiOiIiLCJraW5kIjoiMSIsImN1cnJlbmN5IjoiTVhOIiwidG90YWwiOiI0MjAuMDAwMDAwIn0seyJwb3MiOiIzIiwiY3RyeSI6Ik1YIiwidGF4SWQiOiJKRVM5MDAxMDlROTAiLCJ1dWlkIjoiOTk2ZmQ2ZWMtNjUyYS00ODFjLWE3OTktZjk4YzI4N2ZjZjM0IiwiYnJhbmNoIjoiQUJCIiwiYmF0Y2giOiJBQkIiLCJzZXJpYWwiOiIxMzgxOCIsImlzc3VlZCI6IjIwMjYtMDktMTBUMTg6MDY6NTIiLCJjYW5jZWxsZWQiOiIiLCJraW5kIjoiMSIsImN1cnJlbmN5IjoiTVhOIiwidG90YWwiOiIyMDM4NS4wMDAwMDAifSx7InBvcyI6IjQiLCJjdHJ5IjoiTVgiLCJ0YXhJZCI6IkpFUzkwMDEwOVE5MCIsInV1aWQiOiIxMTFkMTFiMy03YWJmLTQ4ZGItYjdkNS00NjRmNTE2NGM1NGQiLCJicmFuY2giOiJBQkIiLCJiYXRjaCI6IkFCQiIsInNlcmlhbCI6IjEzNTQ0IiwiaXNzdWVkIjoiMjAyNi0wMy0yMFQxNzoxODoxOSIsImNhbmNlbGxlZCI6IiIsImtpbmQiOiIxIiwiY3VycmVuY3kiOiJNWE4iLCJ0b3RhbCI6IjMwMjE1LjAwMDAwMCJ9LHsicG9zIjoiNSIsImN0cnkiOiJNWCIsInRheElkIjoiSkVTOTAwMTA5UTkwIiwidXVpZCI6ImNlZTU2ZGMyLTA2NzQtNGIxZi1hZTg5LTM3ZTlmMzQ1MTVlMCIsImJyYW5jaCI6IkFCQiIsImJhdGNoIjoiQUJCIiwic2VyaWFsIjoiMTM1MzMiLCJpc3N1ZWQiOiIyMDI2LTAyLTEyVDE4OjAwOjI0IiwiY2FuY2VsbGVkIjoiIiwia2luZCI6IjEiLCJjdXJyZW5jeSI6Ik1YTiIsInRvdGFsIjoiOTUuMDAwMDAwIn1dfQ==","ErrorMsg":"","ErrorCode":0,"Token":"OxbZPD1Gd9hUomWYNBUGWkzja54cEGlnz9LLPKZY+pI0+bfE1ldh8TKjBK02xvy5zNV/JVdwwqNlj5419TpH/7NV7sK9uXDo8mYt7YmqI98="}
</JsonServiceCallResult>
</JsonServiceCallResponse>
</soap:Body>
</soap:Envelope>Payload una vez decodificado, en un caso con dos comprobantes encontrados:{
"internalid": "[Número Interno consultado]",
"numDocs": 2,
"docs": [
{ "pos": 1, "ctry": "...", "taxId": "...", "uuid": "...", "branch": "...",
"batch": "...", "serial": "...", "issued": "...", "cancelled": "...",
"kind": "...", "currency": "...", "total": "..." },
{ "pos": 2, "ctry": "...", "taxId": "...", "uuid": "...", "branch": "...",
"batch": "...", "serial": "...", "issued": "...", "cancelled": "...",
"kind": "...", "currency": "...", "total": "..." }
]
}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 Base64 que al decodificarse produce el objeto de resultado de la búsqueda |
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 |
Los campos Result, ErrorMsg y ErrorCode tienen el mismo significado en todas las transacciones de la modalidad, tal como se describe en AUTHENTICATE.
Payload decodifica directamente al objeto de resultado, sin envoltura: basta una capa. En las transacciones de emisión que devuelven archivos hacen falta dos. El patrón depende de la transacción, no del transporte: esta misma transacción se comporta igual en API REST.JsonServiceCall los mismos cinco campos van en camelCase. Si compartes la clase de deserialización entre ambas modalidades, los campos llegarán nulos sin producir excepción, y el síntoma aparente será que no recibiste resultado.Payload
| Campo | Contenido |
|---|---|
internalid |
Número Interno que se buscó en la llamada. Eco del criterio |
numDocs |
Número de comprobantes que tienen el mismo número interno que se buscó en la llamada. Es el campo sobre el que se implementa la lógica de no duplicidad |
docs |
Arreglo con el detalle de cada comprobante encontrado. Ver desglose siguiente |
docs
| Campo | Contenido |
|---|---|
pos |
Indica la posición dentro del resultado |
ctry |
País de emisión |
taxId |
RFC del emisor. En el ambiente de pruebas, JES900109Q90 |
uuid |
Folio Fiscal que corresponde al documento o comprobante. Es el dato que te permite cerrar el comprobante en tu ERP |
branch |
Sucursal de emisión del documento o comprobante |
batch |
Serie |
serial |
Folio |
issued |
Fecha de emisión del documento o comprobante |
cancelled |
Fecha de cancelación del documento o comprobante |
kind |
Tipo de Documento. |
currency |
Moneda del documento o comprobante |
total |
Importe total |
DocsFoundBy que devuelve la misma transacción por RequestTransaction y por SOAP. Es la misma estructura expresada en otro formato, lo cual permite compartir el modelo de datos entre modalidades aunque la petición y la respuesta no se parezcan.| 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 = false significa que la consulta no se pudo ejecutar: no significa que el comprobante no exista. Un ERP que trate el error de consulta como «no encontrado» reintentará la emisión y generará un CFDI duplicado. Ante un error debes reintentar la consulta, no la emisión.| Código | Significado | Causa | Remedio |
|---|---|---|---|
0 |
Sin error | La consulta se ejecutó. El conteo se lee en numDocs |
— |
101 |
Token expirado | La vida del token expiró | Autenticarte de nuevo con AUTHENTICATE y reintentar la consulta |
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 |
|---|---|
| Alcance temporal | Año en curso |
| Alcance por emisor | Determinado por el usuario autenticado y por el ambiente en que consultas |
| Efectos | Ninguno. No crea, no modifica y no cancela |
| Idempotencia | Es una consulta: reintentarla no tiene efectos colaterales |
| Consumo de folios | No consume folios del paquete vigente |
Máximo de documentos en docs |
Los que se encuentren |
| Timeout | 60 segundos en servidor front |
.asmx que atiende EndPoint es el mismo que atiende la modalidad SOAP clásica. Un cambio en ese servicio afecta a ambas modalidades.Problema. numDocs llega en 0 para un comprobante que sí existe en MYSuite, con el riesgo de que tu ERP reintente la emisión y genere un duplicado.
Entorno. EndPoint · recuperación tras un TimeOut.
Resolución. Revisa, en este orden: que el Nativo del comprobante haya llevado el Número Interno, ya que sin él el comprobante no es localizable por esta vía; que el valor de internalid coincida exactamente con el que enviaste al emitir; y que la Sucursal de branch, si la enviaste, sea la del comprobante. Si dudas de la Sucursal, omítela para no acotar la búsqueda.
Problema. La consulta no encuentra comprobantes emitidos en el ejercicio anterior.
Entorno. EndPoint · cierres de ejercicio.
RequestTransaction o por SOAP, que sí reciben el año.Problema. Ante Result = false, el ERP interpreta que el comprobante no fue emitido y reintenta la emisión, generando un CFDI duplicado.
Entorno. EndPoint · lógica de recuperación ante TimeOut.
Resolución. Trata Result = false como consulta no concluyente, no como ausencia de comprobante. Reintenta la consulta; si persiste, detén el proceso de emisión de ese comprobante y escala antes de volver a timbrar. El único valor que autoriza reintentar la emisión es numDocs = 0 con Result = true.
Causa. Confusión entre el resultado de la consulta y el resultado de la búsqueda. Son dos señales distintas que viajan en campos distintos.
Problema. La verificación antiduplicado devuelve error de token justo cuando más se necesita.
Entorno. EndPoint · recuperación tras un corte.
Resolución. Si la emisión no devolvió respuesta, tampoco devolvió token nuevo: el token válido sigue siendo el que tenías antes de emitir. Úsalo para la consulta. Si aun así recibes 101, autentícate de nuevo y repite la consulta: autenticarse no tiene efecto alguno sobre el comprobante que estás investigando.
Causa. Se descartó el token anterior al no recibir uno nuevo.
Problema. numDocs es mayor que 1 y tu ERP no sabe cuál de los comprobantes es el correcto.
Entorno. EndPoint · integraciones con reintentos automáticos, o con Números Internos reutilizados.
Resolución. No reintentes la emisión. Revisa cada elemento de docs: issued te permite identificar el orden de emisión y cancelled indica si alguno ya fue cancelado. Escala el caso para determinar qué comprobante conservar y cancelar el resto conforme al esquema de cancelación Vigente.
Causa. O tu ERP reintentó una emisión sin verificar antes, o el Número Interno no es único en tu sistema. Si es lo segundo, corrige la generación del identificador: de lo contrario la verificación antiduplicado no es confiable.
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. La capa que interpreta Payload funciona aquí y no en las transacciones de emisión, o al revés.
Entorno. EndPoint · integraciones que usan varias transacciones.
Resolución. Aquí Payload decodifica directamente al objeto de resultado: basta una capa. En CONVERT_NATIVE_XML4 y _SN4, en cambio, envuelve los archivos y hacen falta dos. Escribe una capa de lectura por transacción.
Causa. Las transacciones de esta modalidad comparten el nombre del campo pero no su contrato.
El timbrado es una operación con efectos fiscales irreversibles: una vez incorporado el Timbre Fiscal Digital, el comprobante existe ante el SAT y solo puede retirarse mediante una cancelación formal. Entre el momento en que tu ERP envía la petición y el momento en que recibe la respuesta hay una ventana en la que el estado real es desconocido. Si la conexión se corta ahí, tienes dos opciones malas: no reintentar y quedarte sin comprobante, o reintentar y arriesgar un duplicado que después habrá que cancelar. Esta transacción convierte esa decisión ciega en una verificación.
Cuando la respuesta se pierde, tu ERP no conoce el Folio Fiscal: lo asigna MYSuite y viaja justamente en la respuesta que no llegó. El Número Interno es el único identificador que conoces antes de la llamada, porque lo generas tú y lo envías en el Nativo. Es el único puente disponible hacia un comprobante cuyo folio desconoces.
Es opcional en el formato, y MYSuite no valida su unicidad. Eso tiene una consecuencia práctica que conviene aceptar de entrada: tu capacidad de recuperarte de un TimeOut depende de una decisión que tomas al implementar la emisión, no al implementar la recuperación. Un ERP que no lo envía, o que lo reutiliza, se queda sin red de seguridad, y el problema solo se manifiesta el día del primer corte de conexión.
Esto importa especialmente si emites con CONVERT_NATIVE_XML_BASIC4: como esa variante no devuelve archivos, el Número Interno es el único dato tuyo que permite rastrear el comprobante después.
El caso de uso principal necesita responder una sola pregunta: ¿existe o no? Para eso basta numDocs, y por eso la propia documentación lo señala como el campo sobre el que se implementa la lógica de no duplicidad. El arreglo docs sirve al segundo caso de uso, que es cerrar el comprobante en tu ERP con su Folio Fiscal, serie y folio. Conviene separar ambos momentos en el código: decidir si reintentar, y después conciliar.
Es una consulta: no crea, no modifica y no cancela nada. A diferencia de las transacciones de emisión, puedes ejecutarla tantas veces como necesites sin consecuencias. Esa asimetría es la que hace viable el patrón completo: verificar cuantas veces haga falta, emitir una sola.
El token rota con cada llamada exitosa, así que al recuperarse de un TimeOut hay que tener presente que la emisión fallida no entregó token nuevo. El válido sigue siendo el anterior.
Los nombres de los campos de docs son exactamente los del XML DocsFoundBy que devuelve esta misma transacción por SOAP y por RequestTransaction. Es la misma estructura expresada en otro formato, lo cual indica que del lado del servidor hay un único modelo. Para quien mantiene varias modalidades es una buena noticia: el modelo de datos se comparte aunque la petición y la respuesta no.
La transacción es la misma operación de negocio en los cuatro transportes: mismo criterio, misma estructura de detalle, mismo resultado. 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. Documentarlos juntos 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.