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.
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.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.| 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 |
Requestor y Entity.Sello="0", NoCertificado="00000000000000000000" y Certificado="0".retenciones:Addenda si quieres que la plataforma distribuya por correo el XML y el PDF. Es opcional.Transaction con valor FIRMAR_RETENCION, la cadena Base64 en Data1, el literal XML en Data2 y Data3 como cadena vacía.Data2 no dice XML, no vas a recibir el comprobante certificado.POST al recurso /RequestTransaction con Content-Type: application/json.responseField.resultField.responseField = true te permite continuar; responseField = false te lleva a Solución de problemas.responseDataField.responseData1Field desde Base64.identifierField, así que estos datos solo están dentro del comprobante.Si algo falla, ve a Solución de problemas.
| 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.
|
| Ambiente | URL |
|---|---|
| Pruebas | https://api.mysuitetest.com/RequestTransaction |
| Producción | https://api.mysuitecfdi.com/RequestTransaction |
JES900109Q90 como RFC emisor (Entity). Los RFC admitidos como receptores están en el catálogo de RFC autorizados para pruebas: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 |
| 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 |
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 |
| 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 |

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.
AddendaMysuiteSi 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 |
Detalle completo del elemento: Elemento Procesamiento
Data2 lleva el literal XML. Data3 se envía como cadena vacía.
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": ""
}{
"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
}
}
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 |
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ó |
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 |
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.| 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 |
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.
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.
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.
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.
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.
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.
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í.
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.
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.
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.
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.
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.
Vía RequestTransaction