JSON Nativo de MYSuite v8

JSON Nativo de MYSuite v8

Estado: Vigente · Versión del formato: 8 · Archivo de referencia: NativoJSONFull40.json · Compatibilidad: CFDI 4.0 · Última revisión: 14/10/2026 · Próxima revisión: 14/01/2027 · Responsable: Jan Martínez


De un vistazo


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.


El archivo conviene leerlo con cuidado: usa tres convenciones de nombres distintas. El primer nivel y los bloques de emisor, receptor y totales van en minúsculas con guión bajo y en español (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.
Hay un formato hermano en XML. Las modalidades SOAP y API REST por 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.


Cómo saber si este es tu artículo

Si tu integración…Tu artículo es...
Envía el Nativo en JSON, por API REST con JsonServiceCall o por EndPointEste artículo
Envía el Nativo en XML, por SOAP o por API REST con RequestTransactionXML Nativo de MYSuite v8
Quiere saber qué transacción usar para emitirCONVERT_NATIVE_XML4, _SN4 o _BASIC4, en la modalidad que corresponda
Emite constancias de retencionesFIRMAR_RETENCION. Ese flujo no usa el Nativo: recibe el comprobante fiscal ya armado


Requisitos previos

  • El archivo de referencia NativoJSONFull40.json y la descripción de campos Descripcion_JSON_para_CFDI_4.0.xlsx.
  • Los catálogos del SAT que el formato referencia: régimen fiscal, uso de CFDI, clave de producto o servicio, clave de unidad, forma y método de pago, entre otros.
  • Un serializador JSON de tu lenguaje. Construir el documento concatenando cadenas es la causa más frecuente de errores de escape.


Cómo hacerlo

  1. Parte de uno de los cinco ejemplos adjuntos, no del archivo completo de referencia. El de ingreso simple es el camino más corto para una primera emisión.
    Resultado: una base que ya valida.
  2. Completa los bloques obligatorios: emisor, receptor, conceptos y totales, más los campos de primer nivel que identifican el comprobante.
    Resultado: el mínimo que la plataforma necesita.
  3. Escribe numero_interno con el identificador de tu sistema. Es opcional, pero sin él pierdes la verificación antiduplicado.
    Resultado: el comprobante queda localizable desde tu ERP si se pierde una respuesta.
  4. Respeta la convención de nombres de cada bloque. Dentro de conceptos los campos no se escriben como en el primer nivel.
    Resultado: un documento que la plataforma puede interpretar.
  5. Añade lo que necesites: informacion_global para factura global, cfdi_relacionados, complementos o addendas.
    Resultado: el comprobante completo conforme a tu operación.
  6. Serializa con la librería JSON de tu lenguaje y comprueba que no quede BOM al inicio del documento.
    Resultado: un JSON estricto, sin caracteres invisibles al principio.
  7. Codifica o escapa según la modalidad: en API REST el jsonData va en Base64; en EndPoint va crudo dentro del XML y hay que escapar &, < y >.
    Resultado: el documento listo para el transporte que uses.
  8. Envía con la transacción de emisión de tu modalidad.
    Resultado: comprobante timbrado.

Si algo falla, ve a Solución de problemas.


El formato

1. Identidad del formato

NombreJSON Nativo de MYSuite
Versión8. Ver la advertencia del apartado 2
Archivo de referenciaNativoJSONFull40.json
Descripción de camposDescripcion_JSON_para_CFDI_4.0.xlsx
CompatibilidadCFDI 4.0
Claves de primer nivel22
Formato hermanoXML Nativo de MYSuite v8, no equivalente campo por campo


2. El formato no declara su versión

A diferencia del XML Nativo, que lleva un elemento 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.


3. Estructura de primer nivel

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.

ClaveTipoQué contiene
origentextoCanal de origen de la solicitud
doctypetextoTipo de documento a emitir
numero_internotextoIdentificador de tu sistema. Base de la verificación antiduplicado
usuariotextoUsuario del ERP que crea el documento
nota_comprobante_cabecera · nota_comprobante_pietextoNotas a nivel comprobante para la representación gráfica
emisorobjeto · 9 clavesRFC, razón social, dirección fiscal, régimen, lugar de expedición, sucursal, correo, cuenta de pago y atributo del adquirente
receptorobjeto · 9 clavesRFC, razón social, dirección fiscal, uso del CFDI, régimen fiscal, domicilio fiscal, datos de extranjero y correo
conceptosarreglo de objetosLos conceptos del comprobante. Ver apartado 4
totalesobjeto · 7 clavesTotal, subtotal, descuento, moneda, factor de cambio e impuestos trasladados y retenidos
fecha_emision · serie · foliotextoAsignación del comprobante. Determinan el comportamiento ante reenvíos
metodo_pago · forma_pago · condiciones_pagotextoCondiciones de pago
confirmaciontextoClave de confirmación cuando el comprobante la requiere
exportaciontexto[4.0] Si la operación ampara una exportación
informacion_globalobjeto · 3 claves[4.0] Periodicidad, meses y año de la factura global
cfdi_relacionadosarreglo de objetosTipo de relación y listado de folios relacionados
complementosobjeto o nuloComplementos fiscales del SAT
addendasobjeto o nuloAddendas de cliente
Compara con el XML Nativo: allí son 14 nodos y la mayor parte de estos campos vive dentro de fx:Identificacion. Aquí están en el primer nivel. Y addendas es clave propia, mientras que en XML su equivalente es fx:ComprobanteEx.


4. Las tres convenciones de nombres

Este es el punto que más errores produce al escribir el generador, porque no es visible hasta que se mira el archivo con atención.
DóndeConvenciónEjemplos reales
Primer nivel, emisor, receptor, totalesminúsculas con guión bajo, en españolnumero_interno · fecha_emision · razon_social · codigo_postal · regimen_fiscal
Dentro de conceptosmayúscula inicial, en inglésDescription · ListPrice · Qty · Amount · Unit · Partes · ObjetoImp
Dentro de Taxesminúsculas sin separadorimpuesto · 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.


Estructura de un concepto

ClaveContenido
ClaveProdServ · ClaveUnidad · UnitClaves de catálogo del SAT y unidad de medida
Description · Descripcion_AmpliadaDescripción del concepto y su versión extendida
Qty · ListPrice · Amount · DiscountCantidad, valor unitario, importe y descuento
ObjetoImp[4.0] Si la operación es objeto de impuesto
TaxesArreglo de impuestos del concepto: type, impuesto, tipofactor, tasacuota, taxbase, amount
PartesArreglo de partes o componentes del concepto
ACuentaTerceros[4.0] Objeto con RFC, RegimenFiscal, Nombre y DomicilioFiscal
InfoAduanera · CuentaPredialInformación aduanera y cuenta predial
complementos · addendasA nivel de concepto


5. Campos del formato

Descripción campo por campo. Los marcados con [4.0] son los que introdujo la versión 4.0 del CFDI.

CampoDescripción
OrigenEstipule 1001 desde WS o 1002 desde Agente
doctypeTipo 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_internoEstipule un numero interno con la finalidad de evitar duplicidad (se recomienda la concatenación de la serie y folio del documento)
usuarioEspecifique el usuario que esta creando el documento (se recomienda se estipule desde donde se enta enviando el archivo, ejemplo: "SAP-Agente")
nota_comprobante_cabeceraIncluya notas de Cabecera a nivel comprobante (general)
nota_comprobante_pieIncluya notas de Pie a nivel comprobante (general)
emisorObjeto: Emisor
rfcRFC del emisor del documento (solo para pruebas utilice siempre JES900109Q90)
razon_socialEspecifique el nombre de su empresa o negocio
direccion_fiscalObjeto: Dirección del Emisor
calleEspecifique la calle del emisor
num_exteriorEspecifique numero exterior del emisor
num_interiorEspecifique numero interior del emisor
coloniaEspecifique colonia del emisor
municipioEspecifique municipio del emisor
estadoEspecifique estado del emisor
paisEspecifique pais del emisor
codigo_postalEspecifique codigo postal del emisor
localidadEspecifique localidad del emisor
referenciaEspecifique referencia del emisor
regimen_fiscalIndique el regimen fiscal del emisor "catalogo SAT"
lugar_expedicionIndique el codigo postal del lugar de expedición.
sucursalIndique la sucursal del emisor (en caso de tener varias), si no existen sucursales especifique FISCALDOM
correoindique el correo del emisor (le llegará una copia del CFDI generado)
cuenta_pagoIndiqué 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.
receptorObjeto: Receptor
correoEspecifique el correo del receptor, le llegará una copia del CFDI
rfcRFC 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_socialEspecifique el nombre de su cliente, empresa o negocio a quien se le realizó la venta
rfc_extranjeroUtilice este campo para especificar el TAXID del cliente, esto en caso de que haya especificado XEXX010101000 en el nodo RFC)
residencia_fiscalEn caso de haber utilizado XEXX010101000 en el RFC deberá especificar la residencia fiscal (conforme catalogo SAT)
direccion_fiscalObjeto: Dirección del Receptor
calleEspecifique la calle del receptor
num_exteriorEspecifique numero exterior del receptor
num_interiorEspecifique numero interior del receptor
coloniaEspecifique colonia del receptor
municipioEspecifique municipio del receptor
estadoEspecifique estado del receptor
paisEspecifique pais del receptor
codigo_postalEspecifique codigo postal del receptor
localidadEspecifique localidad del receptor
referenciaEspecifique referencia del receptor
uso_cfdiEspecifique 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.
conceptosObjeto: Conceptos
UUIDEspecifique siempre: "00000000-0000-0000-0000-000000000000"
IDEspecifique siempre: "0"
DescriptionEspecifique la descripción de su producto, bien o servicio el que esta facturando o haciendo referencia
ListPricePrecio unitario del concepto, bien o servicio que se esta facturando
DiscountEspecifique el descuento del producto en caso de haber
UnitEspecifique la unidad de medida (propia del emisor)
ClaveProdServEspecifique la clave de producto o servicio (según catalogo SAT)
ClaveUnidadEspecifique la clave de unidad (según catalogo SAT)
InfoAduaneraSi existe, Especifique información de aduana, conforme estructura solicitada por el SAT
CuentaPredialEspecifique la cuenta predial, en caso de existir más de una, separarlas con una coma, ejemplo: "CuentaPredial":"122332, 454555, 8775434, 8805984"
TaxesObjeto: Impuesto de Linea
typeEspecifique el tipo de movimiento del impuesto (TRASLADO/RETENCION)
impuestoEspecifique el tipo de impuesto (IVA, IEPS o ISR, conforme al catalogo SAT)
tipofactorEspecifique el tipo de factor (TASA o CUOTA) conforme al catalogo SAT)
tasacuotaEspecifique el valor conforme el catalogo SAT
taxbaseEspecifique la base del impuesto unicamente de la linea "concepto" (Precio Unitario X Cantidad = SubtotalBaseImpto - Descuento = TotalBaseImpto)
amountEspecifique 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)
QtyEspecifique la cantidad del producto, bien o servicio que esta incluyendo en su concepto
AmountEspecifique el importe del calculo realizado de Precio Unitario X Cantidad
IdentificacionEspecifique la identificación de su producto, bien o servicio (catalogo interno)
PartesObjeto: 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_AmpliadaEspecifique la descripción ampliada de su producto, bien o servicio el que esta facturando o haciendo referencia
addendasEspecificar adenda a procesar (solicite la estructura correcta para la adenda requerida), esta información será integrada en base64
complementosEspecificar complemento a procesar (solicite la estructura correcta para la complemento requerido), esta información será integrada en base64
IdentificacionEspecifique la identificación de la parte del producto, bien o servicio (catalogo interno)
QtyEspecifique la cantidad de la parte del producto, bien o servicio que esta incluyendo en su concepto
DescriptionEspecifique la descripción de la parte del producto, bien o servicio el que esta facturando o haciendo referencia
UnitPricePrecio unitario de la parte del concepto, bien o servicio que se esta facturando
totalesObjeto: Totales
totalEspecifique el total del comprobante (todos los conceptos con sus respectivos descuentos e impuestos)
subtotalEspecifique el subtotal del comprobante (todos los conceptos sin sus respectivos descuentos e impuestos)
descuentoEspecifique el total de los descuentos del comprobante (los descuentos de todos los conceptos)
monedaEspecifique la moneda del documento y su cantidad de decimales (conforme catalogo del SAT)
factor_cambioEspecifique el tipo de cambio en caso de utilizar una moneda diferente a MXN
impuestos_trasladadosEspecifique la suma de todos los impuestos trasladados de todos los conceptos
impuestos_retenidosEspecifique la suma de todos los impuestos retenidos de todos los conceptos
fecha_emisionEspecifique fecha de emisión en caso de quererla controlar, si se omite, toma la fecha y hora actual
serieEspecifique la serie del documento en caso de quererla controlar, si se omite toma la que tengan configurada en su cuenta
folioEspecifique el folio del documento en caso de quererlo controlar, si se omite toma la que tengan configurada en su cuenta
metodo_pagoEspecifique el metodo de pago (conforme catalogo del SAT)
forma_pagoEspecifique el forma de pago (conforme catalogo del SAT)
confirmacionSu uso solo es para comprobantes con millones de pesos y debe haber un folio de confirmación por parte del PAC
condiciones_pagoEspecifique 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.


6. Qué cambió con CFDI 4.0

Si vienes de una integración anterior, estos son los campos nuevos o modificados que tienes que atender.

CampoDescripció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.
El patrón de los cambios es reconocible: la versión 4.0 exige más datos de identificación fiscal de quien recibe —régimen y domicilio fiscal del receptor y del tercero— y obliga a declarar de forma explícita cosas que antes se inferían, como si la operación es objeto de impuesto o si ampara una exportación.


7. Codificación del archivo

AspectoQué hacer
Marca de orden de bytesNo la incluyas. El archivo de referencia la trae y varios analizadores la rechazan
CodificaciónUTF-8
SerializaciónCon la librería JSON de tu lenguaje, no concatenando cadenas
Transporte en API RESTBase64
Transporte en EndPointCrudo dentro del XML, con &, < y > escapados


8. Ejemplos disponibles

ArchivoEscenario
Nativo_Ingreso_Simple_v_8.jsonComprobante de ingreso ordinario. El punto de partida recomendado
Nativo_Ingreso_Global_v_8.jsonFactura global, con informacion_global
Nativo_Egreso_CFDIRelacionado_v_8.jsonEgreso con un comprobante relacionado
Nativo_Egreso_Dos_CFDIRelacionados_v_8.jsonEgreso con dos comprobantes relacionados
Nativo_Ingreso_A_Cuenta_Terceros_v_8.jsonIngreso a cuenta de terceros, con el bloque ACuentaTerceros
Empieza por un ejemplo, no por el archivo completo. 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.


9. Validación antes de enviar

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 cuentaQué 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 presentesClaves de catálogo del SAT · longitudes máximas · coherencia aritmética · reglas de negocio de la plataforma


10. Versionado y cumplimiento

  • La versión 8 del formato aplica únicamente a CFDI 4.0.
  • El JSON Nativo no es un comprobante fiscal: es el insumo con el que MYSuite lo construye. No tiene sello, ni timbre, ni valor probatorio.
  • Los catálogos que el formato referencia los publica el SAT. La plataforma incorpora sus actualizaciones.
  • El formato no declara su versión internamente: la determina la transacción con la que se envía.

Solución de problemas

"El servicio rechaza mi JSON y el analizador dice que es válido"


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.

"Los campos de conceptos me llegan vacíos"


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.

"Convertí mi XML Nativo a JSON y no funciona"


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.

"Envié el archivo de referencia y no emitió"


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.

"No tengo forma de validar antes de enviar"


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.

Causa. No existe un esquema de validación.

"Reenvié el mismo documento y se duplicó el comprobante"


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.

"No envié número interno y ahora no puedo verificar una emisión"


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.

"Mi comprobante 4.0 sale incompleto"


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.


Para entender más

Qué problema resuelve el Nativo

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.

Por qué existe una versión en JSON

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.

De dónde vienen las tres convenciones de nombres

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.

Un formato que no dice qué versión es

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.

La asimetría que más cuesta

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.

Tres campos que deciden si un reenvío duplica

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.

Qué cambió de fondo con la versión 4.0

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.