Qué hace: te entrega el token de seguridad que necesitas para conectarte a la capa de servicio y ejecutar solicitudes en el servicio EndPoint. Es la puerta de entrada: sin token no puedes hacer nada más en esta modalidad.
Cuándo se usa: al iniciar la integración, y cada vez que el token caduca.
Cuándo no usarla: si consumes otra modalidad. Cada una tiene su propio modelo de autenticación, y tener acceso a una no implica tenerlo a las demás.
soap:Envelope, pero el contenido de la respuesta no es XML: es una cadena JSON dentro del elemento de resultado. Si tratas la respuesta como un documento XML y buscas elementos, no los vas a encontrar.AUTHENTICATE, que es ésta, y JSONServiceCall, a través del cual se invocan las transacciones. El token que obtienes aquí se usa en JSONServiceCall.| Si tu integración… | Tu artículo es... |
|---|---|
Envía un sobre SOAP a factwsfront.asmx invocando la operación Authenticate, y recibe JSON dentro del sobre |
Este artículo |
| Ya tiene token y va a ejecutar transacción CONVERT_NATIVE_XML4 por EndPoint | CONVERT_NATIVE_XML4 — Servicio EndPoint |
Envía JSON al recurso /Authenticate de API REST |
AUTHENTICATE — CFDI + Timbrado (API REST) - JsonServiceCall |
Envía sobres SOAP al mismo .asmx pero invocando las operaciones clásicas, y recibe XML |
No aplica: esa modalidad no usa token. Ve al artículo de la transacción que vas a ejecutar |
Envía Requestor, User y UserName en cada petición a /RequestTransaction |
No necesitas token. Ve directo al artículo de la transacción que vas a ejecutar |
ws:Authenticate y sus tres elementos hijos: ws:taxID, ws:user y ws:pass.factwsfront.asmx del ambiente que corresponda.AuthenticateResult. No lo recorras como XML: lo que hay dentro es una cadena JSON.Result, Payload, ErrorMsg, ErrorCode y Token.Result y comprueba que ErrorCode sea 0. Aquí el éxito es cero, igual que en API REST por JsonServiceCall.Token en memoria, en una variable que puedas sustituir.JSONServiceCall.ErrorCode con valor 101, que indica token caducado.Si algo falla, ve a Solución de problemas.
| Arquitectura | Híbrida. Sobre SOAP en la petición y en la respuesta; contenido JSON dentro del elemento de resultado |
|---|---|
| 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 | Authenticate, dentro de soap:Body |
| Encabezado SOAP | <soap:Header/> vacío |
| Naturaleza | Autenticación. No consulta ni modifica comprobantes |
| Consumo |
No consume folio del paquete vigente
|
| Contrato formal | El propio .asmx publica los servicios disponibles |
| 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 |
.asmx que atiende la modalidad SOAP clásica. Lo que cambia es qué operación invocas dentro del sobre, no adónde lo envías.| Servicio | Para qué sirve |
|---|---|
AUTHENTICATE |
Obtener el token de seguridad. Es esta transacción |
JSONServiceCall |
Ejecutar las transacciones de negocio, usando el token |
JSONServiceCall, igual que ocurre en API REST. Esta transacción no requiere autenticación previa: es la que la produce. Las tres credenciales viajan como elementos hijos de ws:Authenticate.
| Elemento | Tipo | Obligatorio | Descripción |
|---|---|---|---|
ws:taxID |
string | Sí | RFC del emisor |
ws:user |
string | Sí | Usuario proporcionado en MYSuite para tu RFC, del ambiente de test es JES900109Q90 o el tuyo para ambiente productivo |
ws:pass |
string | Sí | Contraseña del usuario proporcionado en MYSuite para tu RFC o la que hayas definido para tu usuario en ambiente productivo |
Los tres elementos del apartado anterior son el contenido completo de la petición. Esta modalidad no usa campos de datos genéricos como los Data1, Data2 y Data3 de la modalidad SOAP clásica, pese a compartir con ella el mismo servicio.
Un sobre SOAP con la operación Authenticate y sus tres credenciales. No hay estructuras anidadas ni codificación en Base64.
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:Authenticate>
<ws:taxID>[RFC del emisor]</ws:taxID>
<ws:user>[usuario proporcionado por MYSuite]</ws:user>
<ws:pass>[contraseña del usuario]</ws:pass>
</ws:Authenticate>
</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>
<AuthenticateResponse xmlns="http://www.fact.com.mx/schema/ws">
<AuthenticateResult>
{"Result":true,"Payload":null,"ErrorMsg":null,"ErrorCode":0,"Token":"OxbZPD1Gd9hUomWYNBUGWkzja54cEGlnz9LLPKZY+pI0+bfE1ldh8TKjBK02xvy58Y8dtVB1G102KafDOcVTYMNmPr+x6xdeepl5fD09diQ="}
</AuthenticateResult>
</AuthenticateResponse>
</soap:Body>
</soap:Envelope>AuthenticateResult no son elementos XML hijos: es texto que contiene un objeto JSON. Tu cliente SOAP te devolverá esa cadena, y a partir de ahí el trabajo es de análisis JSON, no de recorrido de nodos.Dentro de AuthenticateResult viaja un objeto JSON plano de cinco campos, en PascalCase.
| Campo | Tipo | Contenido |
|---|---|---|
Result |
booleano | Representa si la transacción fue exitosa o no: true o false |
Token |
string | Token de seguridad para las próximas conexiones con la capa de servicio. Tiene tiempo de expiración |
ErrorCode |
entero | Código de error, en caso de estar codificado. 0 significa que no hubo error |
ErrorMsg |
string | En caso de existir error, tendrá un valor que representa la descripción del error. Llega null en caso exitoso |
Payload |
— | Llega null en esta transacción |
JsonServiceCall devuelve los mismos cinco campos con la misma semántica, pero escritos result, payload, token, errorMsg y errorCode. Si compartes la clase de deserialización entre ambas modalidades, los campos llegarán nulos y tu integración concluirá que no recibió token.| Aspecto del token | Qué se sabe |
|---|---|
| Dónde se obtiene | En esta transacción, y después en cada respuesta de JSONServiceCall |
| Cuál usar | Siempre el último devuelto |
| Dónde se envía | Como parámetro de JSONServiceCall |
| Caducidad | 10 minutos |
| Formato | Cadena |
El sobre y el objeto JSON mantienen su forma. Cambia el contenido.
| Campo | Contenido en error |
|---|---|
Result |
false |
ErrorCode |
Código distinto de 0. Ver apartado 10 |
ErrorMsg |
Descripción del error |
Token |
null, conserva el token anterior tras un fallo |
Payload |
null |
| Código | Significado | Causa | Remedio |
|---|---|---|---|
0 |
Sin error | La operación se ejecutó correctamente | — |
101 |
Token expirado | La vida del token expiró | Autenticarte de nuevo con esta transacción y obtener un token nuevo |
102 |
Token inválido | Al desencriptar y analizar los valores que la llamada incluye como información de autenticación, la operación falla | Revisar que estés enviando el último token devuelto, completo y sin alterar. Si persiste, autenticarte de nuevo |
101 y 102 no los devuelve esta transacción: los recibes al invocar JSONServiceCall, cuando el token que enviaste ya no sirve. Se documentan aquí porque la respuesta a ambos es volver a autenticarte.| Aspecto | Valor |
|---|---|
| Alcance | Un RFC y un usuario por llamada |
| Efectos | Ninguno sobre comprobantes. Abre una sesión |
| Idempotencia | Cada llamada devuelve un token |
| Vida del token | 10 minutos |
| Bloqueo por intentos fallidos | No |
| Timeout | 60 segundos en servidor front |
.asmx que atiende EndPoint es el mismo que atiende la modalidad SOAP clásica. Un cambio en ese servicio afecta a ambas modalidades.Problema. El código que recorre la respuesta buscando elementos XML no localiza Result, Token ni los demás campos.
Entorno. EndPoint · integraciones nuevas, o migradas desde la modalidad SOAP.
Resolución. No son elementos XML. El contenido de AuthenticateResult es una cadena de texto que contiene un objeto JSON. Extrae esa cadena y analízala con tu librería JSON. El trabajo con XML termina en el sobre; a partir de ahí es JSON.
Causa. EndPoint es una modalidad híbrida: sobre SOAP, contenido JSON. Es su rasgo distintivo y la primera fuente de confusión al implementarla, sobre todo porque el servicio es el mismo que el de la modalidad SOAP clásica, donde la respuesta sí es XML.
Problema. Duda sobre si la dirección del servicio es la correcta, al coincidir con la de otra modalidad.
Entorno. EndPoint · integraciones nuevas.
Resolución. Es correcta. EndPoint no es un servicio aparte: son dos operaciones adicionales —AUTHENTICATE y JSONServiceCall— expuestas por el mismo .asmx que atiende la modalidad SOAP. Lo que determina en qué modalidad estás no es la dirección, sino qué operación invocas dentro del sobre y qué forma tiene la respuesta.
Causa. La documentación presenta EndPoint como un servicio distinto.
Problema. La deserialización no falla pero todos los campos llegan vacíos, incluido el token.
Entorno. EndPoint · integraciones que consumen también API REST por JsonServiceCall.
Resolución. Los nombres de los campos están en PascalCase: Result, Payload, Token, ErrorMsg y ErrorCode. En API REST por JsonServiceCall los mismos cinco campos van en camelCase. Define una clase por modalidad, o configura tu deserializador para que no distinga mayúsculas y minúsculas.
Causa. Mismos campos, misma semántica, distinta capitalización. Es un fallo silencioso: no produce excepción, solo valores nulos, y el síntoma aparente es «no recibí token».
Problema. La autenticación devuelve token y la primera transacción funciona, pero a partir de la segunda empiezan los rechazos.
Entorno. EndPoint · integraciones nuevas.
Resolución. El token rota: cada llamada a JSONServiceCall devuelve uno nuevo que sustituye al anterior. Tu integración tiene que leer el token de cada respuesta y usarlo en la llamada siguiente. Guárdalo en una variable que se sobrescriba, no en una constante de configuración.
Causa. Se trató el token como un valor fijo de sesión. En esta plataforma no lo es.
Problema. Un proceso que lanza varias llamadas a la vez produce rechazos intermitentes de token sin un patrón claro.
Entorno. EndPoint · procesos multihilo o de timbrado masivo.
Resolución. Serializa las llamadas de una misma sesión: con un token que rota en cada respuesta, dos peticiones simultáneas que parten del mismo token dejan al menos una con un token ya sustituido.
Problema. Una llamada a JSONServiceCall devuelve el código 101.
Entorno. EndPoint · sesiones de larga duración.
Resolución. El token caducó. Vuelve a ejecutar AUTHENTICATE, toma el token nuevo y reintenta la llamada que falló. No es un error de credenciales ni de datos: es el ciclo normal de una sesión. Conviene que tu integración lo contemple como un caso esperado y no como una excepción.
Causa. El token tiene tiempo de expiración.
Problema. Una llamada devuelve el código 102.
Entorno. EndPoint.
Resolución. El token es inválido, lo que significa que la plataforma no pudo desencriptar ni analizar la información de autenticación que enviaste. Revisa que estés mandando el último token devuelto, completo y sin recortes. Ten cuidado especialmente con el espacio en blanco: al extraer el token de un elemento XML es fácil arrastrar saltos de línea o sangría, y es un riesgo propio de esta modalidad que no existe en las que intercambian JSON puro. Si todo está correcto, autentícate de nuevo.
Causa. Token alterado, truncado, con espacio en blanco sobrante, o de una sesión anterior.
Problema. Se obtuvo el token pero no queda claro cómo enviarlo.
Entorno. EndPoint · integraciones nuevas.
JSONServiceCall, que es el otro servicio de la modalidad y el único a través del cual se ejecutan transacciones. Consulta su artículo para la forma exacta de la petición. Problema. El intento de autenticar con las credenciales de otra modalidad falla.
Entorno. EndPoint · integraciones que migran entre modalidades.
RequestTransaction, esas usan identificadores de tipo GUID y no sirven aquí.EndPoint no es un servicio aparte. Es el mismo .asmx que atiende la modalidad SOAP clásica, al que se le añadieron dos operaciones — AUTHENTICATE y JSONServiceCall— que trabajan con cargas JSON en lugar de con las estructuras XML de las operaciones originales.
Visto así deja de parecer una modalidad independiente y se entiende mejor como una capa moderna montada sobre un servicio existente: se conserva el transporte SOAP, que en muchos entornos empresariales ya está resuelto y autorizado en los cortafuegos, y se sustituye el contenido por JSON, más ligero de componer y de leer que el XML equivalente.
| Modalidad | Destino | Petición | Respuesta | Autenticación |
|---|---|---|---|---|
| SOAP | factwsfront.asmx |
Sobre SOAP | XML | Credenciales en cada petición |
| EndPoint | el mismo .asmx |
Sobre SOAP | JSON dentro del sobre, PascalCase | Token rotatorio |
| API REST · RequestTransaction | /RequestTransaction |
JSON | JSON, nombres con sufijo Field |
Credenciales en cada petición |
| API REST · JsonServiceCall | /JsonServiceCall |
JSON | JSON, camelCase | Token rotatorio |
Leída en conjunto, la tabla sugiere que las dos parejas no se formaron por transporte sino por generación: las dos modalidades con credenciales en cada petición son las antiguas, y las dos con token rotatorio son las nuevas, una sobre cada transporte. EndPoint y API REST por JsonServiceCall son, en el fondo, el mismo diseño expuesto de dos maneras.
Un token fijo que viviera toda la sesión sería más cómodo, pero también más valioso para quien lo interceptara: serviría hasta su caducidad. Al sustituirlo en cada respuesta, el valor capturado en una llamada queda obsoleto en cuanto el cliente legítimo ejecuta la siguiente. Es un esquema más seguro y, a cambio, más exigente con la integración: obliga a tratar el token como estado vivo y no como configuración.
Esta transacción y su equivalente en API REST por JsonServiceCall devuelven exactamente los mismos cinco campos, con la misma semántica y la misma convención de éxito. Lo único que cambia es la capitalización de los nombres. Parece trivial, pero es el tipo de diferencia que más cuesta diagnosticar: no produce una excepción que señale el problema, sino una estructura con todos los campos nulos, y el síntoma que llega a Soporte es «no me devuelve el token» cuando el token sí venía en la respuesta.
Si tu organización consume las dos modalidades, conviene decidir desde el principio si cada una tendrá su propia clase de respuesta o si el deserializador se configurará para ignorar mayúsculas y minúsculas. Ambas soluciones funcionan; lo que no funciona es suponer que una clase sirve para las dos.
Las modalidades antiguas se apoyan en identificadores de tipo GUID, que son largos y aleatorios pero que no se memorizan ni se rotan. Las nuevas usan contraseña, y eso cambia el tratamiento en tres sentidos: no debe quedar escrita en código ni en repositorios, no debe aparecer en bitácoras de la integración, y debería rotarse con alguna periodicidad. Lo primero y lo segundo dependen de ti.
El campo se llama ErrorCode: es un código de error, y cero significa «ningún error», que es la convención habitual en ese tipo de campo. Conviene tenerlo presente porque en API REST por RequestTransaction el campo equivalente se llama codeField, es un código de resultado, y el éxito es uno. Cada nombre es coherente con su propia lógica; lo que no es coherente es que convivan en la misma plataforma sin un aviso.