CONVERT_NATIVE_XML_BASIC4 — SERVICIO EndPoint

CONVERT_NATIVE_XML_BASIC4 — SERVICIO EndPoint

Estado Transacción: Vigente · Compatibilidad: CFDI 4.0 · JSON Nativo de MYSuite v8 · Ú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.


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


Esta transacción no te entrega el comprobante fiscal. El CFDI es el XML sellado y timbrado, y 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 emita. El timbrado es el mismo que en las otras dos variantes: el CFDI existe ante el SAT y retirarlo exige una cancelación formal.
Aquí el JSON no va en Base64: viaja crudo dentro del XML. Es la diferencia de fondo con API REST por JsonServiceCall. Al ir sin codificar, el JSON queda sujeto a las reglas de XML y tienes que escapar los caracteres especiales: & como &amp;, < como &lt; y > como &gt;.
Necesitas un token. Obtenlo con AUTHENTICATE. El token rota en cada llamada: la petición siguiente debe usar el último token devuelto, no el original.


Cómo saber si este es tu artículo

Si tu integración… Tu artículo es...
Emite CFDI 4.0 por EndPoint y solo necesita los metadatos de vuelta Este artículo
Necesita el XML del CFDI con el Nativo de MYSuite, más el PDF por EndPoint CONVERT_NATIVE_XML4 — Servicio EndPoint
Necesita el XML sin el Nativo, más el PDF por EndPoint CONVERT_NATIVE_XML_SN4 — Servicio EndPoint
Emite enviando JSON al recurso /JsonServiceCall de API REST CONVERT_NATIVE_XML_BASIC4 — CFDI + Timbrado (API REST) - JsonServiceCall
Emite por RequestTransaction, con credenciales en cada petición CONVERT_NATIVE_XML — CFDI + Timbrado (API REST) - Request Transaction
Emite enviando sobres SOAP con las operaciones clásicas y XML Nativo en XML CONVERT_NATIVE_XML — CFDI + Timbrado (SOAP)


Requisitos previos

  • Un token vigente, obtenido con AUTHENTICATE.
  • CSD del emisor cargado y vigente en la plataforma MYSuite.
  • Capacidad de tu ERP para construir el archivo nativo de MYSuite en JSON conforme a NativoJSONFull40.json.
  • Capacidad de escapar caracteres especiales al incrustar el JSON en el XML. Ver el apartado 5.
  • 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. Escapa los caracteres especiales de ese JSON antes de incrustarlo en el sobre: &, < y >. Aquí no hay Base64 que te proteja de ellos.
    Resultado: un JSON que puede viajar dentro de un elemento XML sin romperlo.
  5. Arma el sobre SOAP con el elemento ws:JsonServiceCall y sus tres elementos hijos: ws:jsonData con el JSON, ws:transactionName con el literal CONVERT_NATIVE_XML_BASIC4 y ws:token con el token vigente.
    Resultado: petición lista. El literal es lo único que la distingue de las otras dos variantes.
  6. Envía el sobre a factwsfront.asmx del ambiente que te corresponda.
    Resultado: respuesta con un sobre SOAP de vuelta.
  7. Extrae el contenido de JsonServiceCallResult y analízalo como JSON. No lo recorras como XML.
    Resultado: un objeto con Result, Payload, ErrorMsg, ErrorCode y Token.
  8. Lee Result y comprueba que ErrorCode sea 0.
    Resultado: confirmación de que el comprobante se timbró; cualquier otro valor te lleva a Solución de problemas.
  9. Guarda el nuevo Token de la respuesta, sustituyendo el anterior.
    Resultado: sesión viva para la siguiente llamada.
  10. 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.
  11. Registra en tu ERP el Folio Fiscal, la serie y el folio que vienen en esos metadatos.
    Resultado: comprobante identificado en tu sistema.
  12. 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

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 CONVERT_NATIVE_XML_BASIC4, indicada en el elemento ws:transactionName
Naturaleza Emisión. Sella y certifica un comprobante fiscal con efectos ante el SAT
Autenticación Token en el elemento ws:token, obtenido con AUTHENTICATE
Qué devuelve Solo metadatos. No devuelve XML ni PDF
Consumo 1 folio del paquete vigente por cada transacción con éxito
La operación SOAP es siempre la misma. Todas las transacciones de EndPoint se invocan con ws:JsonServiceCall; lo que cambia es el literal de ws:transactionName. EndPoint expone solo dos operaciones: ésta y Authenticate.


2. Ambientes

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
Son las mismas URL que las de la modalidad SOAP: EndPoint no es un servicio aparte, sino dos operaciones adicionales sobre el mismo servicio. Lo que te sitúa en una modalidad o en otra es la operación que invocas dentro del sobre.

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 emisores y receptores correspondan a los datos de 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 poder probar 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


Si facturas a clientes que cuentan con el caracter & por ejemplo: H&E951128469, S&S051221SE2 o L&O950913MSA, ese carácter tiene que ir escapado dentro del sobre. Ver el apartado 5.


3. Autenticación

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 token rota. Cada transacción devuelve un token nuevo que sustituye al anterior. Guárdalo en una variable que se sobrescriba, no en una constante de configuración. 


4. Parámetros de entrada

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 elaborar el CFDI. Ver apartado 5
ws:transactionName string Sí Literal Transacción. Para ésta: CONVERT_NATIVE_XML_BASIC4
ws:token string Sí Texto Valor obtenido de la transacción AUTHENTICATE
El valor de ws:transactionName es lo único que decide qué recibes de vuelta. La petición es idéntica a la de las otras dos variantes. Si tu integración escribe mal ese literal, timbrará igual pero recibirá un contenido distinto del esperado.


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

El contenido 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 Ninguna. JSON crudo, escapado conforme a las reglas de XML


Escape de caracteres: el punto que más cuesta en esta modalidad

Carácter Escapado como Dónde aparece con frecuencia
& &amp; Razones sociales, nombres comerciales, descripciones de conceptos
< &lt; Descripciones de conceptos, notas del comprobante
> &gt; Descripciones de conceptos, notas del comprobante
Facturar a cualquiera de los tres sin escapar ese carácter produce un sobre SOAP mal formado, y el servicio lo rechaza antes de llegar a procesar el comprobante. 
Envía el Número Interno. Es opcional en el esquema, pero en esta variante conviene especialmente: como no recibes archivos, el Número Interno es el único dato tuyo que te permite localizar después el comprobante 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 /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>{
"origen": "10021",
"doctype": "FACTURA",
"numero_interno": "",
"nota_comprobante_cabecera": "",
"nota_comprobante_pie": "",
"usuario": "",
"emisor": {
"rfc": "JES900109Q90",
"razon_social": "JIMENEZ ESTRADA SALAS A A",
"direccion_fiscal": {
"calle": "AV. UNIVERSIDAD",
"num_exterior": "1377 ",
"num_interior": "PISO 3",
"colonia": "AXOTLA",
"municipio": "ALVARO OBREGON",
"estado": "CDMX",
"pais": "MEXICO",
"codigo_postal": "01030",
"localidad": "COYOACAN",
"referencia": "sfsfdsf"
},
"regimen_fiscal": "601",
"lugar_expedicion": "01030",
"sucursal": "ABB",
"correo": "soporte@mysuitemex.com",
"cuenta_pago": "",
"fact_attr_adquirente": ""
},
"receptor": {
"rfc": "JES900109Q90",
"razon_social": "JIMENEZ ESTRADA SALAS A A",
"rfc_extranjero": "",
"residencia_fiscal": "",
"correo": "soporte@mysuitemex.com",
"direccion_fiscal": {
"calle": "CAMINO DE HORMIGUERAS",
"num_exterior": "173",
"num_interior": "2",
"colonia": "",
"municipio": "MADRID",
"estado": "MADRID",
"pais": "ESP",
"codigo_postal": "01030",
"localidad": "MADRID",
"referencia": "NO HAY"
},
"uso_cfdi": "G03",
"domicilio_fiscal_receptor": "01030",
"regimen_fiscal": "601"
},
"conceptos": [
{
"UUID": "7b22d26e-aa42-4c0f-9164-a629a053c6f6",
"ID": "0",
"Description": "PRUEBA CARTA PORTE",
"ListPrice": "1600",
"Discount": "100",
"Unit": "",
"ClaveProdServ": "78101801",
"ClaveUnidad": "E48",
"InfoAduanera": "",
"CuentaPredial": "",
"Taxes": [
{
"UUID": "0b2e9bd3-9adb-4478-9865-d367555adc34",
"type": "TRASLADO",
"impuesto": "002",
"tipofactor": "Tasa",
"tasacuota": "0.160000",
"taxbase": "1500.00",
"amount": "240.000000"
}
],
"Qty": "1",
"Amount": "1600.00",
"Identificacion": "",
"Partes": [
null
],
"Descripcion_Ampliada": "",
"addendas": null,
"complementos": null,
"ObjetoImp": "02",
"ACuentaTerceros": null
}
],
"totales": {
"total": "1740.00",
"subtotal": "1600.00",
"descuento": "100.00",
"moneda": "USD|2",
"factor_cambio": "1",
"impuestos_trasladados": "240.00",
"impuestos_retenidos": "0.00"
},
"fecha_emision": "",
"serie": "",
"folio": "",
"metodo_pago": "PUE",
"forma_pago": "03",
"confirmacion": "",
"condiciones_pago": "",
"exportacion": "01",
"informacion_global": null,
"cfdi_relacionados": [

],
"complementos": [
{
"name": "carta_porte31",
"content": "eyJWZXJzaW9uIjozLjEsIlRyYW5zcEludGVybmFjIjoiTm8iLCJFbnRyYWRhU2FsaWRhTWVyYyI6IiIsIlZpYUVudHJhZGFTYWxpZGEiOiIiLCJQYWlzT3JpZ2VuRGVzdGlubyI6IiIsIlRvdGFsRGlzdFJlYyI6IjIwIiwiVWJpY2FjaW9uZXMiOlt7IlRpcG9Fc3RhY2lvbiI6IiIsIkRpc3RhbmNpYVJlY29ycmlkYSI6IjIwIiwiVGlwb1ViaWNhY2lvbiI6IkRlc3Rpbm8iLCJJRFViaWNhY2lvbiI6IkRFMTIzNDU2IiwiTm9tYnJlUmVtaXRlbnRlRGVzdGluYXRhcmlvIjoiZ3VzdGF2byIsIlJGQ1JlbWl0ZW50ZURlc3RpbmF0YXJpbyI6IlhBWFgwMTAxMDEwMDAiLCJOdW1SZWdJZFRyaWIiOiIiLCJSZXNpZGVuY2lhRmlzY2FsIjoiIiwiTnVtRXN0YWNpb24iOiIiLCJOb21icmVFc3RhY2lvbiI6IiIsIk5hdmVnYWNpb25UcmFmaWNvIjoiIiwiRmVjaGFIb3JhU2FsaWRhTGxlZ2FkYSI6IjIwMjQtMDYtMjYgMTI6MDA6MDAiLCJEb21pY2lsaW8iOnsiQ2FsbGUiOiJzaSIsIk51bWVyb0V4dGVyaW9yIjoiIiwiTnVtZXJvSW50ZXJpb3IiOiIiLCJDb2xvbmlhIjoiIiwiTG9jYWxpZGFkIjoiIiwiUmVmZXJlbmNpYSI6IiIsIk11bmljaXBpbyI6IiIsIkVzdGFkbyI6ImFiY2QiLCJQYWlzIjoiQUZHIiwiQ29kaWdvUG9zdGFsIjoiMTY1MTQifSwiaWQiOiI3OGNmNjE0OC05NjNkLTQwNmUtODJiOC1iYjQ3NWE4ZjZiODQifSx7IlRpcG9Fc3RhY2lvbiI6IiIsIkRpc3RhbmNpYVJlY29ycmlkYSI6IiIsIlRpcG9VYmljYWNpb24iOiJPcmlnZW4iLCJJRFViaWNhY2lvbiI6Ik9SMTIzNDU2IiwiTm9tYnJlUmVtaXRlbnRlRGVzdGluYXRhcmlvIjoiZ3VzdGF2byIsIlJGQ1JlbWl0ZW50ZURlc3RpbmF0YXJpbyI6IlhBWFgwMTAxMDEwMDAiLCJOdW1SZWdJZFRyaWIiOiIiLCJSZXNpZGVuY2lhRmlzY2FsIjoiIiwiTnVtRXN0YWNpb24iOiIiLCJOb21icmVFc3RhY2lvbiI6IiIsIk5hdmVnYWNpb25UcmFmaWNvIjoiIiwiRmVjaGFIb3JhU2FsaWRhTGxlZ2FkYSI6IjIwMjQtMDYtMjYgMTI6MDA6MDAiLCJEb21pY2lsaW8iOnsiQ2FsbGUiOiJOTyBIQVkiLCJOdW1lcm9FeHRlcmlvciI6IiIsIk51bWVyb0ludGVyaW9yIjoiIiwiQ29sb25pYSI6IiIsIkxvY2FsaWRhZCI6IiIsIlJlZmVyZW5jaWEiOiIiLCJNdW5pY2lwaW8iOiIiLCJFc3RhZG8iOiJhYmNkIiwiUGFpcyI6IkFGRyIsIkNvZGlnb1Bvc3RhbCI6IjE2NTE0In0sImlkIjoiYzRiYTdmYzYtMzhjOC00YjAwLWJlODctZmQ1OTc3MTQzMDY1In1dLCJNZXJjYW5jaWFzIjp7IlBlc29CcnV0b1RvdGFsIjoiMTAwIiwiVW5pZGFkUGVzbyI6IktHTSIsIlBlc29OZXRvVG90YWwiOiIxMDAuMDAiLCJOdW1Ub3RhbE1lcmNhbmNpYXMiOiIxIiwiQ2FyZ29Qb3JUYXNhY2lvbiI6IjAiLCJMaXN0YU1lcmNhbmNpYSI6W3siaWQiOiJiMDdkNWEwZS0yZGE1LTRjYzUtYWNmMC05MTlkOGUzNzZiOWYiLCJCaWVuZXNUcmFuc3AiOiIyNjExMTcwMCIsIkNsYXZlU1RDQyI6IiIsIkRlc2NyaXBjaW9uIjoiTk8gSEFZIiwiQ2FudGlkYWQiOiIxIiwiQ2xhdmVVbmlkYWQiOiIxOSIsIlVuaWRhZCI6IktJTE8iLCJEaW1lbnNpb25lcyI6IjMwLzQwLzMwY20iLCJNYXRlcmlhbFBlbGlncm9zbyI6IlPDrSIsIkN2ZU1hdGVyaWFsUGVsaWdyb3NvIjoiMDI1MCIsIkVtYmFsYWplIjoiNEMxIiwiRGVzY3JpcEVtYmFsYWplIjoiY2FqYSIsIlBlc29FbktnIjoiMTAwLjAwIiwiVmFsb3JNZXJjYW5jaWEiOiIyNTAwMCIsIk1vbmVkYSI6IlVTRCIsIkZyYW5jaW9uQXJhbmNlbGFyaWEiOiIiLCJVVUlEQ29tZXJjaW9FeHQiOiIiLCJDYW50aWRhZFRyYW5zcG9ydGEiOlt7IkNhbnRpZGFkIjoiMSIsIklET3JpZ2VuIjoiT1IxMjM0NTYiLCJJRERlc3Rpbm8iOiJERTEyMzQ1NiIsIkN2ZXNUcmFuc3BvcnRlIjoiIiwiaWQiOiI3YzM1ZWNmMi04YWUxLTQ4NzQtYmUxZi0wMTE5ZjEwNTdmOTUifV0sIkRldGFsbGVNZXJjYW5jaWEiOm51bGwsIkd1aWFzSWRlbnRpZmljYWNpb24iOm51bGwsIkRvY3VtZW50YWNpb25BZHVhbmVyYSI6bnVsbCwiVGlwb01hdGVyaWEiOiIiLCJEZXNjcmlwY2lvbk1hdGVyaWEiOiIifV0sIkF1dG9UcmFuc3BvcnRlIjp7IlBlcm1TQ1QiOiJUUEFGMDEiLCJOdW1QZXJtaXNvU0NUIjoiMTIzNDU2Nzg5IiwiSWRlbnRpZmljYWNpb25WZWhpY3VsYXIiOnsiQ29uZmlnVmVoaWN1bGFyIjoiVkwiLCJQbGFjYVZNIjoiZGZnMTIzIiwiQW5pb01vZGVsb1ZNIjoiMjAyMyIsIlBlc29CcnV0b1ZlaGljdWxhciI6IjEwMCJ9LCJTZWd1cm9zIjp7IkFzZWd1cmFSZXNwQ2l2aWwiOiJheGEiLCJQb2xpemFSZXNwQ2l2aWwiOiIxMjM0NTY3ODkiLCJBc2VndXJhTWVkQW1iaWVudGUiOiJHTlAiLCJQb2xpemFNZWRBbWJpZW50ZSI6IjEyMzQ1Njc4OSIsIkFzZWd1cmFDYXJnYSI6IiIsIlBvbGl6YUNhcmdhIjoiIiwiUHJpbWFTZWd1cm8iOiIxMjAwLjAwIn0sIlJlbW9scXVlcyI6W3siU3ViVGlwb1JlbSI6IkNUUjAwMSIsIlBsYWNhIjoicXdlMTIzIn0seyJTdWJUaXBvUmVtIjoiQ1RSMDAyIiwiUGxhY2EiOiJhc2QxMjMifV19LCJUcmFuc3BvcnRlTWFyaXRpbW8iOm51bGwsIlRyYW5zcG9ydGVBZXJlbyI6bnVsbCwiVHJhbnNwb3J0ZUZlcnJvdmlhcmlvIjpudWxsLCJMb2dpc3RpY2FJbnZlcnNhUmVjb2xlY2Npb25EZXZvbHVjaW9uIjoiIn0sIkZpZ3VyYVRyYW5zcG9ydGUiOlt7IlRpcG9GaWd1cmEiOiIwMSIsIlJGQ0ZpZ3VyYSI6IkpFUzkwMDEwOVE5MCIsIk51bUxpY2VuY2lhIjoiNDU0NTQ1NDU0IiwiTm9tYnJlRmlndXJhIjoiR3VzdGF2byBEUiIsIk51bVJlZ0lkVHJpYkZpZ3VyYSI6IiIsIlJlc2lkZW5jaWFGaXNjYWxGaWd1cmEiOiIiLCJEb21pY2lsaW8iOnsiQ2FsbGUiOiJFSkVNUExPIERFIENBTEwiLCJOdW1lcm9FeHRlcmlvciI6IiIsIk51bWVyb0ludGVyaW9yIjoiIiwiQ29sb25pYSI6IiIsIkxvY2FsaWRhZCI6IiIsIlJlZmVyZW5jaWEiOiIiLCJNdW5pY2lwaW8iOiIiLCJFc3RhZG8iOiJBQkQiLCJQYWlzIjoiQUZHIiwiQ29kaWdvUG9zdGFsIjoiMTY1MTQifSwiaWQiOiIyYmE4ZDA3NS0wNzc0LTRmYmQtYmJhMS05MTM1NjBhOTMzMzgifV0sIklkQ0NQIjoiQ0NDY2NjY2MtY2NjYy1jY2NjLWNjY2MtY2NjY2NjY2NjY2NjIiwiUmVnaW1lbmVzQWR1YW5lcm8iOiIiLCJSZWdpc3Ryb0lTVE1PIjoiU8OtIiwiVWJpY2FjaW9uUG9sb09yaWdlbiI6IjAxIiwiVWJpY2FjaW9uUG9sb0Rlc3Rpbm8iOiIwMSJ9"
}
],
"addendas": [

],
"cuentas_bancarias": [

]
}</ws:jsonData>
<ws:transactionName>CONVERT_NATIVE_XML_BASIC4</ws:transactionName>
<ws:token>[último token devuelto]</ws:token>
</ws:JsonServiceCall>
</soap:Body>
</soap:Envelope>


7. Ejemplo de response

<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":"eyJDb3VudHJ5IjoiTVgiLCJFbnRpdHkiOiJKRVM5MDAxMDlROTAiLCJGaXNjYWxOYW1lIjoiSklNRU5FWiBFU1RSQURBIFNBTEFTIEEgQSIsIkFZZWFyIjoiMCIsIkFOdW1iZXIiOiIiLCJCYXRjaCI6IkFCQiIsIlNlcmlhbCI6IjE0MDE5IiwiRG9jdW1lbnRHVUlEIjoiYWEzYWE5ZGUtZDg4ZC00ZmMwLTllYzktNDQ5ODM4OTg3YWJkIiwiSXNzdWVkVGltZVN0YW1wIjoiMjAyNi0xMC0xNVQxMDowODo0OCIsIkVucm9sbGVkVGltZVN0YW1wIjpudWxsLCJQYWlkVGltZVN0YW1wIjpudWxsLCJDYW5jZWxsZWRUaW1lU3RhbXAiOm51bGwsIkludGVybmFsSUQiOiIiLCJCYXRjaElEIjpudWxsLCJCYXRjaFRpbWVTdGFtcCI6bnVsbCwiQmF0Y2hSZXF1ZXN0b3JDb3VudHJ5IjpudWxsLCJCYXRjaFJlcXVlc3RvckVudGl0eSI6bnVsbCwiQmF0Y2hQb3NpdGlvbiI6bnVsbCwiUmVjZWl2ZXJDb3VudHJ5IjoiTVgiLCJSZWNlaXZlckVudGl0eSI6IkpFUzkwMDEwOVE5MCIsIlJlY2VpdmVyVGF4SUQiOiIiLCJSZWNlaXZlck5hbWUiOiJKSU1FTkVaIEVTVFJBREEgU0FMQVMgQSBBIiwiQ2xhdmVBZ2VudGUiOiIiLCJOdW1lcm9EZVBvbGl6YSI6IiIsIkN1cnJlbmN5IjoiVVNEIiwiVG90YWxBbW91bnQiOiIxNzQwIiwiVHlwZTEiOiIiLCJUeXBlMiI6IkZBQ1RVUkEiLCJTdWdnZXN0ZWRGaWxlTmFtZSI6IkpFUzkwMDEwOVE5MF9BQkJfMTQwMTlfSkVTOTAwMTA5UTkwIiwiU3VnZ2VzdGVkRmlsZU5hbWUyIjoiMTUxMDIwMjZfX19BQkIxNDAxOV8iLCJPYnNlcnZhY2lvbmVzIjpudWxsLCJPYnNlcnZhY2lvbmVzSHRtbCI6bnVsbH0=","ErrorMsg":"","ErrorCode":0,"Token":"OxbZPD1Gd9hUomWYNBUGWkzja54cEGlnz9LLPKZY+pI0+bfE1ldh8TKjBK02xvy5zNV/JVdwwqNlj5419TpH/95vPiOCPyKnWYnPewOP7gs="}
</JsonServiceCallResult>
</JsonServiceCallResponse>
</soap:Body>
</soap:Envelope>


Contenido de Payload una vez decodificado:
{
"Country": "MX",
"Entity": "JES900109Q90",
"FiscalName": "JIMENEZ ESTRADA SALAS A A",
"AYear": "0",
"ANumber": "",
"Batch": "ABB",
"Serial": "14019",
"DocumentGUID": "aa3aa9de-d88d-4fc0-9ec9-449838987abd",
"IssuedTimeStamp": "2026-10-15T10:08:48",
"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_14019_JES900109Q90",
"SuggestedFileName2": "15102026___ABB14019_",
"Observaciones": null,
"ObservacionesHtml": null
}


8. Estructura de respuesta — éxito

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 metadatos del comprobante
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 la modalidad, 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 pdf, xml e identifier y hay que decodificar cada archivo por separado: son dos capas. Aquí obtienes el objeto de metadatos directamente, basta una. Una capa de lectura compartida entre las tres variantes se rompe al cambiar de una a otra.
Este comportamiento es el mismo en API REST por JsonServiceCall: allí también CONVERT_NATIVE_XML_BASIC4 entrega los metadatos directamente mientras las otras dos los envuelven. El patrón depende de la transacción, no del transporte, así que si ya lo resolviste en una modalidad, la lógica se traslada.


Los metadatos del comprobante

Campo Qué es
Emisor
Country · 
Entity · 
FiscalName
País, RFC y razón social del emisor
Identificación del comprobante
DocumentGUID Folio Fiscal (UUID). El dato central de esta transacción: es la llave única del comprobante y el criterio de las transacciones de recuperación
Batch · 
Serial
Serie y folio
InternalID Número Interno que tu ERP escribió en el Nativo al emitir. Vacío si no se envió
Fechas
IssuedTimeStamp Fecha y hora de emisión
EnrolledTimeStamp · 
PaidTimeStamp · 
CancelledTimeStamp
Registro, pago y cancelación. Llegan null en una emisión recién hecha
Receptor
ReceiverCountry · 
ReceiverEntity · 
ReceiverName
País, RFC y nombre del receptor
ReceiverTaxID Identificador fiscal del receptor extranjero
Importes y clasificación
Currency · 
TotalAmount
Moneda e importe total
Type1 Tipo de Comprobante del SAT
Type2 Tipo de Comprobante de MYSuite
Nombres sugeridos de archivo
SuggestedFileName Patrón: RFC del emisor, serie, folio y RFC del receptor
SuggestedFileName2 Patrón: fecha ddmmaaaa, serie y folio
Campos que no aplican aquí
BatchID · 
BatchTimeStamp · 
BatchRequestorCountry · 
BatchRequestorEntity ·
 BatchPosition
Llegan null: no aplican en operación individual
AYear · 
ANumber
En desuso
ClaveAgente · 
NumeroDePoliza
No aplican para JSON
Observaciones · 
ObservacionesHtml
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, conservar el token anterior tras un fallo


10. Códigos de Error


Código Significado Causa Remedio
0 Sin error El comprobante se timbró —
101 Token expirado La vida del token expiró 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 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 cada transacción con éxito
Idempotencia Si se envían fecha_emision, serie y folio: vacíos generan un segundo comprobante; con valores iguales se avisa que ya existe
Recuperación ante TimeOut Utilizar LOOKUP_ISSUED_INTERNAL_ID, está disponible por EndPoint. Es el mecanismo que permite verificar si un comprobante se emitió sin duplicarlo
Obtención posterior del XML RETRIEVE_DOCUMENT — SERVICIO ENDPOINT
Tamaño máximo de jsonData 1 MB
Timeout 60 segundos en servidor front


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.
  • El servicio .asmx que atiende EndPoint es el mismo que atiende la modalidad SOAP clásica. Un cambio en ese servicio afecta a ambas modalidades.

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. EndPoint · 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 ws:transactionName a CONVERT_NATIVE_XML4 o a CONVERT_NATIVE_XML_SN4. 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 ws:transactionName.

"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. EndPoint · 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.

"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. EndPoint · 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 hay que decodificar cada archivo por separado. Aquí Payload decodifica directamente al objeto de metadatos: basta una capa. 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.

"El servicio rechaza mi petición y el JSON es correcto"


Problema. El sobre es rechazado con un error de formato, aunque el JSON pasa la validación de cualquier analizador.

Entorno. EndPoint · integraciones nuevas, o migradas desde API REST.

Resolución. Revisa si el JSON contiene &, < o >. Al no ir codificado en Base64, el JSON vive dentro de un elemento XML y esos tres caracteres tienen que escaparse. El ampersand es el más frecuente, porque aparece en razones sociales: tres de los RFC del catálogo de pruebas lo llevan.

Causa. En API REST el Base64 protegía al JSON de las reglas de XML. Aquí no hay esa protección.

"Funciona con unos clientes y con otros no"


Problema. La emisión falla solo para algunos receptores, sin un patrón evidente.

Entorno. EndPoint · operación en producción.

Resolución. Compara las razones sociales de los que fallan con las de los que funcionan: lo más probable es que las primeras contengan un ampersand o alguno de los caracteres que exigen escape. Aplica el escape a todo el jsonData de forma sistemática, no caso por caso.

Causa. El escape se implementó parcialmente, o se omitió por no haber aparecido el problema con los primeros clientes probados.

"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. EndPoint · 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.

"Mi cliente SOAP no encuentra los campos de la respuesta"


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. Confunde especialmente porque el servicio es el mismo que el de la modalidad SOAP clásica, donde la respuesta sí es XML.

"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. EndPoint · integraciones nuevas.

Resolución. El token rota: la respuesta de cada emisión trae uno nuevo que sustituye al anterior. Lee el token de cada respuesta y úsalo en la llamada siguiente. Guárdalo en una variable que se sobrescriba, no en la configuración.

Causa. Se reutilizó el token inicial de AUTHENTICATE como si fuera fijo.

"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. EndPoint · 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. No tomes como referencia el ejemplo del portal: sus datos contradicen la tabla de RFC autorizados de esa misma página.

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


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 esta modalidad el ahorro es especialmente notable, porque el sobre SOAP ya añade volumen por sí mismo: quitar el XML y el PDF reduce la respuesta a una fracción de lo que ocuparía con ellos.

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.

Conviene 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 dos elementos y cada uno hay que decodificarlo aparte; aquí los metadatos son el Payload. La diferencia tiene su lógica —no tendría sentido envolver un solo elemento—.

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. El esquema lo declara opcional, pero en esta variante omitirlo equivale a renunciar a la única red de seguridad disponible.

Las tres variantes, en orden de lo que devuelven

Transacción XML del CFDI PDF Metadatos Capas de decodificación
CONVERT_NATIVE_XML4 Sí, con Nativo Sí Sí Dos
CONVERT_NATIVE_XML_SN4 Sí, sin Nativo Sí Sí Dos
CONVERT_NATIVE_XML_BASIC4 No No Sí Una

Las tres hacen el mismo timbrado y, según lo documentado en API REST, cuestan lo mismo. 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.

Por qué aquí el JSON no va codificado

En API REST, el jsonData viaja dentro de otro JSON, y codificarlo en Base64 evita tener que escapar comillas y llaves. Aquí viaja dentro de un elemento XML, donde el problema es otro: no las comillas, sino los tres caracteres que el propio XML reserva. La plataforma optó por no codificar, lo que hace la petición legible a simple vista pero traslada al integrador la responsabilidad del escape.

Un ampersand sin escapar no degrada nada, rompe el sobre entero, y el servicio rechaza la petición antes de mirar el comprobante.

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.

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, su codificación, el transporte, el modelo de credenciales y la nomenclatura 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 EndPoint


Vía JSONServiceCall

      Autenticación (obtención de token)
      Emisión
      Consulta y Recuperación
      Esquema de cancelación