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

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

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


De un vistazo


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.


La regla operativa cabe en una frase: para implementar la lógica de no duplicidad basta con leer numDocs. Si el comprobante ya existe, no vuelvas a enviarlo a generar.
Esta vía no recibe el año como criterio. A diferencia de las modalidades SOAP y RequestTransaction, aquí solo puedes acotar por Número Interno y por Sucursal.


Cómo saber si este es tu artículo

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


Requisitos previos

  • Un token vigente, obtenido con AUTHENTICATE.
  • Que tu ERP haya enviado el Número Interno al emitir. Sin ese dato la consulta no encuentra nada y te quedas sin verificación antiduplicado para ese comprobante.
  • Que el Número Interno sea único por comprobante en tu sistema. Si lo reutilizas, el conteo pierde valor como señal de duplicado.
  • La Sucursal, si quieres acotar la búsqueda.


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. Recupera de tu ERP el Número Interno del comprobante cuya emisión quieres verificar.
    Resultado: el criterio de búsqueda.
  3. Construye el objeto JSON de criterios con internalid y, si quieres acotar, branch.
    Resultado: un JSON válido de uno o dos campos.
  4. Codifica ese objeto en Base64, sin saltos de línea intermedios.
    Resultado: la cadena que vas a poner en jsonData.
  5. 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 LOOKUP_ISSUED_INTERNAL_ID.
    Resultado: petición lista.
  6. Envía la petición al recurso /JsonServiceCall.
    Resultado: respuesta con un cuerpo JSON de cinco campos.
  7. 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.
  8. Guarda el nuevo token de la respuesta, sustituyendo el anterior.
    Resultado: sesión viva para la siguiente llamada.
  9. Decodifica payload desde Base64. Obtienes directamente el objeto de resultado, sin envoltura.
    Resultado: el conteo en numDocs y el detalle en docs.
  10. Interpreta numDocs antes de decidir si reintentas la emisión:
    • 0 — no existe comprobante con ese Número Interno. Puedes volver a emitir.
    • 1 — el comprobante ya se emitió. No reintentes. Toma el uuid del detalle para actualizar tu ERP.
    • Mayor que 1 — existe más de un comprobante con el mismo Número Interno. No reintentes y revisa internamente el caso.

    Resultado: decisión de reintento tomada sobre evidencia, no sobre suposición.
  11. Actualiza tu ERP con el Folio Fiscal, la serie y el folio obtenidos del detalle, cerrando el ciclo del comprobante que había quedado en estado indeterminado.
    Resultado: comprobante conciliado, sin duplicado emitido.

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 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
El nombre no lleva sufijo 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.


2. Ambientes

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.


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.
Ojo con el orden en la recuperación de un TimeOut. Si la emisión no devolvió respuesta, tampoco devolvió token nuevo, así que el token válido sigue siendo el que tenías antes de emitir. Úsalo para esta consulta en lugar de autenticarte de nuevo por reflejo.


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


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

{
"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
Aquí no se envía el año. Las modalidades SOAP y 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. 


6. Ejemplo de request

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


7. Ejemplo de response

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": "..." }
]
}


8. Estructura de respuesta — éxito

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. 


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


Cada elemento de 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
Los nombres de estos campos coinciden uno a uno con los del XML 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.


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
Distinción crítica para la lógica antiduplicado. 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.


10. Códigos de Error

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
Aquí todos los códigos son seguros de reintentar. Es una consulta: reintentarla no produce efectos sobre ningún comprobante. Lo que nunca debes hacer ante un error es dar por buena la ausencia del comprobante y reintentar la emisión.


11. Límites y comportamiento

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


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. Por eso su nombre no lleva el sufijo 4.
  • El Número Interno es un dato de tu sistema, no del comprobante fiscal: la plataforma lo conserva asociado al CFDI pero no forma parte de lo que el SAT valida.
  • MYSuite no impone la unicidad del Número Interno. Garantizarla es responsabilidad de tu sistema administrativo, y de ello depende que el conteo sea una señal fiable.
  • Esta transacción no sustituye la verificación del estado del comprobante ante el SAT: informa de lo que MYSuite tiene almacenado.
Solución de problemas

"Me devuelve 0 aunque sé que la factura se timbró"


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.

Causa. El caso más frecuente en integraciones nuevas es el Número Interno ausente en el Nativo.

"Consulto en enero una factura de diciembre y no aparece"


Problema. La consulta no encuentra comprobantes emitidos en el ejercicio anterior.

Entorno. CFDI + Timbrado · API REST · JsonServiceCall · cierres de ejercicio.

Resolución. Esta vía no admite el año como criterio, de modo que no puedes ampliar el alcance desde la petición. Si te ocurre, consúltalo por RequestTransaction o por SOAP, que sí reciben el año, y repórtalo a Soporte. 
Causa. Comportamiento sin documentar.

"La consulta me da error y asumo que la factura no existe"


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.

"Tras un TimeOut en la emisión, la consulta también falla"


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.

"Me devuelve más de un comprobante con el mismo número interno"


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.

"Mi código de lectura del payload no encuentra los campos"


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.


Para entender más

El problema que esta transacción resuelve

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.

Por qué la búsqueda se hace por Número Interno

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.

Por qué el Número Interno es responsabilidad tuya

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.

Por qué basta con leer un campo

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.

Por qué es seguro reintentar esta transacción

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.

Un detalle del orden que conviene prever

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.

La misma estructura en dos serializaciones

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.

Por qué cada vía se documenta por separado

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.


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