Qué hace: busca los CFDI emitidos y almacenados en MYSuite cuyo Número Interno coincide con el que consultas, y 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.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 por JsonServiceCall, con token |
Este artículo |
Consulta lo mismo por RequestTransaction, con credenciales en cada petición |
LOOKUP_ISSUED_INTERNAL_ID — CFDI + Timbrado (API REST) - Request Transaction |
Hace lo mismo enviando un sobre SOAP a FactWSFront |
LOOKUP_ISSUED_INTERNAL_ID — CFDI + Timbrado (SOAP) |
| Va a emitir un CFDI por esta misma vía y requiere xml con nativo de mysuite y pdf del cfdi | CONVERT_NATIVE_XML4 — CFDI + Timbrado (API REST) - JsonServiceCall |
AUTHENTICATE.AUTHENTICATE, o toma el último que te devolvió la transacción anterior.internalid y, si quieres acotar, branch.jsonData.jsonData con esa cadena, token con el token vigente y transactionName con el literal LOOKUP_ISSUED_INTERNAL_ID./JsonServiceCall.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.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.
| 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 LOOKUP_ISSUED_INTERNAL_ID |
| Naturaleza | Consulta. No modifica el estado de ningún comprobante |
| Autenticación | Token en el cuerpo, obtenido con AUTHENTICATE |
| Consumo | No consume folio del paquete vigente |
4. Las transacciones de emisión de esta vía 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://api.mysuitetest.com/JsonServiceCall |
| Producción | https://api.mysuitecfdi.com/JsonServiceCall |
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.
| 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.| Campo | Tipo | Obligatorio | Formato | Descripción |
|---|---|---|---|---|
jsonData |
string | Sí | Base64 | Los datos en forma de objeto JSON que conforman la materia prima para buscar el CFDI. Ver apartado 5 |
token |
string | Sí | Texto | Token de seguridad vigente |
transactionName |
string | Sí | Literal | Transacción. Para esta: LOOKUP_ISSUED_INTERNAL_ID |
{
"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, en caso en que quieras buscar por alguna en concreto |
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. POST /JsonServiceCall HTTP/1.1
Host: api.mysuitetest.com
Content-Type: application/json
{
"jsonData": "eyJpbnRlcm5hbGlkIjogIjIwMDAwMCIsCiJicmFuY2giOiAiQUJCIgp9",
"token": "OxbZPD1Gd9hUomWYNBUGWkzja54cEGlnz9LLPKZY+pI0+bfE1ldh8TKjBK02xvy5Qw9I1BlsQejK7kHcLGsmeN5B+BKm7BtzOR518I97ffc=",
"transactionName": "LOOKUP_ISSUED_INTERNAL_ID"
}Forma de la respuesta:
{
"result": true,
"payload": "eyJpbnRlcm5hbGlkIjoiMjAwMDAwIiwibnVtRG9jcyI6MCwiZG9jcyI6W119",
"token": "OxbZPD1Gd9hUomWYNBUGWkzja54cEGlnz9LLPKZY+pI0+bfE1ldh8TKjBK02xvy5Qw9I1BlsQejK7kHcLGsmeM99B+Me4jaSqZAvyTd4iaE=",
"errorMsg": "",
"errorCode": 0
}Contenido de 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": "..." }
]
}El cuerpo es un objeto JSON de cinco campos.
| 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 esta vía, tal como se describe en AUTHENTICATE.
payload decodifica directamente al objeto de resultado, sin envoltura, igual que en CONVERT_NATIVE_XML_BASIC4. Basta una capa de decodificación. 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. 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 |
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. Es la misma estructura traducida a JSON, lo cual facilita mantener las dos vías con un modelo de datos común.| 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 = 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 | Venció el tiempo de vida del token | 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 | Sólo asume el 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 folio del paquete vigente |
Máximo de documentos en docs |
Los que se encuentren |
| Timeout | 60 segundos en el servidor front |
4.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. CFDI + Timbrado · API REST · JsonServiceCall · 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. CFDI + Timbrado · API REST · JsonServiceCall · cierres de ejercicio.
RequestTransaction o por SOAP, que sí reciben el año, y repórtalo a Soporte. Problema. Ante result = false, el ERP interpreta que el comprobante no fue emitido y reintenta la emisión, generando un CFDI duplicado.
Entorno. CFDI + Timbrado · API REST · JsonServiceCall · 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. CFDI + Timbrado · API REST · JsonServiceCall · 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. CFDI + Timbrado · API REST · JsonServiceCall · 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 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. La capa que interpreta payload falla, aunque funciona con las transacciones de emisión.
Entorno. CFDI + Timbrado · API REST · JsonServiceCall · 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 tres elementos y hacen falta dos. Escribe una capa de lectura por transacción.
Causa. Las transacciones de esta vía 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.
El Número Interno es opcional en el esquema, 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. Es un detalle menor que se vuelve importante precisamente en el escenario para el que existe esta transacción, cuando el proceso ya va a tientas y conviene no añadir un error de autenticación encima.
Los nombres de los campos de docs —ctry, taxId, uuid, batch, serial y el resto— son exactamente los del XML DocsFoundBy que devuelve esta misma transacción 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 las dos vías 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 tres 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, los nombres de los campos de respuesta y la convención de éxito. 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