Qué es: el formato propio de MYSuite, en JSON, para entregar los datos de un comprobante. Tú envías el JSON Nativo y la plataforma construye a partir de él el CFDI conforme al Anexo 20, con su estructura, su orden de nodos y su sellado.
Para qué sirve: para que tu ERP no tenga que conocer el Anexo 20 al detalle. Entregas datos de negocio y la plataforma se encarga de la forma fiscal.
Dónde se usa: en las transacciones de emisión de API REST por JsonServiceCall y del servicio EndPoint.
numero_interno, razon_social). Dentro de conceptos los nombres van en mayúscula inicial y en inglés (Description, Qty, Amount). Y dentro de Taxes van en minúsculas sin separador (tipofactor, tasacuota). No es un error de transcripción.RequestTransaction reciben el mismo modelo de datos en XML. Los dos formatos no son equivalentes campo por campo: ni siquiera tienen la misma forma de primer nivel. Por eso cada uno tiene su propio artículo.| Si tu integración… | Tu artículo es... |
|---|---|
Envía el Nativo en JSON, por API REST con JsonServiceCall o por EndPoint | Este artículo |
Envía el Nativo en XML, por SOAP o por API REST con RequestTransaction | XML Nativo de MYSuite v8 |
| Quiere saber qué transacción usar para emitir | CONVERT_NATIVE_XML4, _SN4 o _BASIC4, en la modalidad que corresponda |
| Emite constancias de retenciones | FIRMAR_RETENCION. Ese flujo no usa el Nativo: recibe el comprobante fiscal ya armado |
NativoJSONFull40.json y la descripción de campos Descripcion_JSON_para_CFDI_4.0.xlsx.emisor, receptor, conceptos y totales, más los campos de primer nivel que identifican el comprobante.numero_interno con el identificador de tu sistema. Es opcional, pero sin él pierdes la verificación antiduplicado.conceptos los campos no se escriben como en el primer nivel.informacion_global para factura global, cfdi_relacionados, complementos o addendas.jsonData va en Base64; en EndPoint va crudo dentro del XML y hay que escapar &, < y >.Si algo falla, ve a Solución de problemas.
| Nombre | JSON Nativo de MYSuite |
|---|---|
| Versión | 8. Ver la advertencia del apartado 2 |
| Archivo de referencia | NativoJSONFull40.json |
| Descripción de campos | Descripcion_JSON_para_CFDI_4.0.xlsx |
| Compatibilidad | CFDI 4.0 |
| Claves de primer nivel | 22 |
| Formato hermano | XML Nativo de MYSuite v8, no equivalente campo por campo |
Version con valor fijo en 8, el JSON Nativo no tiene ninguna clave de versión. Verificado sobre el archivo de referencia: ninguna de sus 22 claves de primer nivel la declara.En la práctica, la versión la determina el nombre de la transacción con la que envías el documento: el sufijo 4 de CONVERT_NATIVE_XML4 y sus variantes.
El documento es un objeto con 22 claves. A diferencia del XML, aquí buena parte de los datos de identificación del comprobante vive directamente en el primer nivel.
| Clave | Tipo | Qué contiene |
|---|---|---|
origen | texto | Canal de origen de la solicitud |
doctype | texto | Tipo de documento a emitir |
numero_interno | texto | Identificador de tu sistema. Base de la verificación antiduplicado |
usuario | texto | Usuario del ERP que crea el documento |
nota_comprobante_cabecera · nota_comprobante_pie | texto | Notas a nivel comprobante para la representación gráfica |
emisor | objeto · 9 claves | RFC, razón social, dirección fiscal, régimen, lugar de expedición, sucursal, correo, cuenta de pago y atributo del adquirente |
receptor | objeto · 9 claves | RFC, razón social, dirección fiscal, uso del CFDI, régimen fiscal, domicilio fiscal, datos de extranjero y correo |
conceptos | arreglo de objetos | Los conceptos del comprobante. Ver apartado 4 |
totales | objeto · 7 claves | Total, subtotal, descuento, moneda, factor de cambio e impuestos trasladados y retenidos |
fecha_emision · serie · folio | texto | Asignación del comprobante. Determinan el comportamiento ante reenvíos |
metodo_pago · forma_pago · condiciones_pago | texto | Condiciones de pago |
confirmacion | texto | Clave de confirmación cuando el comprobante la requiere |
exportacion | texto | [4.0] Si la operación ampara una exportación |
informacion_global | objeto · 3 claves | [4.0] Periodicidad, meses y año de la factura global |
cfdi_relacionados | arreglo de objetos | Tipo de relación y listado de folios relacionados |
complementos | objeto o nulo | Complementos fiscales del SAT |
addendas | objeto o nulo | Addendas de cliente |
fx:Identificacion. Aquí están en el primer nivel. Y addendas es clave propia, mientras que en XML su equivalente es fx:ComprobanteEx.| Dónde | Convención | Ejemplos reales |
|---|---|---|
Primer nivel, emisor, receptor, totales | minúsculas con guión bajo, en español | numero_interno · fecha_emision · razon_social · codigo_postal · regimen_fiscal |
Dentro de conceptos | mayúscula inicial, en inglés | Description · ListPrice · Qty · Amount · Unit · Partes · ObjetoImp |
Dentro de Taxes | minúsculas sin separador | impuesto · tipofactor · tasacuota · taxbase · amount |
Dentro de conceptos conviven además nombres en inglés con otros en español (Partes, Identificacion, Descripcion_Ampliada, ACuentaTerceros), de modo que el criterio no es ni siquiera uniforme dentro del bloque.
| Clave | Contenido |
|---|---|
ClaveProdServ · ClaveUnidad · Unit | Claves de catálogo del SAT y unidad de medida |
Description · Descripcion_Ampliada | Descripción del concepto y su versión extendida |
Qty · ListPrice · Amount · Discount | Cantidad, valor unitario, importe y descuento |
ObjetoImp | [4.0] Si la operación es objeto de impuesto |
Taxes | Arreglo de impuestos del concepto: type, impuesto, tipofactor, tasacuota, taxbase, amount |
Partes | Arreglo de partes o componentes del concepto |
ACuentaTerceros | [4.0] Objeto con RFC, RegimenFiscal, Nombre y DomicilioFiscal |
InfoAduanera · CuentaPredial | Información aduanera y cuenta predial |
complementos · addendas | A nivel de concepto |
Descripción campo por campo. Los marcados con [4.0] son los que introdujo la versión 4.0 del CFDI.
| Campo | Descripción |
|---|---|
Origen | Estipule 1001 desde WS o 1002 desde Agente |
doctype | Tipo de documento a emitir Valores: FACTURA / NOTA_DE_CREDITO / NOTA_DE_CARGO / PAGO / CARTA_PORTE / RECIBO_DE_HONORARIOS / RECIBO_DE_ARRENDAMIENTO / RECIBO_DE_DONATIVOS / RECIBO_DE_PAGO_DE_PRIMAS / COMPROBANTE_DE_PAGO_A_PLAZOS / BOLETA |
numero_interno | Estipule un numero interno con la finalidad de evitar duplicidad (se recomienda la concatenación de la serie y folio del documento) |
usuario | Especifique el usuario que esta creando el documento (se recomienda se estipule desde donde se enta enviando el archivo, ejemplo: "SAP-Agente") |
nota_comprobante_cabecera | Incluya notas de Cabecera a nivel comprobante (general) |
nota_comprobante_pie | Incluya notas de Pie a nivel comprobante (general) |
emisor | Objeto: Emisor |
rfc | RFC del emisor del documento (solo para pruebas utilice siempre JES900109Q90) |
razon_social | Especifique el nombre de su empresa o negocio |
direccion_fiscal | Objeto: Dirección del Emisor |
calle | Especifique la calle del emisor |
num_exterior | Especifique numero exterior del emisor |
num_interior | Especifique numero interior del emisor |
colonia | Especifique colonia del emisor |
municipio | Especifique municipio del emisor |
estado | Especifique estado del emisor |
pais | Especifique pais del emisor |
codigo_postal | Especifique codigo postal del emisor |
localidad | Especifique localidad del emisor |
referencia | Especifique referencia del emisor |
regimen_fiscal | Indique el regimen fiscal del emisor "catalogo SAT" |
lugar_expedicion | Indique el codigo postal del lugar de expedición. |
sucursal | Indique la sucursal del emisor (en caso de tener varias), si no existen sucursales especifique FISCALDOM |
correo | indique el correo del emisor (le llegará una copia del CFDI generado) |
cuenta_pago | Indiqué la cuenta de pago en donde le pueden depositar |
fact_attr_adquirente [4.0] | Atributo condicional para expresar el número de operación proporcionado por el SAT cuando se trate de un comprobante a través de un PCECFDI o un PCGCFDISP. |
receptor | Objeto: Receptor |
correo | Especifique el correo del receptor, le llegará una copia del CFDI |
rfc | RFC del receptor del documento (puede indicar el RFC real de su cliente, si no es valido deberá de utilizar el de pruebas o el generico, XEXX010101000 ó XAXX010101000) |
razon_social | Especifique el nombre de su cliente, empresa o negocio a quien se le realizó la venta |
rfc_extranjero | Utilice este campo para especificar el TAXID del cliente, esto en caso de que haya especificado XEXX010101000 en el nodo RFC) |
residencia_fiscal | En caso de haber utilizado XEXX010101000 en el RFC deberá especificar la residencia fiscal (conforme catalogo SAT) |
direccion_fiscal | Objeto: Dirección del Receptor |
calle | Especifique la calle del receptor |
num_exterior | Especifique numero exterior del receptor |
num_interior | Especifique numero interior del receptor |
colonia | Especifique colonia del receptor |
municipio | Especifique municipio del receptor |
estado | Especifique estado del receptor |
pais | Especifique pais del receptor |
codigo_postal | Especifique codigo postal del receptor |
localidad | Especifique localidad del receptor |
referencia | Especifique referencia del receptor |
uso_cfdi | Especifique el uso del CFDI conforme el catalogo del SAT |
regimen_fiscal [4.0] | Atributo requerido para incorporar la clave del régimen fiscal del contribuyente receptor al que aplicará el efecto fiscal de este comprobante. |
domicilio_fiscal_receptor [4.0] | Atributo requerido para registrar el código postal del domicilio fiscal del receptor del comprobante. |
conceptos | Objeto: Conceptos |
UUID | Especifique siempre: "00000000-0000-0000-0000-000000000000" |
ID | Especifique siempre: "0" |
Description | Especifique la descripción de su producto, bien o servicio el que esta facturando o haciendo referencia |
ListPrice | Precio unitario del concepto, bien o servicio que se esta facturando |
Discount | Especifique el descuento del producto en caso de haber |
Unit | Especifique la unidad de medida (propia del emisor) |
ClaveProdServ | Especifique la clave de producto o servicio (según catalogo SAT) |
ClaveUnidad | Especifique la clave de unidad (según catalogo SAT) |
InfoAduanera | Si existe, Especifique información de aduana, conforme estructura solicitada por el SAT |
CuentaPredial | Especifique la cuenta predial, en caso de existir más de una, separarlas con una coma, ejemplo: "CuentaPredial":"122332, 454555, 8775434, 8805984" |
Taxes | Objeto: Impuesto de Linea |
type | Especifique el tipo de movimiento del impuesto (TRASLADO/RETENCION) |
impuesto | Especifique el tipo de impuesto (IVA, IEPS o ISR, conforme al catalogo SAT) |
tipofactor | Especifique el tipo de factor (TASA o CUOTA) conforme al catalogo SAT) |
tasacuota | Especifique el valor conforme el catalogo SAT |
taxbase | Especifique la base del impuesto unicamente de la linea "concepto" (Precio Unitario X Cantidad = SubtotalBaseImpto - Descuento = TotalBaseImpto) |
amount | Especifique el importe del calculo del impuesto (ejemplo: 10 X 100.00 = 1,000.00 - 50.00 = 950.00 X "ejemplo de IVA 16%" = 152.00) |
Qty | Especifique la cantidad del producto, bien o servicio que esta incluyendo en su concepto |
Amount | Especifique el importe del calculo realizado de Precio Unitario X Cantidad |
Identificacion | Especifique la identificación de su producto, bien o servicio (catalogo interno) |
Partes | Objeto: Partes que se incluyen en el producto, bien o servicio |
ObjetoImp [4.0] | Atributo requerido para expresar si la operación comercial es objeto o no de impuesto. |
RFC [4.0] | Atributo requerido para registrar la Clave del Registro Federal de Contribuyentes del contribuyente Tercero, a cuenta del que se realiza la operación. |
RegimenFiscal [4.0] | Atributo requerido para incorporar la clave del régimen del contribuyente Tercero, a cuenta del que se realiza la operación. |
Nombre [4.0] | Atributo requerido para registrar el nombre, denominación o razón social del contribuyente Tercero correspondiente con el Rfc, a cuenta del que se realiza la operación. |
DomicilioFiscal [4.0] | Atributo requerido para incorporar el código postal del domicilio fiscal del Tercero, a cuenta del que se realiza la operación. |
Descripcion_Ampliada | Especifique la descripción ampliada de su producto, bien o servicio el que esta facturando o haciendo referencia |
addendas | Especificar adenda a procesar (solicite la estructura correcta para la adenda requerida), esta información será integrada en base64 |
complementos | Especificar complemento a procesar (solicite la estructura correcta para la complemento requerido), esta información será integrada en base64 |
Identificacion | Especifique la identificación de la parte del producto, bien o servicio (catalogo interno) |
Qty | Especifique la cantidad de la parte del producto, bien o servicio que esta incluyendo en su concepto |
Description | Especifique la descripción de la parte del producto, bien o servicio el que esta facturando o haciendo referencia |
UnitPrice | Precio unitario de la parte del concepto, bien o servicio que se esta facturando |
totales | Objeto: Totales |
total | Especifique el total del comprobante (todos los conceptos con sus respectivos descuentos e impuestos) |
subtotal | Especifique el subtotal del comprobante (todos los conceptos sin sus respectivos descuentos e impuestos) |
descuento | Especifique el total de los descuentos del comprobante (los descuentos de todos los conceptos) |
moneda | Especifique la moneda del documento y su cantidad de decimales (conforme catalogo del SAT) |
factor_cambio | Especifique el tipo de cambio en caso de utilizar una moneda diferente a MXN |
impuestos_trasladados | Especifique la suma de todos los impuestos trasladados de todos los conceptos |
impuestos_retenidos | Especifique la suma de todos los impuestos retenidos de todos los conceptos |
fecha_emision | Especifique fecha de emisión en caso de quererla controlar, si se omite, toma la fecha y hora actual |
serie | Especifique la serie del documento en caso de quererla controlar, si se omite toma la que tengan configurada en su cuenta |
folio | Especifique el folio del documento en caso de quererlo controlar, si se omite toma la que tengan configurada en su cuenta |
metodo_pago | Especifique el metodo de pago (conforme catalogo del SAT) |
forma_pago | Especifique el forma de pago (conforme catalogo del SAT) |
confirmacion | Su uso solo es para comprobantes con millones de pesos y debe haber un folio de confirmación por parte del PAC |
condiciones_pago | Especifique la condición del pago (15, 30, 45 días , etc.) |
exportacion [4.0] | Atributo requerido para expresar si el comprobante ampara una operación de exportación. |
informacion_global [4.0] | Nodo condicional para precisar la información relacionada con el comprobante global. |
periodicidad [4.0] | Atributo requerido para expresar el período al que corresponde la información del comprobante global. |
meses [4.0] | Atributo requerido para expresar el mes o los meses al que corresponde la información del comprobante global. |
anno [4.0] | Atributo requerido para expresar el año al que corresponde la información del comprobante global. |
Si vienes de una integración anterior, estos son los campos nuevos o modificados que tienes que atender.
| Campo | Descripción |
|---|---|
fact_attr_adquirente [4.0] | Atributo condicional para expresar el número de operación proporcionado por el SAT cuando se trate de un comprobante a través de un PCECFDI o un PCGCFDISP. |
regimen_fiscal [4.0] | Atributo requerido para incorporar la clave del régimen fiscal del contribuyente receptor al que aplicará el efecto fiscal de este comprobante. |
domicilio_fiscal_receptor [4.0] | Atributo requerido para registrar el código postal del domicilio fiscal del receptor del comprobante. |
ObjetoImp [4.0] | Atributo requerido para expresar si la operación comercial es objeto o no de impuesto. |
RFC [4.0] | Atributo requerido para registrar la Clave del Registro Federal de Contribuyentes del contribuyente Tercero, a cuenta del que se realiza la operación. |
RegimenFiscal [4.0] | Atributo requerido para incorporar la clave del régimen del contribuyente Tercero, a cuenta del que se realiza la operación. |
Nombre [4.0] | Atributo requerido para registrar el nombre, denominación o razón social del contribuyente Tercero correspondiente con el Rfc, a cuenta del que se realiza la operación. |
DomicilioFiscal [4.0] | Atributo requerido para incorporar el código postal del domicilio fiscal del Tercero, a cuenta del que se realiza la operación. |
exportacion [4.0] | Atributo requerido para expresar si el comprobante ampara una operación de exportación. |
informacion_global [4.0] | Nodo condicional para precisar la información relacionada con el comprobante global. |
periodicidad [4.0] | Atributo requerido para expresar el período al que corresponde la información del comprobante global. |
meses [4.0] | Atributo requerido para expresar el mes o los meses al que corresponde la información del comprobante global. |
anno [4.0] | Atributo requerido para expresar el año al que corresponde la información del comprobante global. |
| Aspecto | Qué hacer |
|---|---|
| Marca de orden de bytes | No la incluyas. El archivo de referencia la trae y varios analizadores la rechazan |
| Codificación | UTF-8 |
| Serialización | Con la librería JSON de tu lenguaje, no concatenando cadenas |
| Transporte en API REST | Base64 |
| Transporte en EndPoint | Crudo dentro del XML, con &, < y > escapados |
| Archivo | Escenario |
|---|---|
Nativo_Ingreso_Simple_v_8.json | Comprobante de ingreso ordinario. El punto de partida recomendado |
Nativo_Ingreso_Global_v_8.json | Factura global, con informacion_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, con el bloque ACuentaTerceros |
NativoJSONFull40.json incluye todos los campos posibles para servir de referencia, no de plantilla: enviarlo tal cual, con sus valores de muestra, no produce un comprobante válido.El JSON Nativo no cuenta con un esquema formal de validación equivalente al fx_2010_g.xsd del formato XML. Eso deja al integrador sin la comprobación local que sí tiene la otra vía.
| Qué sí puedes comprobar por tu cuenta | Qué no |
|---|---|
| Que el JSON sea estricto y no lleve marca de orden de bytes · que los nombres coincidan carácter por carácter con la tabla del apartado 5 · que los bloques obligatorios estén presentes | Claves de catálogo del SAT · longitudes máximas · coherencia aritmética · reglas de negocio de la plataforma |
Problema. El documento pasa la validación local pero la plataforma lo rechaza, o el error apunta al primer carácter sin más detalle.
Entorno. Emisión · integraciones que partieron del archivo de referencia.
Resolución. Comprueba si el documento empieza con la marca de orden de bytes. Es invisible en cualquier editor y el archivo de referencia la trae, de modo que se hereda sin darse cuenta. Guárdalo como UTF-8 sin esa marca, o elimina sus tres primeros bytes antes de enviarlo.
Causa. El mensaje de error no menciona la marca: señala el primer carácter del documento, que parece correcto a simple vista.
Problema. El comprobante se genera pero los conceptos salen incompletos o con valores por defecto.
Entorno. Emisión · primer desarrollo del generador.
Resolución. Revisa la escritura de los nombres dentro de conceptos: ahí no se usa la convención del primer nivel. Es Description y no descripcion, Qty y no cantidad, Amount y no importe. Y dentro de Taxes cambia otra vez: tipofactor y tasacuota, en minúsculas y sin guión bajo.
Causa. El formato usa tres convenciones de nombres distintas según el bloque. Es la primera causa de error al escribir el generador.
Problema. La conversión mecánica del formato XML al JSON es rechazada.
Entorno. Migraciones entre modalidades.
Resolución. Los dos formatos no son equivalentes campo por campo, y ni siquiera comparten la forma de primer nivel: el XML tiene 14 nodos y el JSON 22 claves, con los datos repartidos de otra manera. No conviertas la sintaxis: reescribe la capa que genera el documento partiendo de los ejemplos de esta vía.
Causa. La diferencia entre modalidades no es solo de transporte, también de modelo de datos.
Problema. El envío de NativoJSONFull40.json tal cual no produce un comprobante válido.
Entorno. Primeras pruebas de integración.
Resolución. Ese archivo es una referencia, no una plantilla: incluye todos los campos posibles con valores de muestra, y varios de ellos llevan descripciones del catálogo en lugar de claves. Empieza por Nativo_Ingreso_Simple_v_8.json y ve añadiendo bloques.
Causa. Confusión entre archivo de referencia y ejemplo ejecutable.
Problema. Los errores de estructura y de catálogo se descubren con un rechazo del servicio.
Entorno. Emisión · integraciones por JSON.
Resolución. Hoy no hay un esquema formal para este formato. Mientras tanto, comprueba por tu cuenta que el JSON sea estricto, que no lleve marca de orden de bytes y que los nombres coincidan carácter por carácter con la tabla del apartado 5. Para las claves de catálogo, contéctalas contra las listas del SAT en tu propio sistema antes de enviar.
Problema. Un reintento produjo un segundo CFDI con efectos fiscales.
Entorno. Emisión · procesos con reintento automático.
Resolución. El comportamiento depende de tres campos del primer nivel. Con fecha_emision, serie y folio vacíos, cada llamada produce un comprobante nuevo porque la plataforma no tiene con qué reconocer el reenvío. Con esos valores iguales a los del envío anterior, avisa que el CFDI ya existe. Si tu proceso reintenta solo, envía serie y folio propios, o verifica antes con la transacción de búsqueda por número interno.
Causa. Dejar que MYSuite asigne la serie y el folio es cómodo, pero desactiva el reconocimiento de duplicados.
Problema. Tras perder una respuesta, no hay forma de saber si el comprobante se emitió.
Entorno. Emisión · recuperación ante cortes de conexión.
Resolución. numero_interno es opcional pero es el único dato tuyo que viaja con el comprobante y permite localizarlo después. Incorpóralo siempre, y hazlo único por comprobante. Si emites con la variante básica, que no devuelve archivos, omitirlo equivale a quedarte sin ninguna red de seguridad.
Causa. La capacidad de recuperarse de un corte se decide al implementar la emisión, no al implementar la recuperación.
Problema. El CFDI se genera pero le faltan datos que la versión 4.0 exige.
Entorno. Migraciones desde CFDI 3.3.
Resolución. Revisa los campos marcados como [4.0] en la tabla del apartado 6. Los que más se olvidan son el régimen fiscal y el domicilio fiscal del receptor, el objeto de impuesto en cada concepto, y la exportación a nivel comprobante. Si facturas a cuenta de terceros, el bloque completo de ese tercero también es nuevo.
Causa. La versión 4.0 exige declarar de forma explícita datos que antes se inferían o no se pedían.
El Anexo 20 es extenso y cambia. Si cada ERP tuviera que construir el CFDI directamente, cada cambio normativo obligaría a tocar todos los sistemas de todos los clientes. El Nativo interpone una capa: tú entregas datos de negocio con una estructura estable y la plataforma absorbe la complejidad fiscal. Cuando el SAT cambia algo, lo habitual es que tu integración ni se entere.
El Nativo nació en XML, que era el formato natural cuando se diseñó y el que encajaba con un servicio SOAP. Cuando aparecieron las modalidades que intercambian JSON, obligar a sus clientes a generar XML para envolverlo después habría sido incómodo, así que el mismo modelo se publicó serializado en JSON.
Lo importante es que la traducción no fue mecánica. Los dos formatos no comparten la forma de primer nivel, ni reparten los datos igual, ni usan los mismos nombres. Por eso tienen artículos separados y por eso migrar entre modalidades obliga a reescribir la capa que genera el documento.
No hay una explicación documentada, pero el patrón es revelador: el primer nivel está en español con guión bajo, el bloque de conceptos en inglés con mayúscula inicial, y el de impuestos en minúsculas compactas. Parecen capas escritas en momentos distintos o por manos distintas, y conservadas después por compatibilidad.
Sea cual sea el origen, la consecuencia práctica es la misma: el nombre de un campo no se puede deducir, hay que consultarlo. Un generador escrito suponiendo que todo el archivo sigue la convención del primer nivel produce un documento que se envía, se procesa y sale con los conceptos vacíos, que es la peor forma de fallar: sin error visible.
El XML Nativo lleva su versión dentro, con valor fijo, de modo que un archivo suelto se identifica solo. El JSON no. Su versión la determina el nombre de la transacción con la que se envía, lo que funciona mientras el archivo esté en tránsito pero no cuando se archiva o se adjunta a un ticket.
Es el tipo de detalle que no estorba al integrar y sí al diagnosticar: un archivo recibido por correo, sin contexto, no permite saber contra qué versión validarlo.
Quien integra por XML tiene un esquema de validación con los catálogos del SAT embebidos: detecta localmente los errores de estructura, de clave y de longitud, sin consumir folios y sin depender de la red. Quien integra por JSON no tiene ese equivalente, y descubre los mismos errores con un rechazo del servicio.
Visto desde el coste de implementación, esa diferencia pesa más que todas las de sintaxis juntas: no cambia lo que hay que escribir, cambia cuántas vueltas hacen falta para que funcione.
fecha_emision, serie y folio parecen campos de conveniencia —si los dejas vacíos, la plataforma los asigna— y en realidad son el interruptor de la protección antiduplicado. Vacíos, cada llamada es un comprobante nuevo; con valores propios, la plataforma reconoce el reenvío.
Conviene decidirlo de forma consciente al diseñar la integración y no por omisión, porque la diferencia solo se manifiesta el día del primer reintento automático, y para entonces ya hay dos comprobantes con efectos fiscales.
Mirando juntos los campos nuevos, el patrón es claro: la autoridad pidió más identificación fiscal de quien recibe —régimen y domicilio fiscal del receptor, y los mismos datos del tercero cuando se factura a su cuenta— y obligó a declarar explícitamente lo que antes se infería, como si cada concepto es objeto de impuesto o si el comprobante ampara una exportación.
Para el integrador eso significa que la migración a 4.0 no es solo añadir campos: es conseguir datos que quizá su ERP no almacenaba, empezando por el régimen fiscal y el código postal de cada cliente. Suele ser la parte más lenta del proyecto, y no tiene que ver con el formato.