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.
JsonServiceCall. Al ir sin codificar, el JSON queda sujeto a las reglas de XML y tienes que escapar los caracteres especiales: & como &, < como < y > como >.AUTHENTICATE. El token rota en cada llamada: la petición siguiente debe usar el último token devuelto, no el original.| 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) |
AUTHENTICATE.NativoJSONFull40.json.JES900109Q90 como emisor y un receptor del catálogo autorizado. Ver apartado 2.AUTHENTICATE, o toma el último que te devolvió la transacción anterior.NativoJSONFull40.json.&, < y >. Aquí no hay Base64 que te proteja de ellos.ws:JsonServiceCall y sus tres elementos hijos: ws:jsonData con el JSON, ws:transactionName con el literal CONVERT_NATIVE_XML_BASIC4 y ws:token con el token vigente.factwsfront.asmx del ambiente que te corresponda.JsonServiceCallResult y analízalo como JSON. No lo recorras como XML.Result, Payload, ErrorMsg, ErrorCode y Token.Result y comprueba que ErrorCode sea 0.Token de la respuesta, sustituyendo el anterior.Payload desde Base64. Aquí obtienes directamente el objeto de metadatos: no viene envuelto, como sí ocurre en las otras dos variantes.Si algo falla, ve a Solución de problemas.
| Arquitectura | Híbrida. Sobre SOAP en la petición y en la respuesta; JSON crudo en la petición y JSON dentro del elemento de resultado en la respuesta |
|---|---|
| Versión de SOAP | SOAP 1.2 · espacio de nombres http://www.w3.org/2003/05/soap-envelope |
| Espacio de nombres del servicio | http://www.fact.com.mx/schema/ws |
| Operación SOAP | JsonServiceCall, dentro de soap:Body |
| Transacción | 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 |
ws:JsonServiceCall; lo que cambia es el literal de ws:transactionName. EndPoint expone solo dos operaciones: ésta y Authenticate.| 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 |
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.H&E951128469, S&S051221SE2 o L&O950913MSA, ese carácter tiene que ir escapado dentro del sobre. Ver el apartado 5.| Elemento | Tipo | Obligatorio | Descripción |
|---|---|---|---|
ws:token |
string | Sí | Valor obtenido de la transacción AUTHENTICATE, o el último devuelto por cualquier transacción posterior |
El elemento ws:JsonServiceCall lleva tres elementos hijos.
| Elemento | Tipo | Obligatorio | Formato | Descripción |
|---|---|---|---|---|
ws:jsonData |
string | Sí | JSON crudo, escapado para XML | Los datos en forma de objeto JSON que conforman la materia prima para 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 |
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.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 |
| Carácter | Escapado como | Dónde aparece con frecuencia |
|---|---|---|
& |
& |
Razones sociales, nombres comerciales, descripciones de conceptos |
< |
< |
Descripciones de conceptos, notas del comprobante |
> |
> |
Descripciones de conceptos, notas del comprobante |
| 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 |
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><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>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
}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.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.| 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 |
| 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
|
| 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 |
| 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 |
4 del nombre lo refleja..asmx que atiende EndPoint es el mismo que atiende la modalidad SOAP clásica. Un cambio en ese servicio afecta a ambas modalidades.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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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é.
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.
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—.
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.
| Transacción | XML del CFDI | 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.
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.
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.
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.