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

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

Estado Transacción: Vigente · Compatibilidad: CFDI 4.0 · 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: emite un CFDI 4.0 a partir del archivo nativo de MYSuite en formato JSON y te devuelve solo los metadatos del comprobante generado: Folio Fiscal, serie, folio, emisor, receptor, moneda e importe. No devuelve el XML ni el PDF.


Cuándo se usa: cuando tu ERP ya tiene todos los datos del comprobante y lo único que necesita de vuelta es el Folio Fiscal para registrarlo. Es la variante más ligera de las tres de emisión con archivos JSON.


Cuándo no usarla: si necesitas el XML o el PDF en la misma llamada. Para el XML con el XML Nativo incluido más el PDF, usa CONVERT_NATIVE_XML4; sin el XML Nativo, CONVERT_NATIVE_XML_SN4.


Esta transacción no te entrega el comprobante fiscal (sin XML y sin PDF del CFDI). El CFDI es el XML sellado y timbrado, su conservación es obligación tuya como emisor. Si eliges esta variante, tu proceso necesita un segundo paso para recuperar y resguardar ese XML. No es opcional ni postergable: es lo que ampara la operación.
Que no devuelva archivos no significa que no se emita. El timbrado es el mismo que en las otras dos variantes: el CFDI existe ante el SAT, descuenta un folio y retirarlo exige una cancelación formal. 
Necesitas un token. Esta vía exige autenticarse primero con AUTHENTICATE, y el token rota en cada llamada: la petición siguiente debe usar el último token devuelto.


Cómo saber si este es tu artículo

Si tu integración… Tu artículo es...
Emite CFDI 4.0 por JsonServiceCall y solo necesita los metadatos de vuelta Este artículo
Necesita el XML del CFDI con el Nativo de MYSuite, más el PDF CONVERT_NATIVE_XML4 — CFDI + Timbrado (API REST) - JsonServiceCall
Necesita el XML del CFDI sin el Nativo, más el PDF CONVERT_NATIVE_XML_SN4 — CFDI + Timbrado (API REST) - JsonServiceCall
Emite por RequestTransaction, con credenciales en cada petición y XML Nativo en XML CONVERT_NATIVE_XML — CFDI + Timbrado (API REST) - Request Transaction
Emite enviando un sobre SOAP a FactWSFront CONVERT_NATIVE_XML — CFDI + Timbrado (SOAP)
Emite constancias de retenciones FIRMAR_RETENCION — CFDI + Timbrado (SOAP)


Requisitos previos

  • Un token vigente, obtenido con AUTHENTICATE.
  • CSD del emisor cargado y vigente en la plataforma MYSuite.
  • Un paquete de folios vigente con saldo: cada emisión exitosa descuenta uno.
  • Capacidad de tu ERP para construir el archivo nativo de MYSuite en JSON conforme a la estructura NativoJSONFull40.json.
  • Un procedimiento definido para recuperar y conservar el XML del comprobante, ya que esta transacción no lo devuelve.
  • Para pruebas de CFDI 4.0: usar JES900109Q90 como emisor y un receptor del catálogo autorizado. Ver apartado 2.


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. Construye el archivo nativo de MYSuite en JSON con los datos del comprobante, conforme a la estructura NativoJSONFull40.json.
    Resultado: el objeto JSON que es la materia prima del CFDI.
  3. Incluye el Número Interno de tu sistema en el Nativo. Aquí importa más que en las otras variantes: es lo que te permitirá verificar la emisión si pierdes la respuesta.
    Resultado: el comprobante queda localizable desde tu ERP.
  4. Codifica el objeto JSON 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 CONVERT_NATIVE_XML_BASIC4.
    Resultado: petición lista. El literal es lo único que la distingue de las otras dos variantes.
  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. Recuerda que en esta vía el éxito es cero, al revés que en RequestTransaction.
    Resultado: confirmación de que el comprobante se timbró y de que se descontó el folio.
  8. Guarda el nuevo token de la respuesta, sustituyendo el anterior.
    Resultado: sesión viva para la siguiente llamada.
  9. Decodifica payload desde Base64. Aquí obtienes directamente el objeto de metadatos: no viene envuelto, como sí ocurre en las otras dos variantes.
    Resultado: los metadatos del comprobante, con una sola capa de decodificación.
  10. Registra en tu ERP el Folio Fiscal, la serie y el folio que vienen en esos metadatos.
    Resultado: comprobante identificado en tu sistema.
  11. Recupera y conserva el XML del comprobante por el medio que tengas definido. Esta transacción no te lo entrega y su resguardo es tu obligación.
    Resultado: ciclo cerrado, con el comprobante fiscal en tu poder.

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 CONVERT_NATIVE_XML_BASIC4
Naturaleza Emisión. Sella y certifica un comprobante fiscal con efectos ante el SAT
Autenticación Token en el cuerpo, obtenido con AUTHENTICATE
Consumo 1 folio del paquete vigente por cada transacción con result = true. Igual que las otras dos variantes
Qué devuelve Solo metadatos. No devuelve XML ni PDF
Las tres variantes comparten recurso, petición, consumo y límites. Se distinguen únicamente por el valor de transactionName y por lo que devuelven.


2. Ambientes

Ambiente URL
Pruebas https://api.mysuitetest.com/JsonServiceCall
Producción https://api.mysuitecfdi.com/JsonServiceCall

Restricción del ambiente de pruebas para CFDI 4.0

Para probar CFDI 4.0 y sus complementos, solo pueden emplearse los RFC del catálogo autorizado como receptores, y JES900109Q90 es el único que puede emplearse también como emisor. El SAT exige que el RFC, el nombre y el código postal de emisor y receptor coincidan con la Lista de RFC Inscritos, exige además que el nombre del certificado CSD corresponda al dato del CFDI, y no publica esa lista con los datos nuevos. El catálogo cerrado es la única forma de ejercitar todas las validaciones de la versión 4.0.
Los RFC admitidos como receptores están en el catálogo de RFC autorizados para pruebas: https://soporte.mysuitemex.com/portal/es/kb/articles/rfc-s-autorizados-para-pruebas-de-cfdi-4-0-validos-para-todos-los-servicios


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 debes seguir usando el token que ya tenías. Guárdalo en una variable que solo se sobrescriba cuando llegue un valor válido. 


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 elaborar el CFDI.  Ver apartado 5
token string Sí Texto Token de seguridad vigente
transactionName string Sí Literal Transacción. Para este caso: CONVERT_NATIVE_XML_BASIC4


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

El contenido de jsonData es la estructura nativa de MYSuite serializada en JSON, idéntica a la que usan las otras dos variantes.

Estructura completa Archivo NativoJSONFull40.json, adjunto al artículo fuente: JSON nativo v8 de MYSuite 
Descripción de los campos Archivo Descripcion_JSON_para_CFDI_4.0.xlsx, adjunto al artículo fuente. Los cambios de la versión 4.0 están marcados en la columna B
Codificación de transporte Base64, en una sola línea
Tamaño máximo 1 MB
El JSON Nativo y el XML Nativo no son equivalentes campo por campo. Si migras desde SOAP o desde RequestTransaction, no basta con convertir el XML a JSON.
Envía el Número Interno. Es opcional en el esquema, pero en esta variante conviene especialmente: como no recibes el XML, el Número Interno es el único dato tuyo que te permite localizar después el comprobante con LOOKUP_ISSUED_INTERNAL_ID si pierdes la respuesta.

Ejemplos de estructura disponibles

Archivo Escenario
Nativo_Ingreso_Simple_v_8.json Comprobante de ingreso ordinario
Nativo_Ingreso_Global_v_8.json Factura global
Nativo_Egreso_CFDIRelacionado_v_8.json Egreso con un comprobante relacionado
Nativo_Egreso_Dos_CFDIRelacionados_v_8.json Egreso con dos comprobantes relacionados
Nativo_Ingreso_A_Cuenta_Terceros_v_8.json Ingreso a cuenta de terceros


6. Ejemplo de request

POST /JsonServiceCall HTTP/1.1
Host: api.mysuitetest.com
Content-Type: application/json

{
"jsonData": "ewogICJvcmlnZW4iOiAiMTAwMjEiLAogICJkb2N0eXBlIjogIkZBQ1RVUkEiLAogICJudW1lcm9faW50ZXJubyI6ICIiLAogICJub3RhX2NvbXByb2JhbnRlX2NhYmVjZXJhIjogIiIsCiAgIm5vdGFfY29tcHJvYmFudGVfcGllIjogIiIsCiAgInVzdWFyaW8iOiAiIiwKICAiZW1pc29yIjogewogICAgInJmYyI6ICJKRVM5MDAxMDlROTAiLAogICAgInJhem9uX3NvY2lhbCI6ICJKSU1FTkVaIEVTVFJBREEgU0FMQVMgQSBBIiwKICAgICJkaXJlY2Npb25fZmlzY2FsIjogewogICAgICAiY2FsbGUiOiAiQVYuIFVOSVZFUlNJREFEIiwKICAgICAgIm51bV9leHRlcmlvciI6ICIxMzc3ICIsCiAgICAgICJudW1faW50ZXJpb3IiOiAiUElTTyAzIiwKICAgICAgImNvbG9uaWEiOiAiQVhPVExBIiwKICAgICAgIm11bmljaXBpbyI6ICJBTFZBUk8gT0JSRUdPTiIsCiAgICAgICJlc3RhZG8iOiAiQ0RNWCIsCiAgICAgICJwYWlzIjogIk1FWElDTyIsCiAgICAgICJjb2RpZ29fcG9zdGFsIjogIjAxMDMwIiwKICAgICAgImxvY2FsaWRhZCI6ICJDT1lPQUNBTiIsCiAgICAgICJyZWZlcmVuY2lhIjogInNmc2Zkc2YiCiAgICB9LAogICAgInJlZ2ltZW5fZmlzY2FsIjogIjYwMSIsCiAgICAibHVnYXJfZXhwZWRpY2lvbiI6ICIwMTAzMCIsCiAgICAic3VjdXJzYWwiOiAiQUJCIiwKICAgICJjb3JyZW8iOiAic29wb3J0ZUBteXN1aXRlbWV4LmNvbSIsCiAgICAiY3VlbnRhX3BhZ28iOiAiIiwKICAgICJmYWN0X2F0dHJfYWRxdWlyZW50ZSI6ICIiCiAgfSwKICAicmVjZXB0b3IiOiB7CiAgICAicmZjIjogIkpFUzkwMDEwOVE5MCIsCiAgICAicmF6b25fc29jaWFsIjogIkpJTUVORVogRVNUUkFEQSBTQUxBUyBBIEEiLAogICAgInJmY19leHRyYW5qZXJvIjogIiIsCiAgICAicmVzaWRlbmNpYV9maXNjYWwiOiAiIiwKICAgICJjb3JyZW8iOiAic29wb3J0ZUBteXN1aXRlbWV4LmNvbSIsCiAgICAiZGlyZWNjaW9uX2Zpc2NhbCI6IHsKICAgICAgImNhbGxlIjogIkNBTUlOTyBERSBIT1JNSUdVRVJBUyIsCiAgICAgICJudW1fZXh0ZXJpb3IiOiAiMTczIiwKICAgICAgIm51bV9pbnRlcmlvciI6ICIyIiwKICAgICAgImNvbG9uaWEiOiAiIiwKICAgICAgIm11bmljaXBpbyI6ICJNQURSSUQiLAogICAgICAiZXN0YWRvIjogIk1BRFJJRCIsCiAgICAgICJwYWlzIjogIkVTUCIsCiAgICAgICJjb2RpZ29fcG9zdGFsIjogIjAxMDMwIiwKICAgICAgImxvY2FsaWRhZCI6ICJNQURSSUQiLAogICAgICAicmVmZXJlbmNpYSI6ICJOTyBIQVkiCiAgICB9LAogICAgInVzb19jZmRpIjogIkcwMyIsCiAgICAiZG9taWNpbGlvX2Zpc2NhbF9yZWNlcHRvciI6ICIwMTAzMCIsCiAgICAicmVnaW1lbl9maXNjYWwiOiAiNjAxIgogIH0sCiAgImNvbmNlcHRvcyI6IFsKICAgIHsKICAgICAgIlVVSUQiOiAiN2IyMmQyNmUtYWE0Mi00YzBmLTkxNjQtYTYyOWEwNTNjNmY2IiwKICAgICAgIklEIjogIjAiLAogICAgICAiRGVzY3JpcHRpb24iOiAiUFJVRUJBIENBUlRBIFBPUlRFIiwKICAgICAgIkxpc3RQcmljZSI6ICIxNjAwIiwKICAgICAgIkRpc2NvdW50IjogIjEwMCIsCiAgICAgICJVbml0IjogIiIsCiAgICAgICJDbGF2ZVByb2RTZXJ2IjogIjc4MTAxODAxIiwKICAgICAgIkNsYXZlVW5pZGFkIjogIkU0OCIsCiAgICAgICJJbmZvQWR1YW5lcmEiOiAiIiwKICAgICAgIkN1ZW50YVByZWRpYWwiOiAiIiwKICAgICAgIlRheGVzIjogWwogICAgICAgIHsKICAgICAgICAgICJVVUlEIjogIjBiMmU5YmQzLTlhZGItNDQ3OC05ODY1LWQzNjc1NTVhZGMzNCIsCiAgICAgICAgICAidHlwZSI6ICJUUkFTTEFETyIsCiAgICAgICAgICAiaW1wdWVzdG8iOiAiMDAyIiwKICAgICAgICAgICJ0aXBvZmFjdG9yIjogIlRhc2EiLAogICAgICAgICAgInRhc2FjdW90YSI6ICIwLjE2MDAwMCIsCiAgICAgICAgICAidGF4YmFzZSI6ICIxNTAwLjAwIiwKICAgICAgICAgICJhbW91bnQiOiAiMjQwLjAwMDAwMCIKICAgICAgICB9CiAgICAgIF0sCiAgICAgICJRdHkiOiAiMSIsCiAgICAgICJBbW91bnQiOiAiMTYwMC4wMCIsCiAgICAgICJJZGVudGlmaWNhY2lvbiI6ICIiLAogICAgICAiUGFydGVzIjogWwogICAgICAgIG51bGwKICAgICAgXSwKICAgICAgIkRlc2NyaXBjaW9uX0FtcGxpYWRhIjogIiIsCiAgICAgICJhZGRlbmRhcyI6IG51bGwsCiAgICAgICJjb21wbGVtZW50b3MiOiBudWxsLAogICAgICAiT2JqZXRvSW1wIjogIjAyIiwKICAgICAgIkFDdWVudGFUZXJjZXJvcyI6IG51bGwKICAgIH0KICBdLAogICJ0b3RhbGVzIjogewogICAgInRvdGFsIjogIjE3NDAuMDAiLAogICAgInN1YnRvdGFsIjogIjE2MDAuMDAiLAogICAgImRlc2N1ZW50byI6ICIxMDAuMDAiLAogICAgIm1vbmVkYSI6ICJVU0R8MiIsCiAgICAiZmFjdG9yX2NhbWJpbyI6ICIxIiwKICAgICJpbXB1ZXN0b3NfdHJhc2xhZGFkb3MiOiAiMjQwLjAwIiwKICAgICJpbXB1ZXN0b3NfcmV0ZW5pZG9zIjogIjAuMDAiCiAgfSwKICAiZmVjaGFfZW1pc2lvbiI6ICIiLAogICJzZXJpZSI6ICIiLAogICJmb2xpbyI6ICIiLAogICJtZXRvZG9fcGFnbyI6ICJQVUUiLAogICJmb3JtYV9wYWdvIjogIjAzIiwKICAiY29uZmlybWFjaW9uIjogIiIsCiAgImNvbmRpY2lvbmVzX3BhZ28iOiAiIiwKICAiZXhwb3J0YWNpb24iOiAiMDEiLAogICJpbmZvcm1hY2lvbl9nbG9iYWwiOiBudWxsLAogICJjZmRpX3JlbGFjaW9uYWRvcyI6IFsKICAgIAogIF0sCiAgImNvbXBsZW1lbnRvcyI6IFsKICAgIHsKICAgICAgIm5hbWUiOiAiY2FydGFfcG9ydGUzMSIsCiAgICAgICJjb250ZW50IjogImV5SldaWEp6YVc5dUlqb3pMakVzSWxSeVlXNXpjRWx1ZEdWeWJtRmpJam9pVG04aUxDSkZiblJ5WVdSaFUyRnNhV1JoVFdWeVl5STZJaUlzSWxacFlVVnVkSEpoWkdGVFlXeHBaR0VpT2lJaUxDSlFZV2x6VDNKcFoyVnVSR1Z6ZEdsdWJ5STZJaUlzSWxSdmRHRnNSR2x6ZEZKbFl5STZJakl3SWl3aVZXSnBZMkZqYVc5dVpYTWlPbHQ3SWxScGNHOUZjM1JoWTJsdmJpSTZJaUlzSWtScGMzUmhibU5wWVZKbFkyOXljbWxrWVNJNklqSXdJaXdpVkdsd2IxVmlhV05oWTJsdmJpSTZJa1JsYzNScGJtOGlMQ0pKUkZWaWFXTmhZMmx2YmlJNklrUkZNVEl6TkRVMklpd2lUbTl0WW5KbFVtVnRhWFJsYm5SbFJHVnpkR2x1WVhSaGNtbHZJam9pWjNWemRHRjJieUlzSWxKR1ExSmxiV2wwWlc1MFpVUmxjM1JwYm1GMFlYSnBieUk2SWxoQldGZ3dNVEF4TURFd01EQWlMQ0pPZFcxU1pXZEpaRlJ5YVdJaU9pSWlMQ0pTWlhOcFpHVnVZMmxoUm1selkyRnNJam9pSWl3aVRuVnRSWE4wWVdOcGIyNGlPaUlpTENKT2IyMWljbVZGYzNSaFkybHZiaUk2SWlJc0lrNWhkbVZuWVdOcGIyNVVjbUZtYVdOdklqb2lJaXdpUm1WamFHRkliM0poVTJGc2FXUmhUR3hsWjJGa1lTSTZJakl3TWpRdE1EWXRNallnTVRJNk1EQTZNREFpTENKRWIyMXBZMmxzYVc4aU9uc2lRMkZzYkdVaU9pSnphU0lzSWs1MWJXVnliMFY0ZEdWeWFXOXlJam9pSWl3aVRuVnRaWEp2U1c1MFpYSnBiM0lpT2lJaUxDSkRiMnh2Ym1saElqb2lJaXdpVEc5allXeHBaR0ZrSWpvaUlpd2lVbVZtWlhKbGJtTnBZU0k2SWlJc0lrMTFibWxqYVhCcGJ5STZJaUlzSWtWemRHRmtieUk2SW1GaVkyUWlMQ0pRWVdseklqb2lRVVpISWl3aVEyOWthV2R2VUc5emRHRnNJam9pTVRZMU1UUWlmU3dpYVdRaU9pSTNPR05tTmpFME9DMDVOak5rTFRRd05tVXRPREppT0MxaVlqUTNOV0U0WmpaaU9EUWlmU3g3SWxScGNHOUZjM1JoWTJsdmJpSTZJaUlzSWtScGMzUmhibU5wWVZKbFkyOXljbWxrWVNJNklpSXNJbFJwY0c5VlltbGpZV05wYjI0aU9pSlBjbWxuWlc0aUxDSkpSRlZpYVdOaFkybHZiaUk2SWs5U01USXpORFUySWl3aVRtOXRZbkpsVW1WdGFYUmxiblJsUkdWemRHbHVZWFJoY21sdklqb2laM1Z6ZEdGMmJ5SXNJbEpHUTFKbGJXbDBaVzUwWlVSbGMzUnBibUYwWVhKcGJ5STZJbGhCV0Znd01UQXhNREV3TURBaUxDSk9kVzFTWldkSlpGUnlhV0lpT2lJaUxDSlNaWE5wWkdWdVkybGhSbWx6WTJGc0lqb2lJaXdpVG5WdFJYTjBZV05wYjI0aU9pSWlMQ0pPYjIxaWNtVkZjM1JoWTJsdmJpSTZJaUlzSWs1aGRtVm5ZV05wYjI1VWNtRm1hV052SWpvaUlpd2lSbVZqYUdGSWIzSmhVMkZzYVdSaFRHeGxaMkZrWVNJNklqSXdNalF0TURZdE1qWWdNVEk2TURBNk1EQWlMQ0pFYjIxcFkybHNhVzhpT25zaVEyRnNiR1VpT2lKT1R5QklRVmtpTENKT2RXMWxjbTlGZUhSbGNtbHZjaUk2SWlJc0lrNTFiV1Z5YjBsdWRHVnlhVzl5SWpvaUlpd2lRMjlzYjI1cFlTSTZJaUlzSWt4dlkyRnNhV1JoWkNJNklpSXNJbEpsWm1WeVpXNWphV0VpT2lJaUxDSk5kVzVwWTJsd2FXOGlPaUlpTENKRmMzUmhaRzhpT2lKaFltTmtJaXdpVUdGcGN5STZJa0ZHUnlJc0lrTnZaR2xuYjFCdmMzUmhiQ0k2SWpFMk5URTBJbjBzSW1sa0lqb2lZelJpWVRkbVl6WXRNemhqT0MwMFlqQXdMV0psT0RjdFptUTFPVGMzTVRRek1EWTFJbjFkTENKTlpYSmpZVzVqYVdGeklqcDdJbEJsYzI5Q2NuVjBiMVJ2ZEdGc0lqb2lNVEF3SWl3aVZXNXBaR0ZrVUdWemJ5STZJa3RIVFNJc0lsQmxjMjlPWlhSdlZHOTBZV3dpT2lJeE1EQXVNREFpTENKT2RXMVViM1JoYkUxbGNtTmhibU5wWVhNaU9pSXhJaXdpUTJGeVoyOVFiM0pVWVhOaFkybHZiaUk2SWpBaUxDSk1hWE4wWVUxbGNtTmhibU5wWVNJNlczc2lhV1FpT2lKaU1EZGtOV0V3WlMweVpHRTFMVFJqWXpVdFlXTm1NQzA1TVRsa09HVXpOelppT1dZaUxDSkNhV1Z1WlhOVWNtRnVjM0FpT2lJeU5qRXhNVGN3TUNJc0lrTnNZWFpsVTFSRFF5STZJaUlzSWtSbGMyTnlhWEJqYVc5dUlqb2lUazhnU0VGWklpd2lRMkZ1ZEdsa1lXUWlPaUl4SWl3aVEyeGhkbVZWYm1sa1lXUWlPaUl4T1NJc0lsVnVhV1JoWkNJNklrdEpURThpTENKRWFXMWxibk5wYjI1bGN5STZJak13THpRd0x6TXdZMjBpTENKTllYUmxjbWxoYkZCbGJHbG5jbTl6YnlJNklsUERyU0lzSWtOMlpVMWhkR1Z5YVdGc1VHVnNhV2R5YjNOdklqb2lNREkxTUNJc0lrVnRZbUZzWVdwbElqb2lORU14SWl3aVJHVnpZM0pwY0VWdFltRnNZV3BsSWpvaVkyRnFZU0lzSWxCbGMyOUZia3RuSWpvaU1UQXdMakF3SWl3aVZtRnNiM0pOWlhKallXNWphV0VpT2lJeU5UQXdNQ0lzSWsxdmJtVmtZU0k2SWxWVFJDSXNJa1p5WVc1amFXOXVRWEpoYm1ObGJHRnlhV0VpT2lJaUxDSlZWVWxFUTI5dFpYSmphVzlGZUhRaU9pSWlMQ0pEWVc1MGFXUmhaRlJ5WVc1emNHOXlkR0VpT2x0N0lrTmhiblJwWkdGa0lqb2lNU0lzSWtsRVQzSnBaMlZ1SWpvaVQxSXhNak0wTlRZaUxDSkpSRVJsYzNScGJtOGlPaUpFUlRFeU16UTFOaUlzSWtOMlpYTlVjbUZ1YzNCdmNuUmxJam9pSWl3aWFXUWlPaUkzWXpNMVpXTm1NaTA0WVdVeExUUTROelF0WW1VeFppMHdNVEU1WmpFd05UZG1PVFVpZlYwc0lrUmxkR0ZzYkdWTlpYSmpZVzVqYVdFaU9tNTFiR3dzSWtkMWFXRnpTV1JsYm5ScFptbGpZV05wYjI0aU9tNTFiR3dzSWtSdlkzVnRaVzUwWVdOcGIyNUJaSFZoYm1WeVlTSTZiblZzYkN3aVZHbHdiMDFoZEdWeWFXRWlPaUlpTENKRVpYTmpjbWx3WTJsdmJrMWhkR1Z5YVdFaU9pSWlmVjBzSWtGMWRHOVVjbUZ1YzNCdmNuUmxJanA3SWxCbGNtMVRRMVFpT2lKVVVFRkdNREVpTENKT2RXMVFaWEp0YVhOdlUwTlVJam9pTVRJek5EVTJOemc1SWl3aVNXUmxiblJwWm1sallXTnBiMjVXWldocFkzVnNZWElpT25zaVEyOXVabWxuVm1Wb2FXTjFiR0Z5SWpvaVZrd2lMQ0pRYkdGallWWk5Jam9pWkdabk1USXpJaXdpUVc1cGIwMXZaR1ZzYjFaTklqb2lNakF5TXlJc0lsQmxjMjlDY25WMGIxWmxhR2xqZFd4aGNpSTZJakV3TUNKOUxDSlRaV2QxY205eklqcDdJa0Z6WldkMWNtRlNaWE53UTJsMmFXd2lPaUpoZUdFaUxDSlFiMnhwZW1GU1pYTndRMmwyYVd3aU9pSXhNak0wTlRZM09Ea2lMQ0pCYzJWbmRYSmhUV1ZrUVcxaWFXVnVkR1VpT2lKSFRsQWlMQ0pRYjJ4cGVtRk5aV1JCYldKcFpXNTBaU0k2SWpFeU16UTFOamM0T1NJc0lrRnpaV2QxY21GRFlYSm5ZU0k2SWlJc0lsQnZiR2w2WVVOaGNtZGhJam9pSWl3aVVISnBiV0ZUWldkMWNtOGlPaUl4TWpBd0xqQXdJbjBzSWxKbGJXOXNjWFZsY3lJNlczc2lVM1ZpVkdsd2IxSmxiU0k2SWtOVVVqQXdNU0lzSWxCc1lXTmhJam9pY1hkbE1USXpJbjBzZXlKVGRXSlVhWEJ2VW1WdElqb2lRMVJTTURBeUlpd2lVR3hoWTJFaU9pSmhjMlF4TWpNaWZWMTlMQ0pVY21GdWMzQnZjblJsVFdGeWFYUnBiVzhpT201MWJHd3NJbFJ5WVc1emNHOXlkR1ZCWlhKbGJ5STZiblZzYkN3aVZISmhibk53YjNKMFpVWmxjbkp2ZG1saGNtbHZJanB1ZFd4c0xDSk1iMmRwYzNScFkyRkpiblpsY25OaFVtVmpiMnhsWTJOcGIyNUVaWFp2YkhWamFXOXVJam9pSW4wc0lrWnBaM1Z5WVZSeVlXNXpjRzl5ZEdVaU9sdDdJbFJwY0c5R2FXZDFjbUVpT2lJd01TSXNJbEpHUTBacFozVnlZU0k2SWtwRlV6a3dNREV3T1ZFNU1DSXNJazUxYlV4cFkyVnVZMmxoSWpvaU5EVTBOVFExTkRVMElpd2lUbTl0WW5KbFJtbG5kWEpoSWpvaVIzVnpkR0YyYnlCRVVpSXNJazUxYlZKbFowbGtWSEpwWWtacFozVnlZU0k2SWlJc0lsSmxjMmxrWlc1amFXRkdhWE5qWVd4R2FXZDFjbUVpT2lJaUxDSkViMjFwWTJsc2FXOGlPbnNpUTJGc2JHVWlPaUpGU2tWTlVFeFBJRVJGSUVOQlRFd2lMQ0pPZFcxbGNtOUZlSFJsY21sdmNpSTZJaUlzSWs1MWJXVnliMGx1ZEdWeWFXOXlJam9pSWl3aVEyOXNiMjVwWVNJNklpSXNJa3h2WTJGc2FXUmhaQ0k2SWlJc0lsSmxabVZ5Wlc1amFXRWlPaUlpTENKTmRXNXBZMmx3YVc4aU9pSWlMQ0pGYzNSaFpHOGlPaUpCUWtRaUxDSlFZV2x6SWpvaVFVWkhJaXdpUTI5a2FXZHZVRzl6ZEdGc0lqb2lNVFkxTVRRaWZTd2lhV1FpT2lJeVltRTRaREEzTlMwd056YzBMVFJtWW1RdFltSmhNUzA1TVRNMU5qQmhPVE16TXpnaWZWMHNJa2xrUTBOUUlqb2lRME5EWTJOalkyTXRZMk5qWXkxalkyTmpMV05qWTJNdFkyTmpZMk5qWTJOalkyTmpJaXdpVW1WbmFXMWxibVZ6UVdSMVlXNWxjbThpT2lJaUxDSlNaV2RwYzNSeWIwbFRWRTFQSWpvaVU4T3RJaXdpVldKcFkyRmphVzl1VUc5c2IwOXlhV2RsYmlJNklqQXhJaXdpVldKcFkyRmphVzl1VUc5c2IwUmxjM1JwYm04aU9pSXdNU0o5IgogICAgfQogIF0sCiAgImFkZGVuZGFzIjogWwogICAgCiAgXSwKICAiY3VlbnRhc19iYW5jYXJpYXMiOiBbCiAgICAKICBdCn0=",
"token": "OxbZPD1Gd9hUomWYNBUGWkzja54cEGlnz9LLPKZY+pI0+bfE1ldh8TKjBK02xvy5Qw9I1BlsQejK7kHcLGsmeELyme3ZpIaDvxnW5CHGp5E=",
"transactionName": "CONVERT_NATIVE_XML_BASIC4"
}


7. Ejemplo de response

Forma de la respuesta en una emisión exitosa:

{
"result": true,
"payload": "eyJDb3VudHJ5IjoiTVgiLCJFbnRpdHkiOiJKRVM5MDAxMDlROTAiLCJGaXNjYWxOYW1lIjoiSklNRU5FWiBFU1RSQURBIFNBTEFTIEEgQSIsIkFZZWFyIjoiMCIsIkFOdW1iZXIiOiIiLCJCYXRjaCI6IkFCQiIsIlNlcmlhbCI6IjE0MDA5IiwiRG9jdW1lbnRHVUlEIjoiZjAwMmE5MDMtZTVhNi00M2Q0LTllYWMtOWY3YWJjMDQyOGYzIiwiSXNzdWVkVGltZVN0YW1wIjoiMjAyNi0xMC0xMlQxMTowNzoxNSIsIkVucm9sbGVkVGltZVN0YW1wIjpudWxsLCJQYWlkVGltZVN0YW1wIjpudWxsLCJDYW5jZWxsZWRUaW1lU3RhbXAiOm51bGwsIkludGVybmFsSUQiOiIiLCJCYXRjaElEIjpudWxsLCJCYXRjaFRpbWVTdGFtcCI6bnVsbCwiQmF0Y2hSZXF1ZXN0b3JDb3VudHJ5IjpudWxsLCJCYXRjaFJlcXVlc3RvckVudGl0eSI6bnVsbCwiQmF0Y2hQb3NpdGlvbiI6bnVsbCwiUmVjZWl2ZXJDb3VudHJ5IjoiTVgiLCJSZWNlaXZlckVudGl0eSI6IkpFUzkwMDEwOVE5MCIsIlJlY2VpdmVyVGF4SUQiOiIiLCJSZWNlaXZlck5hbWUiOiJKSU1FTkVaIEVTVFJBREEgU0FMQVMgQSBBIiwiQ2xhdmVBZ2VudGUiOiIiLCJOdW1lcm9EZVBvbGl6YSI6IiIsIkN1cnJlbmN5IjoiVVNEIiwiVG90YWxBbW91bnQiOiIxNzQwIiwiVHlwZTEiOiIiLCJUeXBlMiI6IkZBQ1RVUkEiLCJTdWdnZXN0ZWRGaWxlTmFtZSI6IkpFUzkwMDEwOVE5MF9BQkJfMTQwMDlfSkVTOTAwMTA5UTkwIiwiU3VnZ2VzdGVkRmlsZU5hbWUyIjoiMTIxMDIwMjZfX19BQkIxNDAwOV8iLCJPYnNlcnZhY2lvbmVzIjpudWxsLCJPYnNlcnZhY2lvbmVzSHRtbCI6bnVsbH0=",
"token": "OxbZPD1Gd9hUomWYNBUGWkzja54cEGlnz9LLPKZY+pI0+bfE1ldh8TKjBK02xvy5Qw9I1BlsQejK7kHcLGsmeDZxHkHRQqs9orpaHkA+fCY=",
"errorMsg": "",
"errorCode": 0

}

Contenido de payload una vez decodificado:

{
"Country": "MX",
"Entity": "JES900109Q90",
"FiscalName": "JIMENEZ ESTRADA SALAS A A",
"AYear": "0",
"ANumber": "",
"Batch": "ABB",
"Serial": "14009",
"DocumentGUID": "f002a903-e5a6-43d4-9eac-9f7abc0428f3",
"IssuedTimeStamp": "2026-10-12T11:07:15",
"EnrolledTimeStamp": null,
"PaidTimeStamp": null,
"CancelledTimeStamp": null,
"InternalID": "",
"BatchID": null,
"BatchTimeStamp": null,
"BatchRequestorCountry": null,
"BatchRequestorEntity": null,
"BatchPosition": null,
"ReceiverCountry": "MX",
"ReceiverEntity": "JES900109Q90",
"ReceiverTaxID": "",
"ReceiverName": "JIMENEZ ESTRADA SALAS A A",
"ClaveAgente": "",
"NumeroDePoliza": "",
"Currency": "USD",
"TotalAmount": "1740",
"Type1": "I",
"Type2": "FACTURA",
"SuggestedFileName": "JES900109Q90_ABB_14009_JES900109Q90",
"SuggestedFileName2": "12102026___ABB14009_",
"Observaciones": null,
"ObservacionesHtml": null
}


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 metadatos del comprobante. Ver desglose siguiente
token string Token nuevo para la siguiente llamada. Sustituye al que enviaste
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 no tiene aquí la misma forma que en las otras dos variantes. En CONVERT_NATIVE_XML4 y CONVERT_NATIVE_XML_SN4, al decodificarlo obtienes un objeto con tres elementos —pdf, xml e identifier—, y los metadatos están dentro de ese tercero. Aquí obtienes el objeto de metadatos directamente. Son dos contratos distintos.
Como consecuencia, aquí basta una capa de decodificación. En las otras dos hacen falta dos: una para payload y otra para cada archivo.


El objeto identifier

Trae los datos que la plataforma extrajo del comprobante. Siempre llega con el mismo conjunto de campos y lo que cambia es cuáles vienen poblados.

Campo Valor en este ejemplo Qué es
Emisor
Country MX País del emisor
Entity JES900109Q90 RFC del emisor
FiscalName JIMENEZ ESTRADA SALAS A A Razón social del emisor
Identificación del comprobante
DocumentGUID 46071577-cb44-4afe-9bb4-aad54739637e Folio Fiscal (UUID). Llave única del comprobante y criterio de las transacciones de recuperación
Batch ABB Serie
Serial 14005 Folio
InternalID vacío Número Interno que el ERP escribió en el XML Nativo al emitir. Vacío si no se envió
Fechas
IssuedTimeStamp 2026-10-09T11:08:32 Fecha y hora de emisión
EnrolledTimeStamp null Registro en MYSuite
PaidTimeStamp null Pago, si está registrado
CancelledTimeStamp null Cancelación registrada en MYSuite. Vacío no significa vigente ante el SAT
Receptor
ReceiverCountry MX País del receptor
ReceiverEntity JES900109Q90 RFC del receptor
ReceiverName JIMENEZ ESTRADA SALAS A A Nombre del receptor
ReceiverTaxID vacío Identificador fiscal del receptor extranjero
Importes y clasificación
Currency USD Moneda del comprobante
TotalAmount 1740 Importe total
Type1 vacío Type1 = Tipo de Comprobante SAT
Type2 FACTURA Type2 = Tipo de Comprobante MYSuite
Nombres sugeridos de archivo
SuggestedFileName JES900109Q90_ABB_14005_JES900109Q90 Patrón observado: RFC del emisor, serie, folio y RFC del receptor
SuggestedFileName2 09102026___ABB14005_ Patrón observado: fecha ddmmaaaa, serie y folio. Ver nota siguiente
Lote
BatchID · BatchTimeStamp · BatchRequestorCountry · BatchRequestorEntity · BatchPosition null No aplican en operación individual.
Campos sin documentar
AYear "0" Quedó en desuso
ANumber vacío Quedó en desuso
ClaveAgente · NumeroDePoliza vacíos No aplica para JSON
Observaciones · ObservacionesHtml null Se pueblan en las transacciones de validación y recepción, no en emisión



Los nombres sugeridos de archivo siguen llegando aunque no haya archivos que nombrar. Tienen sentido si tu proceso recupera después el XML y quiere guardarlo con la misma convención que el resto de los documentos de MYSuite.


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


10. Códigos de Error

Código Significado Causa Remedio
0 Sin error El comprobante se timbró y se descontó el folio —
101 Token expirado Venció el tiempo de vida del token Autenticarte de nuevo con AUTHENTICATE y reintentar
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
Los códigos 101 y 102 son seguros de reintentar; los demás no necesariamente. Si el token caducó, el comprobante no llegó a emitirse. Ante cualquier otro error, verifica antes con LOOKUP_ISSUED_INTERNAL_ID si el comprobante se emitió: esta es una transacción con efectos fiscales.


11. Límites y comportamiento

Aspecto Valor
Comprobantes por llamada Uno
Efectos fiscales Irreversibles. El CFDI existe ante el SAT; retirarlo exige cancelación formal
Consumo de folios 1 folio del paquete vigente por emisión exitosa. El mismo que las variantes que sí devuelven archivos
Idempotencia Depende de lo que envíes. Reenviar el mismo jsonData con fecha_emision, serie y folio vacíos genera un segundo comprobante. Reenviarlo con esos valores iguales devuelve el aviso de que el CFDI ya existe en MYSuite
Recuperación ante TimeOut LOOKUP_ISSUED_INTERNAL_ID está disponible en esta vía. Requiere haber enviado el Número Interno en el Nativo
Obtención posterior del XML RETRIEVE_DOCUMENT — CFDI + Timbrado (API REST) - JsonServiceCall
Tamaño máximo de jsonData 1 MB
Timeout 60 segundos en el servidor front
La protección antiduplicado depende de que tú la actives. Si dejas serie, folio y fecha_emision vacíos para que MYSuite los asigne, cada reenvío produce un comprobante nuevo. Si los envías con valores propios, la plataforma reconoce el duplicado. Conviene decidirlo de forma consciente, no por omisión.


12. Versionado y cumplimiento

  • La transacción emite comprobantes conforme a CFDI 4.0 y al Anexo 20 vigente. El sufijo 4 del nombre lo refleja.
  • La estructura del JSON Nativo corresponde a la versión 8 del esquema Nativo de MYSuite.
  • MYSuite sella con el CSD del emisor y certifica en su calidad de PAC autorizado por el SAT.
  • La conservación del XML certificado es obligación del emisor, y esta transacción no te lo entrega. Elegirla implica comprometerse a recuperarlo por otra vía.
  • Los metadatos no sustituyen al comprobante: tienen valor operativo, no fiscal.
  • Los cambios que el SAT introdujo con la versión 4.0 están detallados en el archivo Descripcion_JSON_para_CFDI_4.0.xlsx.
  • Cancelación: los comprobantes emitidos con esta transacción se cancelan con CANCEL_XML_3 por esta misma vía.
Solución de problemas

"No me devuelve el XML ni el PDF"


Problema. La respuesta llega correcta pero no trae los archivos del comprobante.

Entorno. CFDI + Timbrado · API REST · JsonServiceCall · integraciones que cambiaron de variante.

Resolución. Es el comportamiento correcto: esta variante devuelve solo metadatos. Si necesitas los archivos en la misma llamada, cambia el valor de transactionName a CONVERT_NATIVE_XML4 o a CONVERT_NATIVE_XML_SN4. No hace falta tocar nada más de la petición. Ten presente que el comprobante que ya emitiste con esta variante sigue existiendo: no lo vuelvas a timbrar para obtener el XML.

Causa. Las tres variantes comparten petición y se distinguen solo por el literal de transactionName.

"Mi código de lectura del payload funcionaba con la otra variante"


Problema. Al cambiar de variante, la capa que interpreta payload deja de encontrar los campos.

Entorno. CFDI + Timbrado · API REST · JsonServiceCall · integraciones que usan más de una variante.

Resolución. La estructura no es la misma. En CONVERT_NATIVE_XML4 y _SN4, payload decodifica a un objeto con pdf, xml e identifier, y los metadatos están dentro de ese último. Aquí payload decodifica directamente al objeto de metadatos. Escribe una capa de lectura por variante, o detecta la forma antes de interpretarla.

Causa. Las tres variantes comparten el nombre del campo pero no su contrato.

"Timbré con esta variante y ahora no tengo el XML"


Problema. El comprobante existe ante el SAT y el emisor no conserva el archivo que lo ampara.

Entorno. CFDI + Timbrado · API REST · JsonServiceCall · procesos que no previeron el paso de recuperación.

Resolución. El Folio Fiscal está en los metadatos que sí recibiste, así que el comprobante es localizable. Recupéralo y resguárdalo cuanto antes: la conservación del XML es obligación tuya y los metadatos no la satisfacen. 
Causa. Se adoptó la variante más ligera sin añadir el paso de recuperación que exige.

"Se cayó la conexión y no sé si el comprobante se timbró"


Problema. El ERP no recibe respuesta y no puede determinar si el CFDI quedó emitido.

Entorno. CFDI + Timbrado · API REST · JsonServiceCall · redes con cortes intermitentes.

Resolución. No reintentes a ciegas: un reintento puede producir un segundo CFDI con efectos fiscales. Detén el proceso de ese comprobante y ejecuta LOOKUP_ISSUED_INTERNAL_ID con el Número Interno. Aquí esa verificación importa más que en las otras variantes: como no recibes archivos, el Número Interno es el único dato tuyo que permite rastrear el comprobante.

Causa. La emisión es irreversible. Si además no enviaste Número Interno, te quedas sin forma de verificar: envíalo siempre en esta variante.

"Reenvié el mismo comprobante y se duplicó"


Problema. Un reintento generó un segundo CFDI con efectos fiscales.

Entorno. CFDI + Timbrado · API REST · JsonServiceCall · procesos con reintento automático.

Resolución. El comportamiento depende de lo que envíes: con fecha_emision, serie y folio vacíos, cada llamada produce un comprobante nuevo; con esos valores iguales a los del envío anterior, la plataforma avisa que el CFDI ya existe. Si tu proceso reintenta de forma automática, envía serie y folio propios, o verifica antes con LOOKUP_ISSUED_INTERNAL_ID.

Causa. Dejar que MYSuite asigne la serie y el folio desactiva el reconocimiento de duplicados.

"La segunda emisión falla aunque la primera funcionó"


Problema. La integración timbra el primer comprobante y a partir del segundo recibe rechazos de token.

Entorno. CFDI + Timbrado · API REST · JsonServiceCall · integraciones nuevas.

Resolución. El token rota: la respuesta de cada emisión exitosa trae uno nuevo. Léelo de cada respuesta y úsalo en la siguiente llamada. Ten en cuenta que una respuesta de error devuelve token en null: en ese caso conserva el que ya tenías, no lo sobrescribas con el nulo.

Causa. Se reutilizó el token inicial como si fuera fijo, o se sobrescribió con el nulo de una respuesta fallida.

"Me rechaza el RFC del receptor en pruebas"


Problema. La emisión falla en el ambiente de pruebas por los datos del receptor, aunque el RFC sea real y correcto.

Entorno. CFDI + Timbrado · API REST · JsonServiceCall · pruebas de CFDI 4.0.

Resolución. En pruebas solo se admiten los receptores del catálogo autorizado, con el nombre y el código postal exactos que ese catálogo publica. Como emisor, únicamente JES900109Q90. La versión 4.0 valida el RFC contra la Lista de RFC Inscritos y el SAT no publica esa lista con los datos nuevos.

Causa. Se usaron datos de un contribuyente real, o se alteró el nombre o el código postal de uno autorizado. Conviene no tomar como referencia el ejemplo del portal, cuyos datos no son coherentes entre sí.

"Mi código de manejo de errores da falsos positivos"


Problema. La lógica que evalúa el resultado marca como error las respuestas exitosas, o al revés.

Entorno. CFDI + Timbrado · API REST · integraciones que consumen las dos vías.

Resolución. Las dos vías expresan el éxito con valores opuestos: aquí errorCode = 0 significa que no hubo error, y en RequestTransaction el éxito es codeField = 1. Tampoco coinciden los nombres: aquí es result, allí resultField.

Causa. Las dos vías del mismo servicio no comparten convención de respuesta.


Para entender más

Por qué muchos integradores eligen esta variante

El PDF es, con diferencia, lo que más pesa en una respuesta de emisión, y no todos los emisores lo necesitan: quien tiene su propio motor de impresión o entrega el comprobante por otro canal lo descarta sin más. El XML, en cambio, sí hace falta, pero no necesariamente en el instante del timbrado. Esta variante parte de esa observación: devuelve solo lo imprescindible para que el ERP sepa qué comprobante acaba de nacer, y deja el resto para cuando se necesite.

En procesos de volumen la diferencia es notable, y no solo en ancho de banda: menos contenido significa respuestas más rápidas y menos memoria por llamada, que es lo que determina cuántas emisiones simultáneas aguanta tu proceso.

El compromiso que adquieres al elegirla

El CFDI es el XML sellado y timbrado, y conservarlo es obligación del emisor. Esta transacción no te lo entrega, así que adoptarla implica comprometerse a recuperarlo por otra vía. No es un detalle de implementación que pueda quedar para después: si el proceso nunca llega a construirse, el emisor acaba con comprobantes fiscales que existen ante la autoridad y cuyo archivo no tiene.

Vale la pena plantearlo al revés de como suele plantearse: la pregunta no es «¿necesito el XML ahora?», sino «¿tengo resuelto cómo lo voy a obtener?». Si la respuesta a la segunda es no, conviene usar una de las otras dos variantes hasta que lo esté.

Por qué los metadatos no sustituyen al comprobante

Los metadatos describen el comprobante pero no son el comprobante: no llevan sello, ni timbre, ni los conceptos. Sirven para registrar la operación en tu sistema y para localizar después el archivo, que es exactamente para lo que están pensados. Confundir una cosa con la otra es el riesgo específico de esta variante, y conviene que el equipo que la implemente lo tenga claro desde el principio.

Un mismo campo con dos contratos

Las tres variantes devuelven un campo llamado payload, pero no contiene lo mismo ni tiene la misma forma. En las dos que entregan archivos, payload envuelve tres elementos y los metadatos van dentro de uno de ellos; aquí los metadatos son el payload. La diferencia tiene su lógica —no tendría sentido envolver un solo elemento— pero no está advertida en el portal, y es la clase de detalle que solo se descubre al cambiar de variante con el código ya escrito.

Aquí el Número Interno deja de ser opcional en la práctica

En las otras variantes, si pierdes la respuesta todavía te queda la posibilidad de buscar el comprobante por otros medios. Aquí no recibes archivos, de modo que el Número Interno es el único dato tuyo que viaja con el comprobante y permite localizarlo después con LOOKUP_ISSUED_INTERNAL_ID. El esquema lo declara opcional, pero en esta variante omitirlo equivale a renunciar a la única red de seguridad disponible.

Cuesta lo mismo que las demás

Las tres variantes descuentan un folio por emisión exitosa. La diferencia está en lo que recibes, no en lo que pagas, así que elegir la más ligera no ahorra dinero: ahorra tiempo, ancho de banda y memoria. Conviene saberlo para no tomar la decisión por la razón equivocada.

Las tres variantes, en orden de lo que devuelven

Transacción XML del CFDI PDF Metadatos Forma de payload
CONVERT_NATIVE_XML4 Sí, con Nativo Sí Sí Objeto de tres elementos
CONVERT_NATIVE_XML_SN4 Sí, sin Nativo Sí Sí Objeto de tres elementos
CONVERT_NATIVE_XML_BASIC4 No No Sí Metadatos directos

Por qué el catálogo de RFC de pruebas es cerrado

La versión 4.0 introdujo una validación que la 3.3 no tenía: el RFC, el nombre y el código postal del receptor deben coincidir con lo que registra la Lista de RFC Inscritos. Eso choca con un ambiente de pruebas, donde por definición los contribuyentes no son reales. El SAT no publica esa lista con los datos nuevos, así que la única manera de ejercitar la validación completa es acordar un conjunto fijo de identidades ficticias que ambas partes reconozcan.

Esa misma validación es la que delata que el ejemplo publicado en este artículo pertenece a la época anterior: un RFC y un nombre que no corresponden entre sí habrían sido aceptables en 3.3 y hoy no lo son.

Por qué cada modalidad se documenta por separado

Todas emiten el mismo comprobante con las mismas reglas fiscales. Lo que cambia es todo lo demás: el formato del documento de entrada, el modelo de credenciales, los nombres de los campos, la convención de éxito y la forma de la respuesta. Documentarlas juntas obligaría al lector a descartar la mayor parte 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