DESCRIPCIÓN DE LOS SERVICIOS DE INTEGRACIÓN COMPATIBLES CON NETSUITE

DESCRIPCIÓN DE LOS SERVICIOS DE INTEGRACIÓN COMPATIBLES CON NETSUITE

Servicios de Integración de MYSuite compatibles con NetSuite


Guía para consultores, desarrolladores e integradores NetSuite que necesitan conectar una cuenta NetSuite con MYSuite (PAC autorizado por el SAT, autorización 55270), para la certificación de CFDI.


CFDI + Timbrado (SOAP)

Modalidad madura e integrada nativamente por NetSuite ("México PAC"). Consume el web service SOAP FactWSFront con la operación RequestTransaction, de forma síncrona. El XML nativo de MYSuite se envía en el elemento Data1 codificado en Base64 con la transacción CONVERT_NATIVE_XML.
Conoce a detalle el servicio y sus transacciones.

Qué ofrece

Es la modalidad de integración de mayor cobertura funcional y la base histórica del esquema de MYSuite. Está pensada para empresas que operan un ERP como NetSuite y requieren interacción sistema a sistema para el ciclo completo del comprobante: generación, sellado con el CSD del emisor, certificación, entrega del CFDI y la representación gráfica (PDF), distribución por correo al receptor, consulta, validación, recepción y cancelación.

El cliente no construye el CFDI conforme al Anexo 20; construye un XML Nativo de MYSuite —un formato propio, más simple y estable que el Anexo 20— y MYSuite se encarga de convertirlo en CFDI, firmarlo y certificarlo. Este desacoplamiento es la ventaja estructural del servicio: los cambios de versión que publica el SAT (CFDI 4.0, Retenciones 2.0, Pagos 2.0, Carta Porte 3.1, etc.) se absorben en la plataforma y no obligan a reescribir el generador del ERP. La modalidad admite además la totalidad de complementos fiscales vigentes y el catálogo de addendas comerciales de MYSuite.


Cómo se conecta

La capa de servicio es un Web Service SOAP que responde de forma síncrona: se recibe una transacción, MYSuite ejecuta la acción y devuelve la respuesta en la misma llamada.


Contrato técnico

Todas las transacciones de esta modalidad se invocan a través de una única operación, RequestTransaction, con el mismo sobre. El nombre de la transacción viaja como cadena en el nodo <Transaction> y las cargas útiles en <Data1>, <Data2> y <Data3>.


Elementos de la solicitud:
  • Requestor: GUID que proporciona MYSuite. Vinculado a la seguridad, autenticación y autorización de la transacción.
  • Transaction: nombre del método a invocar (por ejemplo CONVERT_NATIVE_XML).
  • Country: abreviatura del país; su valor siempre es "MX".
  • Entity: RFC de quien realiza la solicitud. En pruebas, JES900109Q90.
  • User: se repite el valor del Requestor.
  • UserName: identifica al usuario del ERP NetSuite que originó la solicitud, con el formato País.Entity.Usuario_NetSuite (por ejemplo MX.JES900109Q90.Jacinto). Esto permite trazabilidad por emisor, sucursal, departamento o empleado.
  • Data1, Data2, Data3: se llenan según la transacción invocada.

Interpretación de la respuesta:


Lo primero que debe evaluarse es el nodo <Result> dentro de <Response>.
Con true, la transacción se completó y deben recogerse los datos devueltos.
Con false, deben mostrarse al operador los nodos <Description>, <Hint> y <Data>, que contienen la información necesaria para corregir el problema.

Límites y consideraciones operativas

  • Si el contenido de Data1 excede 1 MB, MYSuite responde false: ese comprobante debe procesarse por el Servicio Grandes Asíncrono.
  • La práctica recomendada de integración es tomar los metadatos en el ERP, tales como la Serie, el Folio, el Folio Fiscal (UUID), el timestamp y almacenar localmente el PDF para no volver a solicitarlo.
  • El emisor debe conservar el CFDI (XML certificado).
  • LOOKUP_ISSUED_INTERNAL_ID es el mecanismo estándar de control de no duplicidad: consulta cuántos comprobantes existen en MYSuite con el número interno del ERP. Debe implementarse como paso previo o de reconciliación ante reintentos y pérdidas de respuesta.


Consideraciones para NetSuite

Es la modalidad con integración nativa en NetSuite a través de la configuración de PAC para México, en la que se registran el ID Fiscal (RFC), la URL del Web Service y el Requestor como Nombre de Usuario:



Para escenarios que van más allá de la certificación estándar —consulta, validación, recepción, retenciones, cancelación— el desarrollo se realiza con SuiteScript, construyendo el sobre SOAP y procesando la respuesta.

Transacciones del servicio CFDI + Timbrado (SOAP)

Emisión

Consulta y Recuperación

Validación y Recepción

CFDI de Retenciones

Esquema de cancelación

 

CFDI + Timbrado (SOAP) — Servicio Grandes Asíncrono

Servidor dedicado y modelo asíncrono para procesar archivos XML Nativos de MYSuite grandes (Data1 > 1 MB, hasta 70 MB en producción).

Flujo de tres pasos: ASYNC_CONVERT_NATIVE_XML, ASYNC_CONVERT_VERIFY y ASYNC_RETRIEVE_DOCUMENT.

Los enlaces para descarga de XML/PDF tienen vigencia de 5 días.
Conoce a detalle el servicio y sus transacciones.

Qué ofrece

Es un servicio dedicado a la emisión/certificación de comprobantes de gran tamaño, operado bajo un modelo asíncrono de cinco etapas: solicitud, encolamiento, procesamiento, consulta de resultado y obtención de enlaces de descarga de archivos del cfdi (xml y pdf). No sustituye al servicio síncrono, lo complementa: cada servicio atiende un rango de tamaño distinto y ambos rechazan el tráfico que corresponde al otro.

Su valor para una integración NetSuite es doble.

Primero, habilita comprobantes que el servicio síncrono no puede procesar —CFDI con miles de conceptos, complementos voluminosos, Carta Porte extensa—.
Segundo, desacopla el tiempo de respuesta del proceso de negocio: el ERP encola y libera el hilo, en lugar de sostener una conexión abierta mientras la plataforma genera el documento.

Adicionalmente, se permite la distribución por correo de los comprobantes generados mediante solicitudes asíncronas.


Cómo se conecta

Se mantiene el mismo sobre RequestTransaction y el mismo juego de credenciales que en la modalidad síncrona, pero sobre hosts propios:


Contrato técnico y flujo

El ciclo se compone de tres transacciones que deben implementarse en secuencia:

      1. ASYNC_CONVERT_NATIVE_XML 

Encola la solicitud de generación. En Data1 va el XML Nativo de MYSuite en Base64. En Data2 va, en texto plano, un identificador único de la transacción del lado del cliente (Id, GUID o cualquier valor único en su ERP); es obligatorio, con máximo de 50 caracteres, y es el mecanismo que impide información repetida en MYSuite. Con Result igual a true, la respuesta llega en ResponseData1 como una cadena en formato GUID: el identificador de la solicitud, indispensable para toda operación posterior.
      
      2. ASYNC_CONVERT_VERIFY

Consulta el estado de la solicitud. En Data1 se envía el identificador obtenido en el paso anterior. La respuesta llega simultáneamente en ResponseData1 (XML) y ResponseData2 (JSON), ambos en Base64 y con el mismo contenido, para que el integrador use el formato que le resulte más cómodo. Campos devueltos: Entity, Uuid, InternalID, EnrolledTimeStamp, Status, DocumentGUID, Year, Batch, Serial y ErrorMsg. El Status admite tres valores: 1 pendiente de procesar, 2 procesado con éxito, 3 procesado con error. Los campos DocumentGUID, Year, Batch y Serial sólo tienen valor cuando Status = 2; ErrorMsg sólo cuando Status = 3, devuelto en Base64. Con Status = 3 se entrega además un log en ResponseData3, en Base64, con el motivo por el que no pudo emitirse.

      3. ASYNC_RETRIEVE_DOCUMENT

Recupera el documento generado. EnData1 se envía el identificador de la solicitud. La respuesta es equivalente a la de RETRIEVE_DOCUMENT con dos diferencias sustantivas: siempre devuelve XML y PDF (no hay parámetro de selección), y lo que llega en ResponseData1 y ResponseData3 no es el contenido del archivo sino el enlace al archivo en la nube, igualmente codificado en Base64.

Límites y consideraciones operativas

  • Productivo: procesa en Data1 información superior a 1 MB, con límite máximo de 70 MB. El tiempo de generación del CFDI depende de la carga de solicitudes asíncronas que se tengan encoladas en este servicio y del tamaño del xml nativo enviado.
  • Pruebas: el tamaño está limitado; sólo se permite procesar Data1 con tamaño mayor a 1 MB y hasta 2 MB. Este punto debe considerarse al planear las pruebas, porque no permite validar los tamaños reales de producción.
  • En ambos ambientes, si Data1 es menor a 1 MB, el servicio responde false: ese archivo debe ir por el servicio síncrono.
  • Vigencia de los enlaces: 5 días. Los enlaces entregados no se guardan en la plataforma; cada llamada a ASYNC_RETRIEVE_DOCUMENT genera enlaces nuevos con vigencia de 5 días.
  • Control de duplicidad: si se envía una solicitud con un número interno ya registrado en MYSuite —escenario típico cuando el ERP no recibió respuesta y reintenta—, la transacción falla con código 3196 y Result igual a false, indicando en <Data> que el número interno ya existe. Aun así, ResponseData1 devuelve el identificador de la solicitud existente, como si se hubiera registrado en ese momento. Esto permite implementar reintentos idempotentes sin generar comprobantes duplicados: ante un 3196, el ERP debe tomar el identificador devuelto y continuar el flujo con ASYNC_CONVERT_VERIFY.


Consideraciones para NetSuite

El patrón natural en NetSuite es separar el ciclo en dos ejecuciones: un script que encola (disparado por evento de usuario o por proceso programado) y un script programado o Map/Reduce que verifica el estado y recupera los documentos. Dado que ASYNC_RETRIEVE_DOCUMENT devuelve enlaces y no contenido, la descarga debe realizarse en un paso adicional y el archivo persistirse en el File Cabinet antes de que expire la vigencia de 5 días. El identificador de solicitud (GUID) y el número interno enviado en Data2 deben almacenarse en campos personalizados del registro de transacción de NetSuite: son la única llave de correlación entre el ERP y la cola de MYSuite.


Transacciones del servicio Grandes Asíncrono



CFDI + Timbrado (API REST)

Procesa XML o JSON nativo de MYSuite sobre REST. Recomendado cuando el equipo NetSuite prefiere REST ya sea con JsonServiceCall o RequestTransaction.

Conoce a detalle el servicio y sus transacciones.

Qué ofrece

Ofrece la misma cobertura funcional que CFDI + Timbrado (SOAP) —emisión, validación, certificación, consulta, recepción, retenciones y cancelación 2022 sobre CFDI v4.0 y todos los complementos fiscales vigentes— pero sobre un transporte API REST. Está dirigida a equipos que prefieren consumir servicios HTTP con cargas JSON y evitar la construcción de sobres SOAP.

Su particularidad de diseño es que expone dos recursos alternativos con semánticas distintas, y la elección entre ellos condiciona el desarrollo completo:

  • RequestTransaction — replica el contrato de la modalidad SOAP en formato JSON: el cuerpo de la petición lleva los mismos campos (Requestor, Transaction, Country, Entity, User, UserName, Data1, Data2, Data3) y se autentica con el Requestor en cada llamada, sin token. Es la vía de menor esfuerzo para migrar una integración SOAP existente a REST, porque la lógica de armado de Data1/Data2 se conserva íntegra.
  • JsonServiceCall — contrato propiamente orientado a JSON. El cuerpo lleva tres campos: jsonData (la carga útil, en Base64), transactionName (el nombre de la transacción) y token (credencial de sesión). Requiere autenticación previa por token.


Cómo se conecta

Los recursos se invocan por ruta, por ejemplo https://api.mysuitetest.com/RequestTransaction, https://api.mysuitetest.com/JsonServiceCall

La documentación de recursos está disponible en el Swagger del ambiente de pruebas: https://api.mysuitetest.com/swagger/ui/index#/.

Info
Al abrirlo debe reemplazarse el valor del campo de especificación por https://api.mysuitetest.com/swagger/docs/v1 (con esquema HTTPS) para que cargue correctamente.


Contrato técnico

El documento de entrada sigue siendo el XML Nativo de MYSuite versión 8 (fx_2010_g.xsd) o su equivalente en JSON nativo, y la transacción de emisión sigue siendo CONVERT_NATIVE_XML, MYSuite lo convierte en CFDI, lo firma con el CSD del emisor y lo timbra/certifica.

Autenticación por token (ruta JsonServiceCall). Antes de cualquier solicitud debe obtenerse un token mediante AUTHENTICATE, enviando taxID (RFC del emisor), user y pass (usuario y contraseña proporcionados por MYSuite para ese RFC). La respuesta devuelve result, payload, token, errorMsg y errorCode.

Tres reglas de implementación son críticas:
  • El token tiene tiempo de expiración (10 minutos).
  • El token es rotativo: en cada transacción ejecutada debe recuperarse el token devuelto en la respuesta, porque la siguiente llamada —de cualquier transacción— debe usar el último token devuelto.
Warning
Un diseño que reutilice indefinidamente el token inicial fallará.
  • Códigos de control: errorCode 101 indica que la vida del token expiró y debe volverse a autenticar; errorCode 102 indica token inválido (falla al desencriptar y parsear la información de autenticación de la llamada).


Consideraciones para NetSuite

Es la modalidad más directa de consumir desde SuiteScript, porque se resuelve con peticiones HTTP y manejo de objetos JSON, sin necesidad de construir y parsear XML de sobre.

Si el proyecto migra desde una integración SOAP previa, la ruta RequestTransaction minimiza el cambio.

Si el desarrollo es nuevo y se opta por JsonServiceCall, debe diseñarse desde el inicio la gestión de estado del token: al ser rotativo y con expiración, un script Map/Reduce con múltiples ejecuciones concurrentes debe centralizar la custodia del token o autenticarse por ejecución, para evitar invalidaciones cruzadas.


Transacciones del servicio CFDI + Timbrado (API REST)


Vía RequestTransaction


      Emisión
      Consulta y Recuperación
      Validación y Recepción
      CFDI de Retenciones


Vía JsonServiceCall

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

EndPoint

Emisión de CFDI a partir de JSON nativo, invocada mediante JsonServiceCall y con método AUTHENTICATE.

Conoce a detalle el servicio y sus transacciones.

Qué ofrece

Es la modalidad que emite/certifica un CFDI (conforme al Anexo 20 vigente), a partir de un archivo JSON nativo de MYSuite. Está dirigida a equipos cuyo flujo de datos es JSON de extremo a extremo y que prefieren no generar ni manipular XML en el ERP.

Su diferencia arquitectónica frente a API REST es importante y suele ser fuente de confusión. 

WarningEndPoint no es un servicio REST.

Se consume sobre el mismo Web Service SOAP FactWSFront, pero a través de dos operaciones distintas de las usadas por CFDI + Timbrado: Authenticate y JSONServiceCall.

Es decir, transporta JSON dentro de un sobre SOAP.

Esto permite reutilizar la infraestructura y las reglas de red ya autorizadas para el Web Service de MYSuite, mientras el equipo de desarrollo trabaja con estructuras JSON.

El servicio contempla la construcción del JSON tanto para CFDI simples como para casos con complementos fiscales y con addendas comerciales, que se identifican a nivel de la estructura principal del archivo JSON.


Cómo se conecta


Contrato técnico


Autenticación.

Antes de cualquier solicitud debe obtenerse un token de seguridad invocando la operación Authenticate con taxID (RFC del emisor), user y pass.
La respuesta viaja dentro del nodo <AuthenticateResult> como un objeto JSON con los campos Result, Payload, ErrorMsg, ErrorCode y Token.
Aplican las mismas reglas que en API REST: el token expira, es rotativo —debe recuperarse el token devuelto en cada transacción y usarse el último en la llamada siguiente—, y los códigos 101 (token expirado) y 102 (token inválido) indican la necesidad de reautenticar.

Invocación de transacciones.

Se realiza mediante la operación JSONServiceCall, que recibe tres elementos: jsonData (la carga útil en JSON), transactionName (nombre de la transacción) y token.
La respuesta llega en <JsonServiceCallResult> como objeto JSON con Result, Payload, ErrorMsg, ErrorCode y Token; el resultado de la transacción se entrega en Payload en Base64.

Transacciones de emisión y consulta.

CONVERT_NATIVE_XML4 devuelve, en Base64, el XML y el PDF del CFDI generado a partir del JSON enviado.
CONVERT_NATIVE_XML_BASIC4 devuelve únicamente los metadatos del comprobante generado, sin los archivos: es la opción indicada cuando el ERP no necesita el XML ni el PDF en la misma llamada, y reduce de forma significativa el volumen de la respuesta.
CONVERT_NATIVE_XML_SN4 devuelve, en Base64, XML del CFDI sin NATIVO de MYSuite y PDF del CFDI.
LOOKUP_ISSUED_INTERNAL_ID está destinada al control de la no duplicidad: uno de sus parámetros es el número interno que corresponde a un único identificador de transacción, llamada, operación o registro en el ERP del cliente.
RETRIEVE_DOCUMENT permite obtener el XML y el PDF de un CFDI ya emitido en cualquier momento posterior. 


Consideraciones para NetSuite

El desarrollo combina dos habilidades: armado de sobre SOAP y manejo de JSON. En SuiteScript esto se traduce en construir el envelope, insertar el JSON como contenido de texto —con el escape correcto de caracteres— y parsear la respuesta en dos niveles: primero el XML del sobre para extraer JsonServiceCallResult, y después el JSON contenido en ese nodo. Debe tenerse presente que la codificación de jsonData no es uniforme entre transacciones ni entre modalidades: en la cancelación por EndPoint se documenta el JSON en texto plano, mientras que la carga equivalente por API REST se documenta en Base64, y dentro de EndPoint el campo XmlSel de la consulta sí va en Base64.


Transacciones del servicio EndPoint


Vía JSONServiceCall

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

Tabla comparativa


Servicio
Protocolo
Documento de entrada
Autenticación
Modelo
Tamaño de Data1
CFDI + Timbrado (SOAP)SOAP / XMLXML Nativo MYSuite v8Requestor (GUID) en cada llamadaSíncronoHasta 1 MB
CFDI + Timbrado (SOAP) — Grandes AsíncronoSOAP / XMLXML Nativo MYSuite v8Requestor (GUID) en cada llamadaAsíncrono (encolado + consulta)> 1 MB y hasta 70 MB (productivo)
CFDI + Timbrado (API REST)REST / JSONXML Nativo MYSuite v8 o JSON Nativo MYSuiteRequestor (GUID) o token con expiraciónSíncronoHasta 1 MB
EndPoint

SOAP / JSON
JSON Nativo MYSuiteToken con expiración (rotativo)SíncronoHasta 1 MB



Todas comparten un mismo modelo conceptual — el ERP construye un documento nativo de MYSuite, lo envía bajo una transacción nombrada y este recibe el CFDI certificado (más su representación gráfica PDF) — pero difieren en protocolo, formato del documento, mecanismo de autenticación, modelo de ejecución y límites de tamaño.

Idea
Elegir la modalidad correcta al inicio del proyecto evita retrabajo de integración.



Criterio de selección

La decisión debe tomarse sobre cuatro variables: tamaño del comprobante, formato de trabajo del equipo, existencia de una integración previa y perfil del proyecto.

  • Implementación estándar de NetSuite con timbrado en línea, documento a documento → CFDI + Timbrado (SOAP). Es la modalidad con integración nativa en NetSuite y la de mayor cobertura funcional documentada.
  • Comprobantes cuyo XML nativo puede superar 1 MB → Servicio Grandes Asíncrono, orquestado desde scripts programados o Map/Reduce. Considerar que el ambiente de pruebas está limitado a 2 MB y que los enlaces de descarga expiran en 5 días.
  • Operación mixta → ambas modalidades SOAP en paralelo, con enrutamiento por tamaño. Es el escenario más frecuente en operaciones de alto volumen: el ERP evalúa el tamaño de Data1 y decide el destino, dado que cada servicio rechaza el tráfico del otro.
  • Equipo que prefiere REST/JSON y proyecto nuevo → CFDI + Timbrado (API REST), ruta JsonServiceCall.
  • Migración de una integración SOAP existente hacia REST con el mínimo cambio de código → CFDI + Timbrado (API REST), ruta RequestTransaction: conserva el contrato de campos y la lógica de Data1/Data2.
  • Flujo de datos JSON de extremo a extremo, sin generación de XML en el ERP → EndPoint.

Requisitos de implementación

  • El sistema debe ser capaz de establecer comunicación mediante Web Services (SOAP) o API REST con la plataforma, según la modalidad elegida.
  • Debe implementarse control de no duplicidad. En las modalidades síncronas, mediante LOOKUP_ISSUED_INTERNAL_ID; en Grandes Asíncrono, mediante el número interno obligatorio en Data2.
  • El emisor debe almacenar el CFDI (XML firmado digitalmente). Se recomienda persistir también el PDF localmente y registrar Serie, Folio, Folio Fiscal (UUID) y timestamp en el ERP.
  • Todo el ciclo debe validarse en el ambiente de pruebas con el RFC JES900109Q90 y la Sucursal asignada antes de habilitar producción.
  • Las actualizaciones y cambios de versión que publica el SAT se absorben en la plataforma de MYSuite.