FIRMAR_RETENCION — SERVICIO CFDI + Timbrado (API REST) - Request Transaction

FIRMAR_RETENCION — SERVICIO CFDI + Timbrado (API REST) - Request Transaction

Estado Transacción: Vigente · Compatibilidad: CFDI de Retenciones e Información de Pagos, Anexo 20 vigente · Última revisión: 07/08/2026 · Próxima revisión: 07/11/2026 · Responsable: Jan Martínez


De un vistazo


Qué hace: certifica un comprobante de retenciones conforme al Anexo 20 vigente. Le envías el XML del CFDI de Retenciones e Información de Pagos que construyó tu sistema, MYSuite lo sella, lo timbra y te devuelve el comprobante certificado en Base64.


Cuándo se usa: cuando tu empresa debe emitir constancias de retenciones e información de pagos, por ejemplo por pagos a residentes en el extranjero, dividendos, intereses, arrendamiento en fideicomiso o enajenación de acciones.


Cuándo no usarla: para comprobantes de ingreso, egreso, traslado, nómina o pago, que son CFDI ordinarios y se emiten con CONVERT_NATIVE_XML. Tampoco devuelve la representación gráfica: para el PDF de una retención se usa GET_DOCUMENT_RETENCIONES.


La respuesta no te devuelve el Folio Fiscal. identifierField llega null: el UUID, la fecha de timbrado y los sellos existen únicamente dentro del comprobante certificado. Para registrar la retención en tu ERP tienes que decodificar responseData1Field y leer el Timbre Fiscal Digital del XML.
El comprobante se envía sin sellar, pero con los atributos de sello presentes. En el XML que mandes en Data1 los atributos Sello, NoCertificado y Certificado deben llevar valores de marcador: Sello="0", NoCertificado="00000000000000000000" y Certificado="0". MYSuite los sustituye por los que correspondan al contribuyente emisor al certificar.
Advertencia de homonimia. Existe la misma transacción en la modalidad CFDI + Timbrado sobre SOAP. Cada transporte se documenta en un artículo independiente. Este cubre exclusivamente API REST.


Cómo saber si este es tu artículo


Si tu integración… Tu artículo es...
Emite constancias de retenciones enviando un cuerpo JSON por HTTP POST Este artículo
Hace lo mismo enviando un sobre SOAP a FactWSFront FIRMAR_RETENCION — CFDI + Timbrado (SOAP)
Emite CFDI de ingreso, egreso, traslado, nómina o pago enviando un cuerpo JSON por HTTP POST CONVERT_NATIVE_XML — CFDI + Timbrado (API REST) - Request Transaction
Necesita el PDF de una retención ya certificada enviando un cuerpo JSON por HTTP POST GET_DOCUMENT_RETENCIONES — CFDI + Timbrado (API REST) - Request Transaction
Necesita el XML o el PDF de un CFDI ordinario almacenado enviando un cuerpo JSON por HTTP POST RETRIEVE_DOCUMENT — CFDI + Timbrado (API REST) - Request Transaction


Requisitos previos

  • Credenciales de integración vigentes que te proporciona MYSuite: Requestor y Entity.
  • CSD del emisor cargado y vigente en la plataforma MYSuite (sólo ambiente productivo).
  • Capacidad de tu sistema para construir el XML del CFDI de Retenciones conforme al esquema que publica el SAT. MYSuite no lo construye por ti: aquí no interviene el XML Nativo.
  • Capacidad de tu ERP para codificar y decodificar Base64, y para leer el XML certificado que recibas.


Cómo hacerlo

  1. Construye el XML del CFDI de Retenciones e Información de Pagos conforme al esquema vigente del SAT.
    Resultado: un comprobante de retención bien formado, aún sin certificar.
  2. Coloca los valores de marcador en los atributos de sello: Sello="0", NoCertificado="00000000000000000000" y Certificado="0".
    Resultado: el comprobante queda listo para que MYSuite lo selle.
  3. Agrega los complementos fiscales que correspondan al tipo de retención que estás emitiendo.
    Resultado: comprobante completo conforme a la obligación que amparas.
  4. Incluye la addenda de MYSuite dentro del elemento retenciones:Addenda si quieres que la plataforma distribuya por correo el XML y el PDF. Es opcional.
    Resultado: instrucciones de distribución por correo embebidas en el comprobante.
  5. Codifica el XML completo en Base64, sin saltos de línea intermedios.
    Resultado: una cadena Base64 en una sola línea.
  6. Arma el cuerpo JSON con los nueve campos: las credenciales, Transaction con valor FIRMAR_RETENCION, la cadena Base64 en Data1, el literal XML en Data2 y Data3 como cadena vacía.
    Resultado: petición lista. Si Data2 no dice XML, no vas a recibir el comprobante certificado.
  7. Envía la petición POST al recurso /RequestTransaction con Content-Type: application/json.
    Resultado: respuesta HTTP 200 con un cuerpo JSON de tres objetos.
  8. Lee responseField.resultField.
    Resultado: responseField = true te permite continuar; responseField = false te lleva a Solución de problemas.
  9. Decodifica responseDataField.responseData1Field desde Base64.
    Resultado: el XML del comprobante de retención ya certificado, con su Timbre Fiscal Digital.
  10. Extrae del XML certificado los datos del Timbre Fiscal Digital: Folio Fiscal (UUID), fecha de timbrado y sello del SAT. La respuesta no incluye identifierField, así que estos datos solo están dentro del comprobante.
    Resultado: los identificadores necesarios para registrar la retención en tu sistema.
  11. Conserva el XML certificado y registra la retención en tu ERP. Si necesitas la representación gráfica, solicítala después con GET_DOCUMENT_RETENCIONES.
    Resultado: retención emitida, resguardada y conciliada.

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


Contrato técnico

1. Endpoint y operación

Protocolo HTTP/1.1 sobre HTTPS · arquitectura REST con cuerpo JSON
Método POST
Recurso /RequestTransaction
Content-Type application/json
Accept application/json
Valor Transaction FIRMAR_RETENCION
Naturaleza Emisión. Sella y certifica un comprobante fiscal con efectos ante el SAT
Consumo
Descuenta 1 folio del paquete vigente. 


2. Ambientes

Ambiente URL
Pruebas https://api.mysuitetest.com/RequestTransaction
Producción https://api.mysuitecfdi.com/RequestTransaction
Restricción del ambiente de pruebas. Un cliente CFDI + Timbrado (API REST) debe usar JES900109Q90 como RFC emisor (Entity). Los RFC admitidos como receptores están en el catálogo de RFC autorizados para pruebas:


3. Autenticación

Esta modalidad no usa token: las credenciales viajan como campos del cuerpo JSON en cada petición.

Campo Tipo Obligatorio Formato Descripción
Requestor string Sí GUID Dato que proporciona MYSuite, relacionado con la seguridad de la transacción, con los procesos de autenticación y autorización
Transaction string Sí Literal en mayúsculas Método que quieres invocar. Para esta transacción: FIRMAR_RETENCION
Country string Sí Valor fijo MX Abreviatura del país
Entity string Sí RFC (12–13 caracteres) RFC del emisor de la retención. En ambiente de test es JES900109Q90
User string Sí GUID Se repite el valor de Requestor
UserName string Sí Country.Entity.Usuario_ERP Identifica al usuario del ERP. Ejmplo MX.JES900109Q90.Jan


4. Parámetros de entrada


Nombre Tipo Obligatorio Límite Formato Descripción
Data1 string Sí 1 MB en servicio síncronos Base64 XML del CFDI de Retenciones conforme al Anexo 20, con los atributos de sello en valores de marcador. Ver apartado 5
Data2 string Sí — Literal XML Debe especificarse XML para que la respuesta traiga la retención en Base64. Si se envía vacío no se entrega XML en la respuesta
Data3 string No — Cadena vacía "" Sin uso en esta transacción. El campo debe estar presente en el JSON con valor vacío


5. Estructura de lo que se envía en Data1, Data2 y Data3

Data1 — XML del CFDI de Retenciones e Información de Pagos

El comprobante se construye conforme al esquema que publica el SAT. A diferencia de las transacciones de emisión de CFDI ordinarios, aquí no interviene el XML Nativo de MYSuite: tu sistema entrega el comprobante fiscal ya armado, MYSuite solo lo sella y lo certifica.

Esquema y documentación CFDI de Retenciones — SAT
Anexo 20 Anexo 20 — SAT
Versión del comprobante Versión del CFDI de Retenciones vigente Anexo 20
Codificación de transporte Base64, en una sola línea

Atributos de sello: valores de marcador obligatorios
Atributo Valor que debes enviar Valor que devuelve MYSuite
Sello 0 Sello digital del contribuyente emisor
NoCertificado 00000000000000000000 (20 ceros) Número de certificado del CSD del emisor
Certificado 0 Certificado del emisor

Alert
Los atributos deben estar presentes porque el esquema del SAT los exige, pero su contenido real lo pone MYSuite al certificar, usando el CSD que tienes cargado en la plataforma.


Complementos fiscales

En la estructura del CFDI de Retenciones puedes agregar los complementos fiscales que publica la autoridad, según el tipo de retención que ampares. El listado vigente está en Complementos de factura — SAT.


Distribución por correo: AddendaMysuite

Si quieres que MYSuite envíe por correo el XML y el PDF de la retención, incluye el elemento ams:AddendaMysuite dentro del elemento retenciones:Addenda del comprobante.

<retenciones:Addenda>
<ams:AddendaMysuite
xsi:schemaLocation="mx.com.fact.addenda.mysuite http://www.mysuitemex.com/fact/schema/addenda-mysuite.xsd"
xmlns:ams="mx.com.fact.addenda.mysuite"
Version="1">
<ams:Procesamiento>
<ams:Dictionary name="email">
<ams:Entry k="from" v="ACCOUNT_OWNER"/>
<ams:Entry k="to" v="destinatario@dominio.com"/>
<ams:Entry k="formats" v="xml pdf"/>
</ams:Dictionary>
</ams:Procesamiento>
</ams:AddendaMysuite>
</retenciones:Addenda>
Entrada (k) Obligatorio Formato Descripción
from Sí ACCOUNT_OWNER u otro valor Remitente del correo. ACCOUNT_OWNER usa la cuenta de correo configurada en el titular en MYSuite.
to Sí Dirección de correo Destinatario del envío
formats Sí xml · pdf · xml pdf Archivos que se adjuntan al correo
Conviene notar que la addenda viaja como XML dentro del comprobante, aunque la petición sea JSON. Las instrucciones de distribución no son parámetros de la transacción: forman parte del documento que envías.

Detalle completo del elemento: Elemento Procesamiento

Data2 y Data3

Data2 lleva el literal XML. Data3 se envía como cadena vacía.


6. Ejemplo de request

POST /RequestTransaction HTTP/1.1
Host: api.mysuitetest.com
Content-Type: application/json

{
"Requestor": "0c320b03-d4f1-47bc-9fb4-77995f9bf33e",
"Transaction": "FIRMAR_RETENCION",
"Country": "MX",
"Entity": "JES900109Q90",
"User": "0c320b03-d4f1-47bc-9fb4-77995f9bf33e",
"UserName": "MX.JES900109Q90.Jan",
"Data1": "PHJldGVuY2lvbmVzOlJldGVuY2lvbmVzIFZlcnNpb249IjIuMCIgRm9saW9JbnQ9IjMiIFNlbGxvPSIwIiBOb0NlcnRpZmljYWRvPSIwMDAwMDAwMDAwMDAwMDAwMDAwMCIgQ2VydGlmaWNhZG89IjAiIEZlY2hhRXhwPSIyMDI2LTEwLTAxVDAwOjAwOjAxIiBMdWdhckV4cFJldGVuYz0iMDEwMzAiIEN2ZVJldGVuYz0iMTgiIHhzaTpzY2hlbWFMb2NhdGlvbj0iaHR0cDovL3d3dy5zYXQuZ29iLm14L2VzcXVlbWFzL3JldGVuY2lvbnBhZ28vMiBodHRwOi8vd3d3LnNhdC5nb2IubXgvZXNxdWVtYXMvcmV0ZW5jaW9ucGFnby8yL3JldGVuY2lvbnBhZ292Mi54c2QgaHR0cDovL3d3dy5zYXQuZ29iLm14L2VzcXVlbWFzL3JldGVuY2lvbnBhZ28vMS9wYWdvc2FleHRyYW5qZXJvcyBodHRwOi8vd3d3LnNhdC5nb2IubXgvZXNxdWVtYXMvcmV0ZW5jaW9ucGFnby8xL3BhZ29zYWV4dHJhbmplcm9zL3BhZ29zYWV4dHJhbmplcm9zLnhzZCIgeG1sbnM6cGFnb3NhZXh0cmFuamVyb3M9Imh0dHA6Ly93d3cuc2F0LmdvYi5teC9lc3F1ZW1hcy9yZXRlbmNpb25wYWdvLzEvcGFnb3NhZXh0cmFuamVyb3MiIHhtbG5zOnJldGVuY2lvbmVzPSJodHRwOi8vd3d3LnNhdC5nb2IubXgvZXNxdWVtYXMvcmV0ZW5jaW9ucGFnby8yIiB4bWxuczp4c2k9Imh0dHA6Ly93d3cudzMub3JnLzIwMDEvWE1MU2NoZW1hLWluc3RhbmNlIj4KICAgIDxyZXRlbmNpb25lczpFbWlzb3IgUmZjRT0iSkVTOTAwMTA5UTkwIiBOb21EZW5SYXpTb2NFPSJKSU1FTkVaIEVTVFJBREEgU0FMQVMgQSBBIiBSZWdpbWVuRmlzY2FsRT0iNjAxIiAvPgogICAgPHJldGVuY2lvbmVzOlJlY2VwdG9yIE5hY2lvbmFsaWRhZFI9IkV4dHJhbmplcm8iPgogICAgICAgIDxyZXRlbmNpb25lczpFeHRyYW5qZXJvIE5vbURlblJhelNvY1I9Ik5JREVDIFBPV0VSVFJBSU4gU1lTVEVNUyBDT1JQT1JBVElPTiIgLz4KICAgIDwvcmV0ZW5jaW9uZXM6UmVjZXB0b3I+CiAgICA8cmV0ZW5jaW9uZXM6UGVyaW9kbyBNZXNJbmk9IjA4IiBNZXNGaW49IjA4IiBFamVyY2ljaW89IjIwMjUiIC8+CiAgICA8cmV0ZW5jaW9uZXM6VG90YWxlcyBNb250b1RvdE9wZXJhY2lvbj0iMjI5MjUzOS44MyIgTW9udG9Ub3RHcmF2PSIyMjkyNTM5LjgzIiBNb250b1RvdEV4ZW50PSIwIiBNb250b1RvdFJldD0iMjI5MjUzLjk4IiBJU1JDb3JyZXNwb25kaWVudGU9IjAiPgogICAgICAgIDxyZXRlbmNpb25lczpJbXBSZXRlbmlkb3MgQmFzZVJldD0iMjI5MjUzLjk4IiBJbXB1ZXN0b1JldD0iMDAxIiBNb250b1JldD0iMjI5MjUzLjk4IiBUaXBvUGFnb1JldD0iMDMiIC8+CiAgICA8L3JldGVuY2lvbmVzOlRvdGFsZXM+CiAgICA8cmV0ZW5jaW9uZXM6Q29tcGxlbWVudG8+CiAgICAgICAgPHBhZ29zYWV4dHJhbmplcm9zOlBhZ29zYWV4dHJhbmplcm9zIFZlcnNpb249IjEuMCIgRXNCZW5lZkVmZWN0RGVsQ29icm89Ik5PIj4KICAgICAgICAgICAgPHBhZ29zYWV4dHJhbmplcm9zOk5vQmVuZWZpY2lhcmlvIFBhaXNEZVJlc2lkUGFyYUVmZWNGaXNjPSJKUCIgQ29uY2VwdG9QYWdvPSIzIiBEZXNjcmlwY2lvbkNvbmNlcHRvPSJSZWdhbGlhcyBwb3IgYXNpc3RlbmNpYSB0ZWNuaWNhIiAvPgogICAgICAgIDwvcGFnb3NhZXh0cmFuamVyb3M6UGFnb3NhZXh0cmFuamVyb3M+CiAgICA8L3JldGVuY2lvbmVzOkNvbXBsZW1lbnRvPgo8L3JldGVuY2lvbmVzOlJldGVuY2lvbmVzPg==",
"Data2": "XML",
"Data3": ""
}

7. Ejemplo de response

{
"requestField": {
"requestorField": "00000000-0000-0000-0000-000000000000",
"requestorNameField": null,
"requestorActiveField": true,
"transactionField": 108,
"countryField": "MX",
"entityField": "JES900109Q90",
"userField": "00000000-0000-0000-0000-000000000000",
"userNameField": "MX.JES900109Q90.Jan",
"idField": "6ac6a6a4-5bbe-4d51-97f2-068d3c1d5fef",
"timeStampField": "2026-10-01T12:31:34.4818927-06:00"
},
"responseField": {
"resultField": true,
"timeStampField": "2026-10-01T12:31:35.6753973-06:00",
"lastResultField": "",
"codeField": 1,
"descriptionField": "",
"hintField": "",
"dataField": " 7177 6ac6a6a4-5bbe-4d51-97f2-068d3c1d5fef",
"processorField": "TEST-BACK03",
"identifierField": null,
"batchIdentifierField": null
},
"responseDataField": {
"responseData1Field": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48cmV0ZW5jaW9uZXM6UmV0ZW5jaW9uZXMgVmVyc2lvbj0iMi4wIiBGb2xpb0ludD0iMyIgU2VsbG89IkpkL2FJMlJMQ3VZaC9qLzZWdUlZbXlpN1NvLzN4bEk1SXR4K05BTmFvaUQyWFVqdlVCanpmSnF2OEF0eWVmdDd0NitSOHgzSFdtRHBpSFllQitNMm9rOTRJY2NMTTNva1NjUThOTWxaakp3NEYwT2VMVTFKd1RsY1N2RUxJc2Q4dTVya2ZKS3NISDdhMHFxOWxpOTZUWC9JUFUrWWJTRDYrd3pYQmovRm1DbzdvL1ZRZFMvQ3RWM2FZclVUamQ3aVJycUR3QjBwaU5TZFNCTllmbndtckgxNEx3ZUF0ZnYzOUtGTTZjS2hPTkg4QmRCRmRkS0NDWE1BNmhrTDUzUlJlVXZYWXRPcVJpTWRFelQvUEFyeW5tSW9lcCs3ZzI0c0tNdlV5M3lwbGdzTm5mZWFJSlFxUjdkNG5kalJSMFpvenY5WVVqV0svVDF2RFpSL1EvS0xNQT09IiBOb0NlcnRpZmljYWRvPSIzMDAwMTAwMDAwMDUwMDAwMzQzNiIgQ2VydGlmaWNhZG89Ik1JSUZvVENDQTRtZ0F3SUJBZ0lVTXpBd01ERXdNREF3TURBMU1EQXdNRE0wTXpZd0RRWUpLb1pJaHZjTkFRRUxCUUF3Z2dFck1ROHdEUVlEVlFRRERBWkJReUJWUVZReExqQXNCZ05WQkFvTUpWTkZVbFpKUTBsUElFUkZJRUZFVFVsT1NWTlVVa0ZEU1U5T0lGUlNTVUpWVkVGU1NVRXhHakFZQmdOVkJBc01FVk5CVkMxSlJWTWdRWFYwYUc5eWFYUjVNU2d3SmdZSktvWklodmNOQVFrQkZobHZjMk5oY2k1dFlYSjBhVzVsZWtCellYUXVaMjlpTG0xNE1SMHdHd1lEVlFRSkRCUXpjbUVnWTJWeWNtRmtZU0JrWlNCallXeHBlakVPTUF3R0ExVUVFUXdGTURZek56QXhDekFKQmdOVkJBWVRBazFZTVJrd0Z3WURWUVFJREJCRFNWVkVRVVFnUkVVZ1RVVllTVU5QTVJFd0R3WURWUVFIREFoRFQxbFBRVU5CVGpFUk1BOEdBMVVFTFJNSU1pNDFMalF1TkRVeEpUQWpCZ2txaGtpRzl3MEJDUUlURm5KbGMzQnZibk5oWW14bE9pQkJRMFJOUVMxVFFWUXdIaGNOTWpNd05URTRNVEkxTVRRM1doY05NamN3TlRFNE1USTFNVFEzV2pDQnlERWlNQ0FHQTFVRUF4TVpTa2xOUlU1RldpQkZVMVJTUVVSQklGTkJURUZUSUVFZ1FURWlNQ0FHQTFVRUtSTVpTa2xOUlU1RldpQkZVMVJTUVVSQklGTkJURUZUSUVFZ1FURWlNQ0FHQTFVRUNoTVpTa2xOUlU1RldpQkZVMVJTUVVSQklGTkJURUZUSUVFZ1FURWxNQ01HQTFVRUxSTWNTa1ZUT1RBd01UQTVVVGt3SUM4Z1ZrRkVRVGd3TURreU4wUktNekVlTUJ3R0ExVUVCUk1WSUM4Z1ZrRkVRVGd3TURreU4waFRVbE5TVERBMU1STXdFUVlEVlFRTEV3cFRkV04xY25OaGJDQXhNSUlCSWpBTkJna3Foa2lHOXcwQkFRRUZBQU9DQVE4QU1JSUJDZ0tDQVFFQXFzVmRERjdXcHdNYzN6Q0RkSkhyMnVxSEJHNUNQbFYxZ3N6YXAzeFFaY3gyaCtiZitneEFOSlk4YU5kMlJhWVh6VkNvL1NRbHczTi9WWkY5Z2FEa29mN0RKQ3QwVWRaSEZWbzZGSW9Zb1I0eXV5V2JoYzBvdGwxS1pzUWErTkRveURQSGYyRklSWUh6clpmaDFrUElHMVNVeGRVUmdPZWlXeWIrUUpXZjh5c2YyQllIemk1bjJrVEtpcll3L2ZtcDN4YURxQldFWFpvaVhYWXp3cTRTN2xTVzM2MURTNVNLSHZXYktVcUNmbkNOc3BSSWgyMmNET043TXQyUVBtQ0M0NGdhMTVYaHFURm1JTUpQMGZEV2RGN3hGcnFQVkEyTEVjdFdNNlR3V0E3L1RpazcrTnlibklwTnp4bkRYczBJZUFick5ycTJUNEVBc1FlMVZjdWNNUUlEQVFBQm94MHdHekFNQmdOVkhSTUJBZjhFQWpBQU1Bc0dBMVVkRHdRRUF3SUd3REFOQmdrcWhraUc5dzBCQVFzRkFBT0NBZ0VBR1FqaWdXWlIrSVczMFZhRlNNVjJhUVAxcnU2OEFoUnpianpoWk1NNWkvVFpMS1NXOVdzaHFwd0VTQXdUOEJjWWNTdWdtTVBXSzQ5OWQ2QTdNaUhOWFJRUGZYMzBGNS8wZHptVW1EaEtjNTR1dFMvcjAzQ2pLd09RYmdEMFRnQjBkRHVSZDYrOXd1a1R4bUZmWWRmUTBuMGdUaGVEREhuaHRvemxPYXMydTNXWFNiYWZOdW5qek92Yk9YR1hreHZIK3l3S0prMG1CMjNjbmVVWGw4dnArVGJkMmRoY2U2S0oyUytyYXgwNDNualoxaWJoRFZKTDJnaksyMDJpOC80a2lUSHpob0pwM2dPV2NsZ1U0b2NZR0wzanlRTDNBMTh3WVBTRVQxcHRTaEN3K1dRYjZpTHRwSDROOXZDWVFZN0djRjRjK1NRYnVoSUZpR1JLRm5NVjIwallDQlRjTXVyYVlzZklrU0VaRVpmV0xpc2FsU3lodWU3NXFwM29tWm1JQjc2QlEzakpRUUdaUlUwbzVNMjdJa2xxU2pMMHE5MnZLajlUbnpRWFpTVkxEUTlKSzg5WXFwRGFsdHVGbUo1cHBMOTlBa3h4NzZ3bWs2bDdENXJCTldQMjhrN3RSc29DYTNMU0FCZUV4U2RJNDRCZDU4LzAxU3RORkRkR1ZPQ1hXaEt2OTg0TVhRaVJBZFM3dFZ0RjBzTSt6MjcrVHlnZHFlQ3FodC9NenlnbEdoMHlWU2draGJXbjhyRjNYczdmRGFWU2c3bE1qOGxjdjhVVEtWUnhMUWh6aGRoS2wybmluYVA3Z3V5UHZURzhxUnNOeks5dC9yR3plSkhIRDliT0FHdDhNN3VzdFY1eDlaRDNjVkVhZVFLUWhTZS83Wm5TTTE3VTFuZVQrL0E9IiBGZWNoYUV4cD0iMjAyNi0xMC0wMVQwMDowMDowMSIgTHVnYXJFeHBSZXRlbmM9IjAxMDMwIiBDdmVSZXRlbmM9IjE4IiB4c2k6c2NoZW1hTG9jYXRpb249Imh0dHA6Ly93d3cuc2F0LmdvYi5teC9lc3F1ZW1hcy9yZXRlbmNpb25wYWdvLzIgaHR0cDovL3d3dy5zYXQuZ29iLm14L2VzcXVlbWFzL3JldGVuY2lvbnBhZ28vMi9yZXRlbmNpb25wYWdvdjIueHNkIGh0dHA6Ly93d3cuc2F0LmdvYi5teC9lc3F1ZW1hcy9yZXRlbmNpb25wYWdvLzEvcGFnb3NhZXh0cmFuamVyb3MgaHR0cDovL3d3dy5zYXQuZ29iLm14L2VzcXVlbWFzL3JldGVuY2lvbnBhZ28vMS9wYWdvc2FleHRyYW5qZXJvcy9wYWdvc2FleHRyYW5qZXJvcy54c2QgIiB4bWxuczpyZXRlbmNpb25lcz0iaHR0cDovL3d3dy5zYXQuZ29iLm14L2VzcXVlbWFzL3JldGVuY2lvbnBhZ28vMiIgeG1sbnM6cGFnb3NhZXh0cmFuamVyb3M9Imh0dHA6Ly93d3cuc2F0LmdvYi5teC9lc3F1ZW1hcy9yZXRlbmNpb25wYWdvLzEvcGFnb3NhZXh0cmFuamVyb3MiIHhtbG5zOnhzaT0iaHR0cDovL3d3dy53My5vcmcvMjAwMS9YTUxTY2hlbWEtaW5zdGFuY2UiPjxyZXRlbmNpb25lczpFbWlzb3IgUmZjRT0iSkVTOTAwMTA5UTkwIiBOb21EZW5SYXpTb2NFPSJKSU1FTkVaIEVTVFJBREEgU0FMQVMgQSBBIiBSZWdpbWVuRmlzY2FsRT0iNjAxIiAvPjxyZXRlbmNpb25lczpSZWNlcHRvciBOYWNpb25hbGlkYWRSPSJFeHRyYW5qZXJvIj48cmV0ZW5jaW9uZXM6RXh0cmFuamVybyBOb21EZW5SYXpTb2NSPSJOSURFQyBQT1dFUlRSQUlOIFNZU1RFTVMgQ09SUE9SQVRJT04iIC8+PC9yZXRlbmNpb25lczpSZWNlcHRvcj48cmV0ZW5jaW9uZXM6UGVyaW9kbyBNZXNJbmk9IjA4IiBNZXNGaW49IjA4IiBFamVyY2ljaW89IjIwMjUiIC8+PHJldGVuY2lvbmVzOlRvdGFsZXMgTW9udG9Ub3RPcGVyYWNpb249IjIyOTI1MzkuODMiIE1vbnRvVG90R3Jhdj0iMjI5MjUzOS44MyIgTW9udG9Ub3RFeGVudD0iMCIgTW9udG9Ub3RSZXQ9IjIyOTI1My45OCIgSVNSQ29ycmVzcG9uZGllbnRlPSIwIj48cmV0ZW5jaW9uZXM6SW1wUmV0ZW5pZG9zIEJhc2VSZXQ9IjIyOTI1My45OCIgSW1wdWVzdG9SZXQ9IjAwMSIgTW9udG9SZXQ9IjIyOTI1My45OCIgVGlwb1BhZ29SZXQ9IjAzIiAvPjwvcmV0ZW5jaW9uZXM6VG90YWxlcz48cmV0ZW5jaW9uZXM6Q29tcGxlbWVudG8+PHBhZ29zYWV4dHJhbmplcm9zOlBhZ29zYWV4dHJhbmplcm9zIFZlcnNpb249IjEuMCIgRXNCZW5lZkVmZWN0RGVsQ29icm89Ik5PIj48cGFnb3NhZXh0cmFuamVyb3M6Tm9CZW5lZmljaWFyaW8gUGFpc0RlUmVzaWRQYXJhRWZlY0Zpc2M9IkpQIiBDb25jZXB0b1BhZ289IjMiIERlc2NyaXBjaW9uQ29uY2VwdG89IlJlZ2FsaWFzIHBvciBhc2lzdGVuY2lhIHRlY25pY2EiIC8+PC9wYWdvc2FleHRyYW5qZXJvczpQYWdvc2FleHRyYW5qZXJvcz48dGZkOlRpbWJyZUZpc2NhbERpZ2l0YWwgeHNpOnNjaGVtYUxvY2F0aW9uPSJodHRwOi8vd3d3LnNhdC5nb2IubXgvVGltYnJlRmlzY2FsRGlnaXRhbCBodHRwOi8vd3d3LnNhdC5nb2IubXgvc2l0aW9faW50ZXJuZXQvY2ZkL1RpbWJyZUZpc2NhbERpZ2l0YWwvVGltYnJlRmlzY2FsRGlnaXRhbHYxMS54c2QiIFZlcnNpb249IjEuMSIgVVVJRD0iNTZiMzhhZTUtNDBmMi00NjVmLWFmMTYtZjYyZDRmNjcwOWM3IiBGZWNoYVRpbWJyYWRvPSIyMDI2LTEwLTAxVDEyOjMxOjM0IiBSZmNQcm92Q2VydGlmPSJTUFIxOTA2MTNJNTIiIFNlbGxvQ0ZEPSJKZC9hSTJSTEN1WWgvai82VnVJWW15aTdTby8zeGxJNUl0eCtOQU5hb2lEMlhVanZVQmp6ZkpxdjhBdHllZnQ3dDYrUjh4M0hXbURwaUhZZUIrTTJvazk0SWNjTE0zb2tTY1E4Tk1sWmpKdzRGME9lTFUxSndUbGNTdkVMSXNkOHU1cmtmSktzSEg3YTBxcTlsaTk2VFgvSVBVK1liU0Q2K3d6WEJqL0ZtQ283by9WUWRTL0N0VjNhWXJVVGpkN2lScnFEd0IwcGlOU2RTQk5ZZm53bXJIMTRMd2VBdGZ2MzlLRk02Y0toT05IOEJkQkZkZEtDQ1hNQTZoa0w1M1JSZVV2WFl0T3FSaU1kRXpUL1BBcnlubUlvZXArN2cyNHNLTXZVeTN5cGxnc05uZmVhSUpRcVI3ZDRuZGpSUjBab3p2OVlValdLL1QxdkRaUi9RL0tMTUE9PSIgTm9DZXJ0aWZpY2Fkb1NBVD0iMzAwMDEwMDAwMDA1MDAwMDM0NTYiIFNlbGxvU0FUPSJDZGEwaUQvYWsyM0ZZeGpwVStPMlpwK281a3F2V0FLMDFXQkNpNWVnNG10dTBLeFp1SlQvUStuRVMzeDVJblBJZmxpV1gxRDR6K1ZqUjB4emhhYjRhQVZEcFU2SDlWRVRTRzdjaHlSTWx4WVpKV1JUREZVZWZiWkdvcXNwU2Q2SHpNNk02ZlRFeWVrTkRqS0pxaVIyTnliRlBBaFIxZ2VXaHhUQXJJNEZRcmtHOXNZM25MY0krNGNvVjYzVDZxdnFYNnQ2V0tOYVQ3OW42WTlZeEdQL2pqalZWNkdmdnA5ck1KcUFxcXdtVjl4TWhucVNoc0U2UXUvYWpPdlhMVEwwTURQOXYvTTRaVXljMTV2ZVNpV1hRWFduMGVCelZ6dVJlVXQrYmVtNEt1OTVDS1FSa1NyYWtEK0xOL3ZKaThtQ08wTi9jN1d2d2FGcVZvajNiRVpkd3c9PSIgeG1sbnM6dGZkPSJodHRwOi8vd3d3LnNhdC5nb2IubXgvVGltYnJlRmlzY2FsRGlnaXRhbCIgLz48L3JldGVuY2lvbmVzOkNvbXBsZW1lbnRvPjwvcmV0ZW5jaW9uZXM6UmV0ZW5jaW9uZXM+",
"responseData2Field": "",
"responseData3Field": "",
"responseDataSetField": null
}
}

8. Estructura de respuesta — éxito

El cuerpo de la respuesta es un objeto JSON con tres objetos de primer nivel. Todos los nombres de campo llevan el sufijo Field.

requestField — eco de la petición:

Campo Contenido
requestorField · userField GUID recibidos en la petición. Se entrega valor en "0" por seguridad.
requestorNameField Nombre del solicitante. Puede llegar null
requestorActiveField Booleano. Indica si el solicitante está activo
transactionField Entero, no cadena
countryField · entityField · userNameField Eco de los valores recibidos
idField GUID de la operación en la plataforma. Dato a incluir al reportar incidencias
timeStampField Momento de recepción de la petición, con desplazamiento de zona horaria

responseField — resultado del procesamiento:

Campo Contenido
resultField Booleano. true cuando el comprobante fue certificado
codeField Entero. Código de resultado. Ver apartado 10
timeStampField Momento en que concluyó el procesamiento
lastResultField · descriptionField · hintField Vacíos en certificación exitosa. Ver apartado 9
dataField · processorField Referencia interna del procesamiento y Servidor que atendió la solicitud
identifierField Llega null. Esta transacción no devuelve datos de identificación del comprobante
batchIdentifierField Llega null

responseDataField — carga devuelta:

Campo Contenido
responseData1Field Comprobante de Retención certificado, en Base64, si enviaste XML en Data2
responseData2Field Vacío
responseData3Field Vacío
responseDataSetField Llega null
Toda la información del timbrado está dentro del comprobante. A diferencia de CONVERT_NATIVE_XML, que devuelve el identifierField poblado con el Folio Fiscal, la serie, el folio y las fechas, aquí ese objeto llega null. Decodifica responseData1Field y lee el nodo del Timbre Fiscal Digital: es el único lugar donde existen esos datos.

Datos que debes extraer del XML certificado, del nodo del Timbre Fiscal Digital:

Dato Uso
Folio Fiscal (UUID) Llave única de la retención. Registrar en el ERP. Es también el único criterio de GET_DOCUMENT_RETENCIONES
Fecha de timbrado Momento de la certificación
Sello del SAT y sello del CFD Evidencia de la certificación
RFC del proveedor de certificación Identifica al PAC que timbró
NoCertificado y Certificado del emisor Sustituidos por MYSuite. Confirman que el sellado se aplicó


9. Estructura de respuesta — error

El cuerpo mantiene los tres objetos del apartado 8. Cambia el contenido de responseField y la carga llega vacía.

Campo Contenido en error
resultField false: el comprobante no fue certificado
codeField Código del error. Ver apartado 10
lastResultField Identificador simbólico del error. 
descriptionField · hintField Mensaje del error y sugerencia de corrección
processorField Servidor que atendió la solicitud. 
responseData1Field Vacío
Un error de negocio se reporta con resultField = false dentro de un cuerpo JSON válido. Evalúa siempre ese campo y no asumas éxito por el código de estado HTTP.


10. Códigos de Error


11. Límites y comportamiento


Aspecto Valor
Comprobantes por llamada Uno
Efectos fiscales Irreversibles. La certificación incorpora el Timbre Fiscal Digital y el comprobante existe ante el SAT. Retirarlo requiere una cancelación formal
Consumo de folios por cada resultField = true se descuenta 1 folio del paquete vigente
Idempotencia Si reenvian el mismo comprobante genera una notificación de error y se envía en responseData1Field el xml del cfdi de retención en Base64
Recuperación ante TimeOut Si se pierde la respuesta, el cliente se queda sin ningún dato del comprobante. Volver a solicitar para conocer si ya se tiene registro
Almacenamiento La retención queda almacenada: GET_DOCUMENT_RETENCIONES la recupera después por su Folio Fiscal. Año actual y 5 años hacía atrás
Tamaño máximo de Data1 1 MB servicio síncrono
Timeout 60 segundos en servidor front


12. Versionado y cumplimiento

  • La certificación se realiza conforme al Anexo 20 vigente para el CFDI de Retenciones e Información de Pagos.
  • MYSuite sella con el CSD del emisor y certifica en su calidad de PAC autorizado por el SAT. La conservación del XML certificado es obligación del emisor, y aquí con más razón, porque la respuesta no deja rastro del comprobante fuera del propio archivo.
  • El esquema del comprobante lo publica el SAT, no MYSuite: los cambios normativos impactan directamente al sistema que construye el XML.

Solución de problemas

"No encuentro el folio fiscal en la respuesta"


Problema. El ERP busca el UUID en identifierField y lo encuentra en null.

Entorno. CFDI + Timbrado · API REST · integraciones que reutilizan el código de CONVERT_NATIVE_XML.

Resolución. Esta transacción no devuelve identificación. Decodifica responseData1Field y lee el Folio Fiscal, la fecha de timbrado y los sellos directamente del nodo del Timbre Fiscal Digital dentro del XML certificado. Guarda ese UUID: es el único criterio con el que podrás recuperar la retención más adelante.

Causa. La respuesta de las retenciones es más escueta que la de los CFDI ordinarios: entrega el comprobante y nada más. La capa de lectura de respuesta no se puede compartir entre ambas transacciones.

"Me rechaza el comprobante por el sello"


Problema. La certificación falla al enviar el comprobante con un sello real, con los atributos vacíos o sin ellos.

Entorno. CFDI + Timbrado · API REST · integraciones nuevas.

Resolución. Envía los tres atributos presentes y con valores de marcador: Sello="0", NoCertificado="00000000000000000000" y Certificado="0". No los omitas, porque el esquema del SAT los exige, y no los llenes con datos reales, porque el sellado lo hace MYSuite con el CSD que tienes cargado.

Causa. Se aplicó el criterio de otros flujos donde el emisor sella antes de enviar. Aquí el orden es el inverso: primero envías, después se sella.

"Dice que se timbró pero no me devolvió nada"


Problema. resultField es true pero responseData1Field llega vacío, y el comprobante certificado no aparece por ningún lado.

Entorno. CFDI + Timbrado · API REST · FIRMAR_RETENCION.

Resolución. Revisa el valor de Data2: debe llevar el literal XML para que la respuesta incluya la retención en Base64. Si ya certificaste sin recibirlo, el comprobante existe ante el SAT y no debes volver a certificarlo. Como la respuesta tampoco trae el Folio Fiscal, tendrás que recuperarlo por el portal del SAT y obtenerlo en MYSuite con el Folio Fiscal.

Causa. Data2 vacío o con un valor distinto.

"Necesito el PDF de la retención"


Problema. La respuesta solo trae el XML y el proceso necesita la representación gráfica para enviarla o archivarla.

Entorno. CFDI + Timbrado · API REST · emisión de constancias de retención.

Resolución. Solicita la representación gráfica con GET_DOCUMENT_RETENCIONES, usando el Folio Fiscal que extrajiste del comprobante. Si lo que necesitas es que el receptor la reciba por correo, puedes evitar esa llamada incluyendo la addenda de MYSuite en el comprobante que envías a certificar.

Causa. A diferencia de CONVERT_NATIVE_XML, que puede devolver el PDF en la misma llamada, aquí la representación gráfica se obtiene aparte.

"Puse la addenda y el correo nunca llegó"


Problema. El comprobante se certifica correctamente pero la distribución por correo no ocurre.

Entorno. CFDI + Timbrado · API REST · retenciones con distribución automática.

Resolución. Verifica que ams:AddendaMysuite esté dentro del elemento retenciones:Addenda del comprobante, no en otro lugar del XML, y que el Dictionary se llame email con las tres entradas from, to y formats. Revisa también que el espacio de nombres y la ubicación del esquema estén declarados como indica el ejemplo. Ten presente que la addenda es XML dentro del comprobante, no un campo del JSON.

Causa. La addenda colocada fuera del elemento que le corresponde se ignora silenciosamente: el comprobante es válido y se certifica igual, pero las instrucciones de procesamiento no se leen.

"Se cayó la conexión y no sé si la retención se timbró"


Problema. El ERP no recibe respuesta y no puede determinar si el comprobante quedó certificado.

Entorno. CFDI + Timbrado · API REST · redes con latencia o cortes intermitentes.

Resolución. Reintenta. Un reintento (cuando el comprobante de retención ya existe en MYSuite), te dará una notificación de error y te dará el xml del cfdi de retención en base 64 en el elemento responseData1Field. Debes enviar el xml del cfdi con el mismo tiempo de emisión que en la primer solicitud.

Causa. En retenciones no hay identificador propio del ERP, no hay transacción de búsqueda. 


Para entender más

Por qué la retención es otro documento

El CFDI de Retenciones e Información de Pagos no es una variante del CFDI de factura: es un comprobante distinto, con su propio esquema publicado por el SAT, sus propios complementos y su propio espacio de nombres. Ampara una obligación diferente —informar sobre impuestos retenidos y pagos efectuados— y por eso tiene una transacción propia en lugar de un tipo de comprobante dentro de la emisión ordinaria. Casi nada de lo que sabes de CONVERT_NATIVE_XML se traslada aquí.

Por qué no hay XML Nativo en este flujo

En la emisión ordinaria, MYSuite ofrece un formato propio para que el ERP no tenga que conocer el Anexo 20: tú entregas datos y la plataforma construye el CFDI. En retenciones no existe esa capa intermedia: tu sistema entrega el comprobante fiscal ya armado conforme al esquema del SAT, y MYSuite solo sella y certifica. La consecuencia práctica es que el conocimiento normativo vive de tu lado, y que un cambio de versión del comprobante te obliga a modificar tu código, cosa que en la emisión ordinaria normalmente no ocurre.

Por qué los atributos de sello van en cero

El esquema del SAT declara Sello, NoCertificado y Certificado como atributos del comprobante, así que deben existir para que el XML sea válido. Pero su contenido solo puede calcularlo quien tiene la llave privada del CSD, y en este flujo esa llave la custodia MYSuite. Los valores de marcador resuelven la contradicción: satisfacen al esquema sin afirmar nada falso, y se sustituyen en el momento del sellado. Verlos como campos reservados en lugar de como datos evita la confusión.

Por qué la distribución por correo viaja dentro del comprobante

Podría haberse resuelto con parámetros de la transacción, pero se resolvió con una addenda. La razón es que la addenda viaja con el documento: las instrucciones de envío quedan asociadas al comprobante concreto y no a la llamada, lo que permite que cada retención lleve su propio destinatario sin cambiar la integración. Tiene un efecto llamativo en esta modalidad: acabas enviando XML dentro de un JSON para configurar algo que parecería un parámetro. El costo es que tienes que colocarla en el lugar exacto del XML, y que si te equivocas de lugar el comprobante se certifica igual pero el correo nunca sale.

Por qué el PDF se pide aparte

La representación gráfica de una retención se genera con plantillas distintas de las de un CFDI de factura, y se obtiene con GET_DOCUMENT_RETENCIONES. Separar la certificación de la representación mantiene la primera ligera, que es lo deseable en una operación con efectos fiscales.

Por qué SOAP y REST se documentan por separado

La transacción es la misma operación de negocio en ambos transportes: mismo comprobante, mismos marcadores de sello, misma addenda. Lo que cambia es todo lo que rodea al dato: los encabezados, la forma del cuerpo, la nomenclatura de la respuesta y la manera de leerla. Documentar ambos en un solo artículo obligaría al lector a descartar la mitad del contrato técnico en cada consulta, y es precisamente donde se originan los errores de integración.


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