---
updatedAt: 2025-05-08T22:51:34.000Z
agentTools:
  projectIndex: https://developers.timbracfdi33.mx/llms.txt
---

# Timbra Retención

A través de esta función podrás timbrar un comprobante de retenciones e información de pagos e incorporar a él cualquier tipo de complemento.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "TimbraCFDI API",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://pruebas.timbracfdi33.mx:1444/api/{version}",
      "description": "Servidor de pruebas DEV",
      "variables": {
        "version": {
          "default": "v2"
        }
      }
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/Timbrado/TimbraRetencion": {
      "post": {
        "tags": [
          "Timbrado de Retenciones"
        ],
        "summary": "Timbra Retención",
        "description": "A través de esta función podrás timbrar un comprobante de retenciones e información de pagos e incorporar a él cualquier tipo de complemento.",
        "operationId": "Timbrado_TimbraRetencion",
        "requestBody": {
          "x-name": "request",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TimbraRetencionRequest"
              },
              "examples": {
                "Timbrado de Retenciones": {
                  "summary": "Ejemplo de timbrado de un comprobante de retenciones",
                  "value": {
                    "XmlComprobanteBase64": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPHJldGVuY2lvbmVzOlJldGVuY2lvbmVzIHhtbG5zOnhzaT0iaHR0cDovL3d3dy53My5vcmcvMjAwMS9YTUxTY2hlbWEtaW5zdGFuY2UiIHhtbG5zOnJldGVuY2lvbmVzPSJodHRwOi8vd3d3LnNhdC5nb2IubXgvZXNxdWVtYXMvcmV0ZW5jaW9ucGFnby8yIiB4c2k6c2NoZW1hTG9jYXRpb249Imh0dHA6Ly93d3cuc2F0LmdvYi5teC9lc3F1ZW1hcy9yZXRlbmNpb25wYWdvLzIgaHR0cDovL3d3dy5zYXQuZ29iLm14L2VzcXVlbWFzL3JldGVuY2lvbnBhZ28vMi9yZXRlbmNpb25wYWdvdjIueHNkIiBWZXJzaW9uPSIyLjAiIEZvbGlvSW50PSIxMjMiIEZlY2hhRXhwPSIyMDIzLTExLTAxVDAxOjIyOjMxIiBMdWdhckV4cFJldGVuYz0iMjk5NjAiIEN2ZVJldGVuYz0iMDEiPgogIDxyZXRlbmNpb25lczpFbWlzb3IgUmZjRT0iSUlBMDQwODA1RFo0IiBOb21EZW5SYXpTb2NFPSJJTkRJU1RSSUEgSUxVTUlOQURPUkEgREUgQUxNQUNFTkVTIiBSZWdpbWVuRmlzY2FsRT0iNjAxIiAvPgogIDxyZXRlbmNpb25lczpSZWNlcHRvciBOYWNpb25hbGlkYWRSPSJOYWNpb25hbCI+CiAgICA8cmV0ZW5jaW9uZXM6TmFjaW9uYWwgUmZjUj0iRUtVOTAwMzE3M0M5IiBOb21EZW5SYXpTb2NSPSJFU0NVRUxBIEtFTVBFUiBVUkdBVEUiIERvbWljaWxpb0Zpc2NhbFI9IjI2MDE1IiAvPgogIDwvcmV0ZW5jaW9uZXM6UmVjZXB0b3I+CiAgPHJldGVuY2lvbmVzOlBlcmlvZG8gTWVzSW5pPSIwMSIgTWVzRmluPSIxMiIgRWplcmNpY2lvPSIyMDIxIiAvPgogIDxyZXRlbmNpb25lczpUb3RhbGVzIE1vbnRvVG90T3BlcmFjaW9uPSI1NTAwIiBNb250b1RvdEdyYXY9IjU1MDAiIE1vbnRvVG90RXhlbnQ9IjAiIE1vbnRvVG90UmV0PSIwIiAvPgo8L3JldGVuY2lvbmVzOlJldGVuY2lvbmVzPg==",
                    "IdComprobante": "12345"
                  }
                }
              }
            }
          },
          "x-position": 1
        },
        "responses": {
          "200": {
            "description": "Respuesta exitosa",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TimbraRetencionResponse"
                },
                "examples": {
                  "Respuesta con éxito": {
                    "summary": "Ejemplo de respuesta exitosa",
                    "value": {
                      "Codigo": "0",
                      "Mensaje": "Comando exitoso",
                      "Xml": "[Xml timbrado...]",
                      "CodigoQr": "[Código QR... (arreglo de bytes)]",
                      "CadenaOriginalTimbre": "||1.1|738f8bb0-18f4-4944-b870-02c3e790a197|2023-11-12T21:28:37|SPR190613I52|..."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Solicitud incorrecta (Bad Request)"
          },
          "401": {
            "description": "Sin Autorización (Authorization Exception)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnauthorizedErrorResponse"
                },
                "examples": {
                  "Respuesta con error": {
                    "summary": "Ejemplo de respuesta sin autorización",
                    "value": {
                      "Categoria": "Validación",
                      "Codigo": 21,
                      "CodigoSat": "21",
                      "Mensaje": "Token de integrador o contraseña incorrectos.",
                      "MensajeSat": "Token de integrador o contraseña incorrectos",
                      "Valores": {}
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Respuesta no exitosa",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TimbraRetencionErrorResponse"
                },
                "examples": {
                  "Respuesta con error": {
                    "summary": "Ejemplo de respuesta con errores",
                    "value": {
                      "Categoria": "FaultsTimbrado",
                      "Codigo": 20001,
                      "CodigoSat": "20001",
                      "Mensaje": "Error no controlado.",
                      "MensajeSat": "Error no controlado.",
                      "Valores": {}
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "UnauthorizedErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "Categoria": {
            "type": "string",
            "description": "Indica la categoría de la respuesta"
          },
          "Codigo": {
            "type": "integer",
            "format": "int32",
            "description": "Indica el código de error interno para efectos de soporte"
          },
          "CodigoSat": {
            "type": "string",
            "description": "Indica el código de error correspondiente a las validaciones establecidas por el SAT"
          },
          "Mensaje": {
            "type": "string",
            "description": "Indica el mensaje de error interno para efectos de soporte"
          },
          "MensajeSat": {
            "type": "string",
            "description": "Indica el mensaje de error correspondiente a las validaciones establecidas por el SAT"
          },
          "Valores": {
            "type": "object",
            "description": "En ocasiones contiene información adicional en caso de error. Las claves y valores son dinámicos",
            "additionalProperties": {
              "type": "string"
            },
            "nullable": true
          }
        }
      },
      "TimbraRetencionRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "XmlComprobanteBase64": {
            "type": "string",
            "description": "Xml del CFDI de retenciones codificado en Base64",
            "nullable": false
          },
          "IdComprobante": {
            "type": "string",
            "description": "Id interno del comprobante para efectos de soporte (Puede omitirse)",
            "nullable": false
          }
        },
        "required": [
          "XmlComprobanteBase64"
        ]
      },
      "TimbraRetencionResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "Codigo": {
            "type": "integer",
            "format": "int32",
            "description": "El código interno '0' indica siempre una petición exitosa"
          },
          "Mensaje": {
            "type": "string",
            "description": "Valor vacío (sólo aplica en caso de error)"
          },
          "Xml": {
            "type": "string",
            "description": "El CFDI timbrado, incluye complemento de timbre fiscal digital"
          },
          "CodigoQr": {
            "type": "string",
            "description": "La imagen del código QR para incorporar en la representación impresa (PDF) como un arreglo de bytes"
          },
          "CadenaOriginalTimbre": {
            "type": "string",
            "description": "La cadena original del complemento de certificación para incorporar en la respresentación impresa (PDF)"
          }
        }
      },
      "TimbraRetencionErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "Categoria": {
            "type": "string",
            "description": "Indica la categoría de la respuesta"
          },
          "Codigo": {
            "type": "integer",
            "format": "int32",
            "description": "Indica el código de error interno para efectos de soporte"
          },
          "CodigoSat": {
            "type": "string",
            "description": "Indica el código de error correspondiente a las validaciones establecidas por el SAT"
          },
          "Mensaje": {
            "type": "string",
            "description": "Indica el mensaje de error interno para efectos de soporte"
          },
          "MensajeSat": {
            "type": "string",
            "description": "Indica el mensaje de error correspondiente a las validaciones establecidas por el SAT"
          },
          "Valores": {
            "type": "object",
            "description": "En ocasiones contiene información adicional en caso de error. Las claves y valores son dinámicos",
            "additionalProperties": {
              "type": "string"
            },
            "nullable": true
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Utiliza tu Token de integrador para autorizarte en la API, para pruebas utiliza <b>mvpNUXmQfK8=</b>"
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true,
    "samples-enabled": true
  }
}
```