XSA - Manual del API

• Legales
• Introducción
• Manual de Usuario - API CFDIs y Retenciones
• Manual de Usuario - API CFDIs y Retenciones-Copia
• Endpoint Cancelación Acuse

Legales

Queda estrictamente prohibida la reproducción total o parcial de este documento, por cualquier medio y para cualquier fin, sin la autorización previa y por escrito de Tralix México, S. de R.L. de C.V.

Este documento y su contenido pueden incluir, entre otros, marcas registradas, nombres comerciales, logotipos, avisos comerciales, diseños industriales y demás elementos protegidos por las leyes de propiedad industrial e intelectual. Todos estos signos distintivos son propiedad exclusiva de Tralix México, S. de R.L. de C.V., y están legalmente protegidos.

El acceso, posesión o consulta de este documento no otorga, en ningún caso, licencia ni derecho alguno para usar, reproducir, distribuir, modificar o explotar, total o parcialmente, los elementos distintivos de Tralix México. Cualquier uso no autorizado constituirá una infracción a la normativa aplicable y podrá dar lugar al ejercicio de acciones legales.

Tralix México se reserva el derecho de modificar, sin previo aviso, las especificaciones, características o alcances de sus productos y servicios.

Copyright © 2025 Tralix México, S. de R.L. de C.V. Todos los derechos reservados.

Introducción

El Consorcio World Wide Web (W3C) es una comunidad internacional donde las organizaciones Miembro desarrollan estándares Webs, y han definido los Web Services como sistemas de software creados para soportar una interacción interoperable equipo a equipo sobre una red.

Los Web Services suelen ser APIs Web que pueden ser accedidos dentro de una red (principalmente Internet) y son ejecutados en el sistema donde residen. El estilo de arquitectura que hemos utilizado es el REST (Representational State Transfer), de tal manera que los servicios web deben cumplir con los siguientes principios:

• Un protocolo cliente/servidor sin estado: cada mensaje HTTP contiene toda la información necesaria para comprender la petición. Por lo que ni el cliente ni el servidor necesitan recordar ningún estado de las comunicaciones entre mensajes. Sin embargo, en la práctica, muchas aplicaciones basadas en HTTP utilizan cookies y otros mecanismos para mantener el estado de la sesión (algunas de estas prácticas, como la reescritura de URLs, no son permitidas por REST).
• Un conjunto de operaciones bien definidas que se aplican a todos los recursos de información: HTTP en sí define un conjunto pequeño de operaciones, las más importantes son POST, GET, PUT y DELETE. Con frecuencia estas operaciones se equiparan a las operaciones CRUD en bases de datos (ABMC: Alta, Baja, Modificación y Consulta) que se requieren para la persistencia de datos, aunque POST no encaja exactamente en este esquema.
• Una sintaxis universal para identificar los recursos. En un sistema REST, cada recurso es direccionable únicamente a través de su URI.
• El uso de hipermedios, tanto para la información de la aplicación como para las transiciones de estado de la aplicación: la representación de este estado en un sistema REST son típicamente HTML o XML. Como resultado de esto, es posible navegar de un recurso REST a muchos otros, simplemente siguiendo enlaces sin requerir el uso de registros u otra infraestructura adicional.

Cliente/Servidor 

Como servicios web, son cliente servidor y definen una interfaz de comunicación entre ellos, separando completamente las responsabilidades entre ambas partes.

Sin estado

Son servicios web que no mantienen estado asociado al cliente. Cada petición que se realiza a ellos es completamente independiente de la siguiente. Todas las llamadas al mismo servicio serán idénticas.

Caché

El contenido de los servicios web REST se puede cachear de tal forma que, una vez realizada la primera petición al servicio, el resto puedan apoyarse en el caché si fuera necesario.

Servicios Uniformes

Todos los servicios REST compartirán una forma de invocación y métodos uniforme utilizando los métodos GET, POST, PUT y DELETE.

Arquitectura en capas

Todos los servicios REST están orientados hacia la escalabilidad y un cliente REST no será capaz de distinguir entre si está realizando una petición directamente al servidor, o se lo está devolviendo un sistema de cachés intermedio; o, por ejemplo, existe un balanceador que se encarga de redirigirlo a otro servidor.

Manual de Usuario - API CFDIs y Retenciones

CFDI

Puerto asignado para los servicios: 9050

Consulta de tipos de CFDs

Consulta de sucursales

Consulta de CFDI

Consulta de CFDIs de nómina

Generación de CFDI

Descarga del CFDI

Descarga de nómina

Consulta del número de CFDIs generados

Consulta del número de CFDIs cancelados

Cancelación de CFDI múltiple

Cancelación de CFDI múltiple URL

Motivo de Cancelación

Códigos de Cancelación

Consulta de cancelación

Retenciones

Consulta tipos de retenciones

Consulta CFDI de retenciones

Descarga CFDI de retención

Descarga CFDI retenciones XML

Descarga CFDI retenciones PDF

Generación de retenciones

Cancelación de retenciones

Motivo de Cancelación

Consultar los CFDIs cancelados por rango de fechas

La consulta por fecha y rango de fecha solo aplica para los comprobantes cancelados posteriores a la versión 3.64, todo lo que se canceló con una versión anterior no podrá ser consultada.

Consultar los CFDIs cancelados indicando las fechas

Consultar los CFDI enviados

La consulta solo aplica para el servicio de Email Rastreable

Manual de Usuario - API CFDIs y Retenciones-Copia

1 Introducción

Este manual describe el uso de la API de Tralix para la consulta, generación, descarga y cancelación de CFDIs y CFDIs de Retenciones.

La documentación se encuentra organizada en dos secciones principales:

• CFDIs: servicios relacionados con la emisión, consulta, descarga y cancelación de CFDIs.
• Retenciones: servicios para la consulta, descarga, generación y cancelación de CFDIs de retenciones.

El objetivo de esta documentación es proporcionar a los desarrolladores y responsables técnicos una guía clara y estructurada para consumir los servicios de forma correcta, mostrando ejemplos prácticos, parámetros requeridos y códigos de respuesta esperados.

2 CFDIs

2.1 Consulta de tipos de CFDIs

2.1.1 Estructura general de la petición

El servicio se consume mediante una API REST, utilizando el método GET. Regresa el Id (encriptado), nombre, serie, idSucursal (encriptado), nómina (boleano) de todos los tipos de CFDs con los que cuenta la empresa en formato JSON.

2.1.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/tiposCfds

Autenticación y Headers

Parámetros

2.1.3 Ejemplo de petición

GET 
https://localhost:9050/985408d8-64ae-48e0-b46c-473b47176205/tiposCfds

2.1.4 Ejemplo de respuesta

Respuesta exitosa (código 200)

[
{"id":"d18bb0158356449c31e72cb69e642b31","nombre":"generacion","serie":null,"idSucursal":"6ac9a2c315480d5cc5534c7e58caee5a","nomina":false},
{"id":"8e327ff08a2eec8c760a91fbf08f636e","nombre":"nomina","serie":"B","idSucursal":"6ac9a2c315480d5cc5534c7e58caee5a","nomina":false}
]

2.1.5 Códigos de respuesta

2.1.6 Consideraciones Técnicas

• La consulta devuelve todos los tipos de CFDI disponibles para la empresa.

• El campo id y idSucursal son valores encriptados.

2.2 Consulta de Sucursales

2.2.1 Estructura general de la petición

El servicio se consume mediante una API REST, utilizando el método GET. Regresa el idSucursal, Nombre y TipoSucursal en formato json de todas las sucursales de la empresa.

2.2.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/sucursales

Autenticación y Headers

Parámetros

2.2.3 Ejemplo de petición

Respuesta exitosa (código 200)

GET 
https://localhost:9050/985408d8-64ae-48e0-b46c-473b47176205/sucursales

2.2.4 Ejemplo de respuesta

[
  {
    "idSucursal": "6ac9a2c315480d5cc5534c7e58caee5a",
    "nombre": "Actver Pruebas",
    "tipoSucursal": "MATRIZ"
  }
]

2.2.5 Códigos de respuesta

2.2.6 Consideraciones Técnicas

• El parámetro idSucursal siempre se devuelve encriptado.

• El parámetro Id es el idSucursal.

2.3 Consulta de CFDI

2.3.1 Estructura general de la petición

El servicio de Consulta de CFDI permite obtener información detallada de los comprobantes fiscales digitales (CFDI) emitidos por la empresa. El servicio se consume mediante el método GET y devuelve la información en formato JSON.

Donde:

• <keyEmpresa> es el identificador único (encriptado) de la empresa en el sistema Tralix.

• El consumo requiere al menos un filtro como parámetro (por ejemplo: uuid, fecha, rfc, etc.).

Regresa: idSucursal (Encriptado), rfc (del receptor), razonSocial (del receptor), fecha (YYYY-MM-DD hh:mm:ss.s), folio, status, UUID, monto (BigDecimal), idCfd (Encriptado), serie, subtotal (BigDecimal), descuento (BigDecimal), tipoMoneda, tipoCambio (BigDecimal), iva (BigDecimal), fechaCancelacion (YYYY-MM-DD hh:mm:ss.s), tienePDF (Boleano), pedimento, fechaPedimento (pueden venir varias fechas ), aduana, pdfAndXmlDownload (link para descargar XML y pdf), pdfDownload (link para descargar el pdf), xmlDownload (link para descargar el xml), cancellCfdi (link para cancelar el cfdi) en formato json de todas los CFDIs de la empresa (de no existir el filtros) excepto nóminas.

2.3.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/cfdis

Autenticación y Headers

Parámetros

Importante: Al menos uno de los siguientes parámetros debe incluirse en la petición.

2.3.3 Ejemplo de petición

Ejemplo 1 – Consulta por UUID

GET 
https://localhost:9050/985408d8-64ae-48e0-b46c-473b47176205/cfdis?uuid=9d8b7b0f-2aa6-47d7-8b45-d3abf26f57d1,c23a6470-9be2-4241-8cfa-fef55525c80f

Ejemplo 2 – Consulta por Fecha

GET 
https://localhost:9050/985408d8-64ae-48e0-b46c-473b47176205/cfdis?fecha=2014-06-30

2.3.4 Ejemplo de respuesta

Respuesta exitosa (Código 200)

[
  {
    "idCfdi": "66a673fbc55109153b7d684ed56b3b63",
    "serie": "",
    "subtotal": "99.090000",
    "descuento": "9999.009000",
    "tipoMoneda": "USD",
    "tipoCambio": "12.5014",
    "iva": "1000008.180000",
    "fechaCancelacion": "",
    "tienePDF": "true",
    "pedimento": "",
    "fechaPedimento": "",
    "aduana": "",
    "pdfAndXmlDownload": "/985408d8-64ae-48e0-b46c-473b47176205/descargasCfdi?idCfdi=66a673fbc55109153b7d684ed56b3b63&representacion=XML_PDF",
    "pdfDownload": "/985408d8-64ae-48e0-b46c-473b47176205/descargasCfdi?idCfdi=66a673fbc55109153b7d684ed56b3b63&representacion=PDF",
    "xmlDownload": "/985408d8-64ae-48e0-b46c-473b47176205/descargasCfdi?idCfdi=66a673fbc55109153b7d684ed56b3b63&representacion=XML"
  }
]

2.3.5 Códigos de respuesta

2.3.6 Consideraciones Técnicas

• Es obligatorio incluir al menos un filtro en la consulta.

• El formato de fecha no acepta horas (yyyy-MM-dd).

• El valor por defecto de pageSize es 50 y el máximo permitido es 100.

• En los headers de la respuesta se incluyen los links de paginación (siguiente serie de resultados).

• Es posible combinar los parámetros para realizar filtrados más detallados.

• No se incluyen CFDI de tipo nómina en los resultados.

• Los enlaces pdfDownload, xmlDownload y pdfAndXmlDownload permiten descargar los archivos asociados al CFDI.

• El parámetro uuid admite múltiples valores separados por comas.

• El campo idSucursal y idCfdi se devuelven en formato encriptado para seguridad de datos.

2.4 Consulta de CFDIs de Nómina

2.4.1 Estructura general de la petición

El servicio Consulta de CFDIs de Nómina permite obtener la información de los comprobantes fiscales digitales por internet (CFDI) relacionados con nómina emitidos por una empresa. Este servicio devuelve los datos de los CFDIs de nómina en formato JSON, permitiendo aplicar filtros para realizar búsquedas específicas según parámetros como fechas, RFC, estatus, montos o UUID. La consulta se realiza mediante una API REST utilizando el método GET.

Donde:

• <keyEmpresa> Llave encriptada que identifica la empresa en el sistema.

El servicio devuelve un listado de CFDIs de nómina registrados en el sistema, o bien un subconjunto filtrado de acuerdo con los parámetros de búsqueda aplicados.

Regresa: idSucursal (Encriptado), rfc (del receptor), razonSocial (del receptor), fecha (YYYY-MM-DD hh:mm:ss.s) , folio, status, UUID, monto (BigDecimal), idCfd (Encriptado), serie, subtotal (BigDecimal), descuento (BigDecimal), tipoMoneda, tipoCambio (BigDecimal), iva (BigDecimal), fechaCancelacion (YYYY-MM-DD hh:mm:ss.s), tienePDF (Boleano), pedimento, fechaPedimento (pueden venir vairias fechas ), aduana, pdfAndXmlDownload (link para descargar XML y pdf), pdfDownload (link para descargar el pdf), xmlDownload (link para descargar el xml), cancellCfdi (link para cancelar el cfdi) en formato json de todas las nóminas de la empresa (de no existir el filtros).

2.4.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/cfdisNomina

Autenticación y Headers

Parámetros

2.4.3 Ejemplo de petición

Ejemplo 1 – Consulta por UUID

GET 
https://localhost:9050/985408d8-64ae-48e0-b46c-473b47176205/cfdisNomina?uuid=97c05608-58aa-4087-886d-82a69a86bc98

Ejemplo 2 – Consulta por Fecha

GET 
https://localhost:9050/985408d8-64ae-48e0-b46c-473b47176205/cfdisNomina?fecha=2014-06-18

2.4.4 Ejemplo de respuesta

Respuesta exitosa (código 200)

[
  {
    "idCfdi": "66a673fbc55109153b7d684ed56b3b63",
    "serie": "",
    "subtotal": "99.090000",
    "descuento": "9999.009000",
    "tipoMoneda": "USD",
    "tipoCambio": "12.5014",
    "iva": "1000008.180000",
    "fechaCancelacion": "",
    "tienePDF": "true",
    "pedimento": "",
    "fechaPedimento": "",
    "aduana": "",
    "pdfAndXmlDownload": "/985408d8-64ae-48e0-b46c-473b47176205/descargasCfdi?idCfdi=66a673fbc55109153b7d684ed56b3b63&representacion=XML_PDF",
    "pdfDownload": "/985408d8-64ae-48e0-b46c-473b47176205/descargasCfdi?idCfdi=66a673fbc55109153b7d684ed56b3b63&representacion=PDF",
    "xmlDownload": "/985408d8-64ae-48e0-b46c-473b47176205/descargasCfdi?idCfdi=66a673fbc55109153b7d684ed56b3b63&representacion=XML"
  }
]

2.4.5 Códigos de respuesta

2.4.6 Consideraciones Técnicas

• El formato de fecha debe ser yyyy-MM-dd. No se admiten horas.

• El parámetro pageSize tiene un valor predeterminado de 50 y un máximo de 100.

• En los headers de la respuesta se incluirán los links de paginación cuando los resultados excedan el máximo permitido.

• El servicio devuelve los CFDIs en formato JSON.

• Es posible combinar varios filtros para realizar búsquedas más específicas.

• Si se envían múltiples UUIDs, deben separarse con comas (,).

• El endpoint no requiere cuerpo (body) en la petición; todos los parámetros se envían en la URL.

2.5. Generación de CFDI

2.5.1 Estructura general de la petición

El servicio Generación de CFDI permite emitir Comprobantes Fiscales Digitales por Internet (CFDI) a través de una petición HTTP PUT. La información del comprobante debe enviarse en formato JSON dentro del cuerpo de la solicitud (Request Payload), conteniendo la estructura y datos definidos según el conector o adaptador configurado en la cuenta del cliente.

La petición genera y devuelve un objeto JSON con la información fiscal del CFDI emitido, incluyendo folio, UUID, montos, y enlaces para descarga de XML y PDF.

Regresa: idSucursal (Encriptado), rfc (del receptor), razonSocial (del receptor), fecha (YYYY-MM-DD hh:mm:ss.s) , folio, status, UUID, monto (BigDecimal), idCfd (Encriptado), serie, subtotal (BigDecimal), descuento (BigDecimal), tipoMoneda, tipoCambio (BigDecimal), iva (BigDecimal), fechaCancelacion (YYYY-MM-DD hh:mm:ss.s), tienePDF (Boleano), pedimento, fechaPedimento (pueden venir vairias fechas ), aduana, pdfAndXmlDownload (link para descargar XML y pdf), pdfDownload (link para descargar el pdf), xmlDownload (link para descargar el xml), cancellCfdi (link para cancelar el cfdi) en formato json del CFDI generado.

2.5.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/cfdis

Autenticación y Headers

Nota: Es indispensable incluir el salto de línea entre registros utilizando\n.
Ejemplo: |00|idcfd|FAC|\n

Parámetros

2.5.3 Ejemplo de petición

URL

PUT 
https://localhost:9050/985408d8-64ae-48e0-b46c-473b47176205/cfdis

Request

{
  "idTipoCfd": "d18bb0158356449c31e72cb69e642b31",
  "idSucursal": "6ac9a2c315480d5cc5534c7e58caee5a",
  "nombre": "prueba.txt",
  "archivoFuente": "|00|idcfd|FAC|\n01|1|||20140630T00:00:00|99.09|9999.09|||9999.009||Noventa y nueve billones novecientos noventa y nueve mil novecientos noventa y nueve millones novecientos noventa y nueve mil novecientos noventa y nueve 90\/10000000|USD|12.5014|REFERENCIA XXXAAAXXX|Primera Observación|Segunda Observación|Tercera Observación|\n02|PAGO EN UNA SOLA EXHIBICIÓN|10% DE INTERÉS SI NO SE PAGA ANTES DEL 05-AGOSTO-2010|CHEQUE|2010-08-05|EFECTOS FISCALES AL PAGO|\n03|01|AAA010101AAA|PATITO, S.A. DE C.V.|MÉXICO|AVENIDA CALLE |S\/N|INT. 1|COL. COLONIA|MÉXICO|REFERENCIA FRENTE AL OXXO|CUAJIMALPA|ESTADO DE MÉXICO|06860|4424876399|\n05|405010|802011|3|BOMBA MOLOTOV|150.00|450.00|PZA|Categoría 5e|205010|\n05|405011|802012|1|DISFRAZ DE CORRECAMINOS|2368231872779.000009|884346835174.000009|PZA|Categoría 5e|205011|\n05|405012|802013|10|COMIDA DE CORRECAMINOS|39.00|390.00|KG|Categoría 5e|205010|\n05|405013|802014|1|LIGA DE HULE GIGANTE|378.00|378.00|PZA|Categoría 5e|205011|\n06|IVA|16.00|9.09|\n07|IVA|58.58|\n06|IVA|16.00|999999.09|\n07|IVA|58.58|\n08|405010|APTO INTL DE CIUDAD DE MEXICO|2010-06-29|548984124578124||\n08|405011|APTO INTL DE CIUDAD DE MEXICO|2010-06-29|654651456987452||\n99|15||"
}

2.5.4 Ejemplo de respuesta

Respuesta exitosa (código 200)

{
  "uuid": "3D5DAEF4-FE52-44A5-9C82-84B6B293EC7E",
  "fecha": "2020-05-23 17:09:00.0",
  "serie": "D01",
  "folio": "1000",
  "rfc": "OIAD8404189S3",
  "iva": "134.390000",
  "monto": "974.390000",
  "descuento": "0.000000",
  "subtotal": "840.000000",
  "tipoCambio": "1.0000",
  "tipoMoneda": "MXN",
  "idCfd": "60014b09e2d75d1ac1260b7c4e780c00",
  "idSucursal": "0dd6aebbea85662fd2fe2f76ce4258b3",
  "status": "ALMACENADO",
  "produccion": true,
  "fechaCancelacion": "",
  "tienePDF": true,
  "pedimento": "",
  "fechaPedimento": "",
  "aduana": "",
  "pdfAndXmlDownload": "/03317bd7-c60d-434f-958d-65344238e75f/descargasCfdi?idCfdi=60014b09e2d75d1ac1260b7c4e780c00&produccion=true&representacion=XML_PDF",
  "pdfDownload": "/03317bd7-c60d-434f-958d-65344238e75f/descargasCfdi?idCfdi=60014b09e2d75d1ac1260b7c4e780c00&produccion=true&representacion=PDF",
  "xmlDownload": "/03317bd7-c60d-434f-958d-65344238e75f/descargasCfdi?idCfdi=60014b09e2d75d1ac1260b7c4e780c00&produccion=true&representacion=XML"
}

2.5.5 Códigos de respuesta

Nota: Si ocurre un error en el proceso de generación, el sistema devolverá un mensaje JSON con la descripción del problema.

2.5.6 Consideraciones Técnicas

• El contenido del CFDI debe enviarse en formato JSON dentro del Request Payload.

• Es obligatorio utilizar el encabezado:

  Content-Type: application/json

• El campo archivoFuente debe respetar la estructura y delimitadores configurados para el conector o adaptador de la empresa.

• Se recomienda validar previamente que los valores encriptados (idTipoCfd, idSucursal) sean correctos.

• Si el CFDI se genera correctamente, el servicio devuelve:

  • Datos fiscales (UUID, serie, folio, montos, etc.)

  • Ligas para descarga de XML y PDF.

• En caso de error, se devuelve un objeto JSON con los mensajes de error específicos del proceso.

2.6 Descarga del CFDI

2.6.1 Estructura general de la petición

El servicio Descarga del CFDI permite obtener los comprobantes fiscales digitales (CFDI) en formato XML, PDF o ambos, según la representación requerida. Puede realizarse una descarga individual o múltiple de documentos mediante filtros específicos, incluyendo RFC, fechas, serie, folios o UUIDs. El servicio devuelve los archivos solicitados dentro de un archivo ZIP, cuando se incluyen varios documentos o representaciones combinadas.

Donde:

• <keyEmpresa> Llave encriptada que identifica la empresa en el sistema.

• Los parámetros opcionales permiten filtrar la búsqueda de CFDIs según las necesidades del usuario.

2.6.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/descargasCfdi

Autenticación y Headers

Parámetros

Importante: Al menos uno de los siguientes parámetros debe incluirse en la petición.

2.6.3 Ejemplo de petición

Ejemplo 1: Descargar un CFDI en formato XML.

GET 
https://10.0.0.183:9050/985408d8-64ae-48e0-b46c-473b47176205/descargasCfdi?representacion=XML&pageSize=1

Ejemplo 2: Descargar varios CFDIs por UUID.

GET 
https://localhost:9050/985408d8-64ae-48e0-b46c-473b47176205/descargasCfdi?uuid=9d8b7b0f-2aa6-47d7-8b45-d3abf26f57d1,dabcea47-2e61-4cdb-b71e-e43c0d108ae3

2.6.4 Ejemplo de respuesta

Ejemplo 1 – Respuesta exitosa (código 200)
La respuesta devuelve un archivo XML descargable.
Se descargará un archivo de tipo XML (este servicio no aplica para CFDI de tipo Nómina).

Ejemplo 2 – Respuesta exitosa (código 200)
La respuesta devuelve un archivo ZIP con los CFDI solicitados.
Se descargará un archivo ZIP que contiene los archivos XML y PDF correspondientes a los UUIDs indicados en la URL.

2.6.5 Códigos de respuesta

2.6.6 Consideraciones técnicas

1. Parámetros mínimos: Es obligatorio incluir al menos un filtro (RFC, fecha, folio o UUID).

2. Tipo de archivo:

   • Si se solicita solo un CFDI, se devuelve un ZIP con un archivo XML o PDF, según el parámetro representacion.

   • Si se solicita XML y PDF o varios documentos se devolverá un archivo tipo ZIP.

   • Si no se incluye el parámetro representacion se devolverá XML y PDF dentro de un zip.

3. Rendimiento:

   • El parámetro pageSize define la cantidad de resultados por página. El valor por defecto es 50 registros y el máximo permitido es 100.

   • Considerar el tiempo de construcción de archivos PDF (aproximadamente 600 PDF por minuto).

4. Paginación:

   • Si la cantidad de resultados excede el límite de 50, en los headers de la respuesta se incluirán los link para acceder a las siguientes páginas de resultados.

5. Filtros combinados:

   • Es posible combinar múltiples parámetros para realizar consultas más específicas.

2.7 Descarga de Nómina

2.7.1 Estructura general de la petición

El servicio Descarga de CFDI Nómina permite obtener los comprobantes fiscales digitales correspondientes a los recibos de nómina emitidos. El servicio puede devolver los archivos en formato XML, PDF o ambos (XML_PDF), según los parámetros establecidos en la solicitud. Este servicio se consume mediante una API REST con método GET, y su respuesta puede incluir uno o varios archivos según el criterio de búsqueda.

Donde:

• <keyEmpresa> Llave encriptada que identifica la empresa en el sistema.

• El servicio admite múltiples filtros opcionales que determinan los documentos a descargar.

2.7.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/descargasCfdiNominas

Autenticación y Headers

Parámetros

Importante: Al menos uno de los siguientes parámetros debe incluirse en la petición.

2.7.3 Ejemplo de petición

Ejemplo 1. Solicitud de XML (único registro)

GET 
https://10.0.0.183:9050/985408d8-64ae-48e0-b46c-473b47176205/descargasCfdiNominas?representacion=XML&pageSize=1

Ejemplo 2. Descarga por UUID

GET 
https://localhost:9050/985408d8-64ae-48e0-b46c-473b47176205/descargasCfdiNominas?uuid=97c05608-58aa-4087-886d-82a69a86bc98

2.7.4 Ejemplo de respuesta

Ejemplo 1 – Respuesta exitosa (código 200)
Se descarga un archivo de tipo XML, correspondiente a un CFDI de nómina.

Ejemplo 2 – Respuesta exitosa (código 200)
Se descarga un archivo ZIP que contiene los archivos XML y PDF del CFDI correspondiente al UUID indicado en la URL.

2.7.5 Códigos de respuesta

2.7.6 Consideraciones técnicas

1. Parámetros mínimos: Es obligatorio incluir al menos un filtro (RFC, fecha, folio o UUID).

2. Tipo de archivo:

   • Si se solicita XML y PDF o varios documentos se devolverá un archivo tipo ZIP.
   • Si se solicita solo un CFDI, dependiendo del parámetro de representación se devolverá UN archivo XML o PDF.
   • Si no se incluye el parámetro se devolverá XML y PDF.

3. Rendimiento:

   • El parámetro pageSize define la cantidad de resultados por página. El valor por defecto es 50 registros y el máximo permitido es 100.

   • Considerar el tiempo de construcción de archivos PDF (aproximadamente 600 PDF por minuto).

4. Paginación:

   • Si la cantidad de resultados excede el límite de 50, en los headers de la respuesta se incluirán los link para acceder a las siguientes páginas de resultados.

5. Filtros combinados:

   • Es posible combinar múltiples parámetros para realizar consultas más específicas.

   • Si se desea descargar solo el PDF poner "xml=false" en los parámetros.

   • Si se desea descargar solo el XML poner "pdf=false" en los parámetros.

2.8 Consulta del número de CFDIs generados

2.8.1 Estructura general de la petición

El servicio Consulta del número de CFDIs generados permite obtener la cantidad total de CFDIs emitidos por una empresa dentro de una fecha específica o en un rango determinado.

El servicio se consume mediante una petición HTTP GET, devolviendo como respuesta un valor numérico que representa el total de comprobantes generados en el periodo solicitado.

Es obligatorio enviar al menos una fecha (fecha) o un rango de fechas (fechaInicial, fechaFinal).

2.8.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/cfdis/consumo/generacion

Autenticación y Headers

Parámetros

Nota: Forzosamente debe de haber una fecha específica (fecha) o un rango de fechas (fechaInicial, fechaFinal).

2.8.3 Ejemplo de petición

Ejemplo 1. Por fecha específica

GET 
https://10.0.0.183:9050/985408d8-64ae-48e0-b46c-473b47176205/cfdis/consumo/generacion?fecha=2014-07-02

Ejemplo 2. Por rango de fechas

GET 
https://10.0.0.183:9050/985408d8-64ae-48e0-b46c-473b47176205/cfdis/consumo/generacion?fechaInicial=2014-07-01&fechaFinal=2014-07-03

2.8.4 Ejemplo de respuesta

Respuesta exitosa (código 200)

3525 (la respuesta es numérica)

Nota: El valor devuelto representa el número total de CFDIs generados en el periodo indicado. En este ejemplo, el sistema registró 3,525 comprobantes.

2.8.5 Códigos de respuesta

2.8.6 Consideraciones técnicas

• Es obligatorio enviar una fecha específica o un rango de fechas.

• El formato de las fechas debe ser yyyy-MM-dd.

• La respuesta siempre será un valor numérico.

• Este servicio solo consulta CFDIs emitidos por la empresa identificada en la keyEmpresa.

2.9 Consulta del número de CFDIs cancelados

2.9.1 Estructura general de la petición

El servicio Consulta del número de CFDIs cancelados permite obtener la cantidad total de CFDIs que han sido cancelados por una empresa dentro de una fecha específica o en un rango determinado.

La consulta se realiza mediante una petición HTTP GET y devuelve como respuesta un valor numérico que representa el total de comprobantes fiscales cancelados en el periodo indicado.

Es obligatorio proporcionar una fecha específica (fecha) o un rango de fechas (fechaInicial, fechaFinal) para ejecutar la solicitud correctamente.

2.9.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/cfdis/consumo/cancelacion

Autenticación y Headers

Parámetros

Nota: Debe enviarse una sola fecha (fecha) o un rango de fechas (fechaInicial, fechaFinal), nunca ambos en la misma petición.

2.9.3 Ejemplo de petición

Ejemplo 1. Por fecha específica

GET 
https://10.0.0.183:9050/985408d8-64ae-48e0-b46c-473b47176205/cfdis/consumo/cancelacion?fecha=2014-07-02

Ejemplo 2. Por rango de fechas

GET 
https://10.0.0.183:9050/985408d8-64ae-48e0-b46c-473b47176205/cfdis/consumo/cancelacion?fechaInicial=2013-04-01&fechaFinal=2014-01-01

2.9.4 Ejemplo de respuesta

Respuesta exitosa (código 200)

0 (la respuesta es numérica)

Nota: El valor numérico indica la cantidad total de CFDIs cancelados durante el periodo indicado.
En este ejemplo, la respuesta 0 indica que no se registraron cancelaciones dentro del rango solicitado.

2.9.5 Códigos de respuesta

2.9.6 Consideraciones técnicas

• Es obligatorio incluir una fecha o un rango de fechas.

• Las fechas deben enviarse en formato yyyy-MM-dd.

• La respuesta será siempre un valor numérico entero.

• Si no se encuentran CFDIs cancelados en el periodo indicado, el sistema devuelve 0.

• Este servicio solo aplica para los CFDIs emitidos por la empresa identificada en la keyEmpresa.

2.10 Cancelación de CFDI múltiple

2.10.1 Estructura general de la petición

El servicio Cancelación de CFDI múltiple permite cancelar uno o varios comprobantes fiscales digitales (CFDI) en una sola solicitud. La petición debe enviarse mediante el método HTTP POST, incluyendo en el cuerpo de la solicitud (body) un JSON con los UUIDs de los CFDIs a cancelar, así como el motivo de cancelación.

Para los motivos de cancelación distintos de “01”, es posible incluir múltiples UUIDs en la misma petición.
En el caso de motivo “01”, se requiere además el UUID del CFDI sustituto que reemplazará al cancelado.

La respuesta se entrega en formato JSON, indicando para cada CFDI su UUID, el código de estado y la descripción correspondiente.

2.10.2 Parámetros requeridos

Endpoint

Autenticación y Headers

Parámetros

Nota:
- Cuando el motivo = 01, solo puede cancelarse un CFDI por solicitud.
- Cuando el motivo = 02, 03 o 04, pueden incluirse múltiples UUIDs (cancelación masiva).

2.10.3 Ejemplo de petición

Petición para motivo 01 (requiere folio de sustitución)

POST https://10.0.0.183:9050/985408d8-64ae-48e0-b46c-473b47176205/cfdis/cancelar?

Content-Type: application/json

{
  "motivo": "01",
  "folioSustitucion": "B5E6897B-40A7-4DEA-ADD2-F417B32EE908",
  "uuid": [
    "B5E6897B-40A7-4DEA-ADD2-F417B32EE909"
  ]
}

Petición para motivo 02, 03 o 04 (múltiples UUIDs)

POST https://10.0.0.183:9050/985408d8-64ae-48e0-b46c-473b47176205/cfdis/cancelar?

Content-Type: application/json

{
  "motivo": "02",
  "uuid": [
    "B5E6897B-40A7-4DEA-ADD2-F417B32EE909",
    "B5E6897B-40A7-4DEA-ADD2-F417B32EE909"
  ]
}

2.10.4 Ejemplo de respuesta

Respuesta (código 200):

[
  {
    "uuid": "A07F61BD-4E1D-E504-9F3F-902DA4D622B3",
    "status": "201",
    "descripcion": "UUID Cancelado"
  },
  {
    "uuid": "d5cdbe22-b117-4ca7-bfbb-ddef8e22b0f4",
    "status": "201",
    "descripcion": "UUID Cancelado"
  }
]

Nota:
El sistema devuelve un arreglo JSON donde cada elemento representa un CFDI procesado, mostrando su UUID, status numérico y una descripción textual del resultado.

2.10.5 Códigos de respuesta

2.10.6 Consideraciones técnicas

• El cuerpo de la solicitud debe enviarse en formato JSON.

• Para el motivo “01”, el campo folioSustitucion es obligatorio.

• Para los motivos “02”, “03” o “04”, no se incluye folioSustitucion y se pueden procesar varios UUIDs.

• Los UUIDs enviados deben existir y estar asociados a la empresa identificada por keyEmpresa.

2.11 Cancelación de CFDI múltiple URL

2.11.1 Estructura general de la petición

El servicio Cancelación de CFDI múltiple URL permite cancelar uno o varios comprobantes fiscales digitales (CFDI) en una sola operación y obtener, además, las ligas de descarga del acuse de cancelación en formato XML y PDF para cada CFDI procesado.

La petición se realiza mediante el método HTTP POST, enviando los datos en formato JSON.
Dependiendo del motivo de cancelación, se puede incluir uno o varios UUIDs dentro del cuerpo de la solicitud.

• Si el motivo es “01”, debe incluirse un folio de sustitución.

• Si el motivo es “02”, “03” o “04”, se pueden incluir múltiples UUIDs en la misma petición.

2.11.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/cfdis/cancelarUrl

Autenticación y Headers

Parámetros

Notas:
- El cuerpo de la solicitud debe enviarse en formato JSON.
- Cuando el motivo = 01, solo puede cancelarse un CFDI por solicitud.
- Cuando el motivo = 02, 03 o 04, pueden incluirse múltiples UUIDs (cancelación masiva).

2.11.3 Ejemplo de petición

Petición para motivo 01 (requiere folio de sustitución):

POST https://10.0.0.183:9050/985408d8-64ae-48e0-b46c-473b47176205/cfdis/cancelarUrl?

Content-Type: application/json

{
  "motivo": "01",
  "folioSustitucion": "B5E6897B-40A7-4DEA-ADD2-F417B32EE908",
  "uuid": [
    "B5E6897B-40A7-4DEA-ADD2-F417B32EE909"
  ]
}

Petición para motivo 02, 03 o 04 (múltiples UUIDs):

POST https://10.0.0.183:9050/985408d8-64ae-48e0-b46c-473b47176205/cfdis/cancelarUrl?

Content-Type: application/json

{
  "motivo": "02",
  "uuid": [
    "B5E6897B-40A7-4DEA-ADD2-F417B32EE909",
    "B5E6897B-40A7-4DEA-ADD2-F417B32EE909"
  ]
}

2.11.4 Ejemplo de respuesta

Respuesta (código 200):

[
  {
    "uuid": "A07F61BD-4E1D-E504-9F3F-902DA4D622B3",
    "status": "201",
    "descripcion": "UUID Cancelado",
    "URLAcuse_XML":"/985408d8-64ae-48e0-b46c-473b47176205/descargasCfdi?idCfdi=66a673fbc55109153b7d684ed56b3b63&representacion=ACUSE",
    "URLAcuse_PDF":"/985408d8-64ae-48e0-b46c-473b47176205/descargasCfdi?idCfdi=66a673fbc55109153b7d684ed56b3b63&representacion=ACUSE_PDF"
  }
]

Descripción:
El sistema devuelve un arreglo JSON donde cada elemento representa un CFDI procesado. Para cada registro se incluyen los siguientes datos:

• uuid: identificador único del CFDI cancelado.

• status: código numérico del resultado.

• descripcion: texto descriptivo del estado del CFDI.

• URLAcuse_XML: liga directa para descargar el acuse de cancelación en formato XML.

• URLAcuse_PDF: liga directa para descargar el acuse de cancelación en formato PDF.

2.11.5 Códigos de respuesta

2.11.6 Consideraciones técnicas

• Es obligatorio incluir el encabezado Content-Type: application/json.

• Para el motivo “01”, se debe incluir el campo folioSustitucion.

• Las URLs proporcionadas permiten descargar el acuse de cancelación en los formatos XML y PDF.

• Las ligas de descarga son válidas únicamente para la empresa (keyEmpresa) propietaria del CFDI.

Motivo de Cancelación

Códigos de Cancelación

2.12 Consulta de Cancelación

2.12.1 Estructura general de la petición

El servicio Consulta de Cancelación permite consultar el estatus actual de cancelación de un CFDI específico, identificándolo por su UUID. La petición se realiza mediante el método HTTP POST, enviando el parámetro uuid dentro del cuerpo en formato JSON.

El servicio devuelve el UUID solicitado junto con su estado de cancelación, según la información registrada en el SAT.

2.12.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/cfdis/consultaCancelacion

Autenticación y Headers

Parámetros

2.12.3 Ejemplo de petición

POST https://localhost:9050/6df9515e-6c7d-46fc-a2a8-86080ce9ba2f/cfdis/consultaCancelacion?

Content-Type: application/json

{
  "uuid": [
    "3BC513EC-FD2A-4B66-AAB2-4C46BC976C7A"
  ]
}

2.12.4 Ejemplo de respuesta

Respuesta (código 200):

[
  {
    "uuid": "3BC513EC-FD2A-4B66-AAB2-4C46BC976C7A",
    "status": "CANCELABLE_SIN_ACEPTACION"
  }
]

Descripción:
La respuesta se devuelve en formato JSON y contiene los siguientes campos:

• uuid: identificador único del CFDI consultado.

• status: estado actual del CFDI en el proceso de cancelación.

2.12.5 Códigos de respuesta

2.12.6 Estados posibles del CFDI

El campo status puede devolver uno de los siguientes valores según la situación del CFDI:

2.12.7 Consideraciones técnicas

• El cuerpo de la solicitud debe enviarse en formato JSON con el campo uuid como arreglo.

• Solo se puede consultar un CFDI por solicitud.

• La respuesta del servicio depende del estatus registrado en el SAT al momento de la consulta.

• Se recomienda almacenar los resultados para seguimiento y trazabilidad de cancelaciones.

3 Retenciones

3.1 Consulta de Tipos de Retenciones

3.1.1 Estructura general de la petición

El servicio Consulta de Tipos de Retenciones permite obtener el listado de los tipos de CFDI de retención registrados para una empresa específica. A través de este servicio, el usuario puede conocer el identificador (id) del tipo de retención, su nombre y el ID de la sucursal asociada.

Este servicio está disponible mediante una llamada HTTP GET y devuelve la información en formato JSON.

Donde:

• <keyEmpresa> Llave encriptada que identifica la empresa en el sistema.

3.1.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/tiposCfdsRetenciones

Autenticación y Headers

Parámetros

3.1.3 Ejemplo de petición

GET 
https://10.0.0.183:9050/985408d8-64ae-48e0-b46c-473b47176205/tiposCfdsRetenciones

3.1.4 Ejemplo de respuesta

Respuesta exitosa (código 200):

[
  {
    "idTipoCfdRetencion": "51bcbd36d5f0cbf971e3cbb0bea7567a",
    "nombre": "Retencion",
    "idSucursal": "2575797c4c7933f6f067e054240fc48b",
    "produccion": true
  }
]

3.1.5 Códigos de respuesta

3.1.6 Consideraciones técnicas

• El parámetro keyEmpresa es obligatorio y válido.

• Los parámetros pageSize y pageNumber permiten implementar paginación en la consulta.

• La respuesta se entrega en formato JSON.

• En caso de no existir información, el servicio devuelve el código 204 (No Content).

• Este servicio es de solo lectura y no modifica información en el sistema.

3.2 Consulta CFDI de Retenciones

3.2.1 Estructura general de la petición

Este servicio permite consultar los CFDI de Retenciones emitidos por una empresa determinada, aplicando diferentes filtros de búsqueda. La respuesta del servicio devuelve información detallada sobre los comprobantes, incluyendo su estatus, monto, fecha de emisión, UUID y ligas de descarga en formatos XML y PDF.

Regresa el id del cfdi de retención, el id de la sucursal de a retención, el RFC del receptor, la razón social del receptor, la fecha de emisión del documento, el status del documento, el uuid del documento, el monto, la fecha de cancelacion del documentos (si está cancelado), la liga de descarga del documento en sus versiones XML y PDF, liga de descarga del documento en formato XML, liga de descarga del documento en PDF, la liga con la que se podría cancelar el documento.

El servicio se consume mediante una petición HTTP GET, indicando la clave de empresa (keyEmpresa) en la ruta del endpoint, junto con los parámetros de filtro opcionales.

3.2.2 Parámetros requeridos

Endpoint

Autenticación y Headers

Parámetros

Importante: Al menos uno de los siguientes parámetros debe incluirse en la petición.

3.2.3 Ejemplo de petición

GET 
https://localhost:9050/6df9515e-6c7d-46fc-a2a8-86080ce9ba2f/ cfdisretencion?pageSize=50&pageNumber=1&rfcReceptor=MURR750516812

3.2.4 Ejemplo de respuesta

Respuesta exitosa (código 200):

[
  {
    "idCfdiRetencion": "1dccc6e57b1d443c3e1a1ffd5095f382",
    "idSucursal": "6ac9a2c315480d5cc5534c7e58caee5a",
    "rfcReceptor": "MURR750516812",
    "razonSocial": "Razón Social Nacional",
    "fecha": "2015-01-24T01:18:22",
    "status": "CANCELADO",
    "uuid": "2310EABB-5F39-4694-8FBD-1EA0842C8113",
    "monto": "3252.500000",
    "fechaCancelacion": "",
    "pdfAndXmlDownload": "/985408d8-64ae-48e0-b46c-473b47176205/cfdisretencion/descarga?uuid=2310EABB-5F39-4694-8FBD-1EA0842C8113&representacion=XML_PDF",
    "pdfDownload": "/985408d8-64ae-48e0-b46c-473b47176205/cfdisretencion/descarga/pdf?uuid=3bf7942709f6eb925d26dae62c63f8c287b8868661bc4a69ce1e3c2e10ff98bd6486140ef80ba7ac7867620b4fc94fed",
    "xmlDownload": "/985408d8-64ae-48e0-b46c-473b47176205/cfdisretencion/descarga/xml?uuid=3bf7942709f6eb925d26dae62c63f8c287b8868661bc4a69ce1e3c2e10ff98bd6486140ef80ba7ac7867620b4fc94fed"
  }
]

3.2.5 Códigos de respuesta

3.2.6 Consideraciones técnicas

• Se debe incluir al menos un filtro en la consulta; el endpoint no acepta solicitudes vacías.

• El formato de fecha debe ser consistente (yyyy-MM-dd o yyyy-MM-dd h:mm:ss).

• Los campos pageSize y pageNumber permiten paginar los resultados para optimizar el rendimiento.

• El servicio devuelve enlaces directos para descargar el comprobante en sus versiones XML y PDF.

• En caso de CFDIs cancelados, el campo fechaCancelacion mostrará la fecha correspondiente; si está vacío, indica que la cancelación no ha sido procesada.

• Los UUID y idSucursal se devuelven en formato encriptado para garantizar la seguridad de los datos.

3.3 Descarga CFDI de Retención

3.3.1 Estructura general de la petición

Este servicio permite descargar los CFDI de Retención previamente consultados, empaquetados en un archivo ZIP. Cada archivo comprimido contiene los documentos resultantes de la consulta, en formato XML, PDF, o en ambos, dependiendo del parámetro indicado en la solicitud.

El servicio se consume mediante una petición HTTP GET, especificando la clave de empresa (keyEmpresa) y los filtros de búsqueda. Si no se indica el tipo de representación, el servicio tomará XML como valor predeterminado.

3.3.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/cfdisretencion/descarga?

Autenticación y Headers

Parámetros

Importante: Al menos uno de los siguientes parámetros debe incluirse en la petición.

3.3.3 Ejemplo de petición

GET 
https://localhost:9050/6df9515e-6c7d-46fc-a2a8-86080ce9ba2f/ cfdisretencion/descarga?pageSize=50&pageNumber=1&rfcReceptor=AAA010101AAA

3.3.4 Ejemplo de respuesta

Respuesta exitosa (código 200):

Content-Type: application/zip
Content-Disposition: attachment; filename="1441221373984.zip"

El servicio devuelve un archivo ZIP que contiene los CFDI resultantes de la consulta, en el formato solicitado (XML, PDF o ambos).

3.3.5 Códigos de respuesta

3.3.6 Consideraciones técnicas

• Es obligatorio incluir al menos un filtro en la solicitud.

• Si no se especifica el parámetro representación, el sistema descargará únicamente los archivos en formato XML.

• El archivo ZIP contendrá únicamente los CFDI que cumplan con los criterios definidos en los parámetros de búsqueda.

• El tamaño máximo de página (pageSize) es de 100 registros por solicitud, para optimizar el rendimiento.

• En caso de error en los parámetros o keyEmpresa no válida, el servicio devolverá los códigos 400 o 401 respectivamente.

3.4 Descarga CFDI de Retención (XML)

3.4.1 Estructura general de la petición

Este servicio permite obtener el archivo XML correspondiente a un CFDI de retención específico. El servicio se consume mediante una petición HTTP GET, indicando la clave de empresa (keyEmpresa) y el identificador único del comprobante (uuid).

3.4.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/cfdisretencion/descarga/xml

Autenticación y Headers

Parámetros

3.4.3 Ejemplo de petición

GET 
https://localhost:9050/6df9515e-6c7d-46fc-a2a8-86080ce9ba2f/ cfdisretencion/descarga/xml?uuid=7e00413dcf1b605e189b9a91972

3.4.4 Ejemplo de respuesta

Respuesta exitosa (código 200):

Content-Type: application/xml
Content-Disposition: attachment; filename="D095EF45-0465-4BBD-8F74-DE9576B909CA.xml"

El servicio devuelve el archivo XML correspondiente al UUID solicitado.

3.4.5 Códigos de respuesta

3.4.6 Consideraciones técnicas

• Los parámetros keyEmpresa y uuid son obligatorios; sin ellos, la petición no será procesada.

• El UUID debe enviarse en su formato encriptado.

• El servicio devuelve exclusivamente el archivo XML.

• El encabezado Content-Disposition incluye el nombre del archivo XML con su identificador único.

• En caso de error en los parámetros o en la autenticación, se devolverán los códigos 400 o 401 según corresponda.

3.5 Descarga CFDI de Retención (PDF)

3.5.1 Estructura general de la petición

Este servicio permite obtener el archivo PDF correspondiente a un CFDI de retención específico. El archivo descargado contiene la representación impresa del comprobante fiscal.

El servicio se consume mediante una petición HTTP GET, indicando la clave de empresa (keyEmpresa) y el identificador único del comprobante (uuid).

3.5.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/cfdisretencion/descarga/pdf

Autenticación y Headers

Parámetros

3.5.3 Ejemplo de petición

GET 
https://localhost:9050/6df9515e-6c7d-46fc-a2a8-86080ce9ba2f/ cfdisretencion/descarga/pdf?uuid=7e00413dcf1b605e189b9a91972

3.5.4 Ejemplo de respuesta

Respuesta exitosa (código 200):

Content-Type: application/pdf
Content-Disposition: attachment; filename="D095EF45-0465-4BBD-8F74-DE9576B909CA.pdf"

El servicio devuelve el archivo PDF correspondiente al UUID solicitado.

3.5.5 Códigos de respuesta

3.5.6 Consideraciones técnicas

• Los parámetros keyEmpresa y uuid son obligatorios para procesar la solicitud.
• El UUID debe enviarse en su formato encriptado.
• El servicio devuelve exclusivamente la representación impresa del CFDI en formato PDF.
• El encabezado Content-Disposition define el nombre del archivo generado.
• En caso de error en los parámetros o en la autenticación, se devolverán los códigos 400 o 401 según corresponda.

3.6 Generación de Retenciones

3.6.1 Estructura general de la petición

Este servicio permite emitir un nuevo CFDI de retención, indicando la empresa emisora, el tipo de retención, la sucursal correspondiente y el contenido del archivo fuente estructurado de acuerdo con el layout configurado previamente en el sistema.

La generación del CFDI se realiza mediante una petición HTTP POST, en la que se debe enviar la información en formato JSON.

Generación exitosa
Devuelve el id del cfdi de retención que se ha emitido, el id de la sucursal en la que se emitió, el RFC del receptor, la razón social del receptor, la fecha de emisión, el estatus del documento, el uuid, el monto, la fecha de cancelacion(aunque en este caso de emisión, siempre se encontrará vacío este campo), la ligas de descarga para el XML y PDF juntos, para el XML (individual), PDF (individual) y finalmente la liga de cancelacion (con la que se podría cancelar el documento posteriormente)

Error
Este error tiene que ver con la generación del CFDI de retención y no con el error que podría ocurrir al consumir este servicio. En este caso se devolverá el error que el motor de generación de la solución arroja.

3.6.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/cfdisretencion

Autenticación y Headers

Parámetros

3.6.3 Ejemplo de petición

POST 
https://localhost:9050/6df9515e-6c7d-46fc-a2a8-86080ce9ba2f/cfdisretencion?

{
  "idTipoCfdRetencion": "332c2994597401415717c9de2e21d207",
  "idSucursal": "6ac9a2c315480d5cc5534c7e58caee5a",
  "archivoFuente": "RET00|1.0|12345|2015-09-02T00:00:00-06:00|03|DescRetenc|\nRET01|BADD110313HCMLNS09|\nRET02|Nacional|\nRET020|MURR750516812|Razón Social Nacional|BADD110313HCMLNS09|\nRET03|1|1|2015|\nRET04|3252.5|0.00|0.00|0.00|\nRET040|0.00|01|0.00|Pago definitivo|\nRET99|"
}

3.6.4 Ejemplo de respuesta

Respuesta exitosa (código 200):

[
  {
    "idCfdiRetencion": "1dccc6e57b1d443c3e1a1ffd5095f382",
    "idSucursal": "6ac9a2c315480d5cc5534c7e58caee5a",
    "rfcReceptor": "MURR750516812",
    "razonSocial": "Razón Social Nacional",
    "fecha": "2015-01-24T01:18:22",
    "status": "CANCELADO",
    "uuid": "2310EABB-5F39-4694-8FBD-1EA0842C8113",
    "monto": "3252.500000",
    "fechaCancelacion": "",
    "pdfAndXmlDownload": "/985408d8-64ae-48e0-b46c-473b47176205/cfdisretencion/descarga?uuid=2310EABB-5F39-4694-8FBD-1EA0842C8113&representacion=XML_PDF",
    "pdfDownload": "/985408d8-64ae-48e0-b46c-473b47176205/cfdisretencion/descarga/pdf?uuid=3bf7942709f6eb925d26dae62c63f8c287b8868661bc4a69ce1e3c2e10ff98bd6486140ef80ba7ac7867620b4fc94fed",
    "xmlDownload": "/985408d8-64ae-48e0-b46c-473b47176205/cfdisretencion/descarga/xml?uuid=3bf7942709f6eb925d26dae62c63f8c287b8868661bc4a69ce1e3c2e10ff98bd6486140ef80ba7ac7867620b4fc94fed"
  }
]

3.6.5 Códigos de respuesta

3.6.6 Consideraciones técnicas

• Todos los campos marcados como requeridos deben incluirse correctamente.

• El parámetro archivoFuente debe estructurarse conforme al layout configurado en la plataforma, respetando el orden y los delimitadores establecidos.

• Para separar las líneas dentro del archivoFuente, se debe usar el carácter \n.

• En caso de error durante la generación del CFDI, el sistema devolverá el mensaje correspondiente generado por el motor de emisión.

• Las ligas de descarga (XML, PDF, XML_PDF) estarán disponibles tras la emisión exitosa del documento.

• Este servicio no realiza cancelaciones; únicamente genera el CFDI de retención.

3.7 Cancelación de Retenciones

3.7.1 Estructura general de la petición

La cancelación de CFDIs de retención se realiza mediante una petición HTTP POST, especificando los parámetros keyEmpresa y los UUIDs de los documentos a cancelar.

3.7.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/cfdisretencion/cancelar

Autenticación y Headers

Parámetros

3.7.3 Ejemplo de petición

Ejemplo para motivo 01 (con folio de sustitución)

POST 
https://localhost:9050/6df9515e-6c7d-46fc-a2a8-86080ce9ba2f/cfdisretencion/cancelar?

{
  "motivo": "01",
  "folioSustitucion": "B5E6897B-40A7-4DEA-ADD2-F417B32EE908",
  "uuid": [
    "B5E6897B-40A7-4DEA-ADD2-F417B32EE909",
    "B5E6897B-40A7-4DEA-ADD2-F417B32EE909"
  ]
}

Ejemplo para motivos 02, 03 y 04 (sin folio de sustitución)

POST 
https://localhost:9050/6df9515e-6c7d-46fc-a2a8-86080ce9ba2f/cfdisretencion/cancelar?

{
  "motivo": "02",
  "uuid": [
    "B5E6897B-40A7-4DEA-ADD2-F417B32EE909",
    "B5E6897B-40A7-4DEA-ADD2-F417B32EE909"
  ]
}

3.7.4 Ejemplo de respuesta

Respuesta exitosa (código 200):

[
  {
    "uuid": "DAC5C869-3DC3-41A1-85F3-FE113E7046AF",
    "status": 1201,
    "httpCode": 200,
    "description": " <Acuse xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Fecha="2021-12-15T23:28:06.4819808"RfcEmisor="B&amp;M011127BQ0" WorkProcessId="8e5a0254-babc-4b55-aaa1-9232dc739db0"xmlns="http://www.sat.gob.mx/esquemas/retencionpago/1"><Folios><UUID>0AA0A514-6997-4C1B-8A36-89BB0CB1B265</UUID><EstatusUUID>1201</EstatusUUID><Motivo>01</Motivo><FolioSustitucion>01E53227-38EC-458D-B1D4-08F2B533F98B</FolioSustitucion></Folios><Signature Id="SelloSAT" xmlns="http://www.w3.org/2000/09/xmldsig#"><SignedInfo><CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/><SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#hmac-sha512"/><Reference URI=""><Transforms><Transform Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116"><XPath>not(ancestor-or-self::*[local-name()='Signature'])</XPath></Transform></Transforms><DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha512"/><DigestValue>fMuB/Ee3grx4cDFX+GRpnX3ME0l9dLTLdbiYXundyMPS+GOZ1AR2XMtepTSZiD08NzAwF2nFFHWkZOIEU3a4Dw==</DigestValue></Reference></SignedInfo><SignatureValue>D4rC8c5ZK2eXtbJWQ2C6xOTeW3dkPIf6u2+i6DbX1FTXqPkVW1dcm4i+I9GEetpJOfS6pSxGBa152QBPimJBNg==</SignatureValue><KeyInfo><KeyName>30001000000400001215</KeyName><KeyValue><RSAKeyValue><Modulus>nbtVtkPquCMLdpgeClMrTmxzCjyjn8P9YrBlW9jXC/FcXozIYHvzctK1pRxRxLTKlChc9fjluht9ffDfGOWim/4AlTrCiG6om7ItkHbLGMQrABp8qGY+SPmq1xtZ7qbbgoTFCtzP3pN9Z4uSDhdnrF2655sdmDzHJYE9MirNLM4SIdSFsabA31CCAMaWpB4TO6ZmExLp+wUiUyeIFWswc5G5KvmS/lU5tbXLK7zBDDUVjN0K1r/0iaZIZzPMxQcgfgYBrfLGZ3916MkmF28iBk5l1sfNTKS9S445QHKc+6oTP4UDDnjN/K14YWX449BAMxKcelEpjZlBQs1a1eNVcQ==</Modulus><Exponent>AQAB</Exponent></RSAKeyValue></KeyValue></KeyInfo></Signature></Acuse>"
  }
]

3.7.5 Códigos de respuesta

3.7.6 Consideraciones técnicas

• Se permite cancelar hasta 500 CFDIs de retención en una sola petición.

• Los UUIDs deben corresponder a CFDIs emitidos por la keyEmpresa indicada.

• En caso de incluir UUIDs inválidos o que no correspondan a la empresa emisora, el servicio devolverá un error 403.

• El motivo de cancelación debe ser uno de los valores definidos por el SAT (01–04).

• Cuando el motivo sea 01, es obligatorio incluir el campo folioSustitucion.

• El campo description contiene el XML del acuse de cancelación, el cual debe conservarse como evidencia oficial del proceso.

Motivo de Cancelación

3.8 Consultar los CFDIs Cancelados por Rango de Fechas

3.8.1 Estructura general de la petición

Este servicio permite consultar los CFDIs cancelados dentro de un rango de fechas específico. La búsqueda por fecha o rango de fechas aplica únicamente para los comprobantes cancelados en versiones iguales o posteriores a la 3.64.

Los documentos cancelados en versiones anteriores no podrán ser consultados mediante este endpoint.

3.8.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/cfdis/consultaCancelacion

Autenticación y Headers

Parámetros

3.8.3 Ejemplo de petición

POST https://localhost:9050/6df9515e-6c7d-46fc-a2a8-86080ce9ba2f/cfdis/consultaCancelacion
Content-Type: application/json
Authorization: Basic {Token}

{
  "uuid": ["3BC513EC-FD2A-4B66-AAB2-4C46BC976C7A"]
}

3.8.4 Ejemplo de respuesta

Respuesta exitosa (código 200):

[
  {
    "uuid": "3BC513EC-FD2A-4B66-AAB2-4C46BC976C7A",
    "status": "CANCELABLE_SIN_ACEPTACION"
  }
]

Ejemplo de error – CFDI no encontrado

[
  {
    "uuid": "52CE170D-20DB-45B7-84EF-F886537163B1",
    "status": "NO_TRALIX"
  }
]

3.8.5 Códigos de respuesta

3.8.6 Consideraciones técnicas

• La consulta por fecha o rango de fechas solo aplica para CFDIs cancelados en versión 3.64 o posterior.

• Al menos un parámetro debe incluirse en la solicitud; no se permiten peticiones vacías.

• Si se utilizan filtros por estado, deben acompañarse de fecha, fechaInicial o fechaFinal.

• Los parámetros válidos para la consulta de estados son los siguientes:

3.9 Consultar los CFDIs Cancelados Indicando las Fechas

3.9.1 Estructura general de la petición

Este servicio permite consultar los CFDIs cancelados indicando fechas específicas o un rango de fechas, mostrando además la fecha de cancelación asociada a cada comprobante. La consulta admite el uso de filtros por UUID, estado o fecha.

3.9.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/cfdis/consultaCancelacionFecha

Autenticación y Headers

Parámetros

Es requerido al menos un parámetro opcional en la petición, en formato json.

3.9.3 Ejemplo de petición

POST 
https://localhost:9050/6df9515e-6c7d-46fc-a2a8-86080ce9ba2f/cfdis/consultaCancelacion{"uuid":["3BC513EC-FD2A-4B66-AAB2-4C46BC976C7A"]}

Ejemplo adicional por fecha y estado:

POST
https://localhost:9050/6df9515e-6c7d-46fc-a2a8-86080ce9ba2f/cfdis/consultaCancelacion{"uuid":["3BC513EC-FD2A-4B66-AAB2-4C46BC976C7A"]}

3.9.4 Ejemplo de respuesta

Respuesta exitosa (código 200):

[
  {
    "uuid": "3BC513EC-FD2A-4B66-AAB2-4C46BC976C7A",
    "status": "CANCELABLE_SIN_ACEPTACION",
    "fecha": "2020-01-20"
  }
]

Ejemplo de error – CFDI no encontrado

[
  {
    "uuid": "52CE170D-20DB-45B7-84EF-F886537163B1",
    "status": "NO_TRALIX",
    "fecha": "2025-11-13"
  }
]

3.9.5 Códigos de respuesta

3.9.6 Consideraciones técnicas

• Al menos un parámetro debe incluirse en la solicitud; no se permiten peticiones vacías.

• Si se incluyen filtros por estado, deben acompañarse de fecha, fechaInicial o fechaFinal.

• Los parámetros válidos para la consulta de estados son los siguientes:

3.10 Consultar los CFDI Enviados

3.10.1 Estructura general de la petición

Este servicio permite consultar los CFDI enviados a través del servicio de Email Rastreable, mostrando información relevante como el UUID, estatus, tipo de CFDI, correo electrónico del receptor y fecha de envío. La consulta se realiza en formato JSON y admite filtros por fechas, tipo de CFDI, tipo de reporte y número de página.

Nota: La consulta solo aplica para el servicio de Email Rastreable.

3.10.2 Parámetros requeridos

Endpoint

/<keyEmpresa>/emailRastreable/report

Autenticación y Headers

Parámetros

3.10.3 Ejemplo de petición

{
  "fechaInicial" : "2020-01-01",
  "fechaFinal" : "2020-11-19",
  "tiposCfdi" : ["cfdi33", "nomina"],
  "tipoReporte" : "OPEN",
  "page": 1
}

3.10.4 Ejemplo de respuesta

Respuesta exitosa (código 200):

{
  "page": 1,
  "lastPage": true,
  "reports": [
    {
      "uuid": "BCB0B52D-9A13-52AC-B432-DDDD29FF15EE",
      "serie": "",
      "folio": "",
      "rfcReceptor": "",
      "razonSocial": "",
      "monto": "",
      "fechaEmision": "",
      "tipoCfdi": "baseJhoanProd",
      "email": "jose.martinez@tralix.com",
      "fecha": "2020-10-23 22:15:52",
      "estatus": "OPEN"
    }
  ]
}

3.10.5 Códigos de respuesta

3.10.6 Consideraciones técnicas

• Este servicio solo aplica para el módulo de Email Rastreable.

• Los parámetros fechaInicial y fechaFinal deben tener formato yyyy-MM-dd.

• El campo tiposCfdi debe ser un arreglo con los tipos de comprobantes a consultar.

• El campo page indica el número de página y lastPage indica si la página actual es la última del conjunto de resultados.

4. Contacto y Soporte

Para soporte técnico o dudas sobre el uso del servicio puede comunicarse con el área de soporte técnico de Tralix vía ticket.

Endpoint Cancelación Acuse

1. Introducción

Este documento describe el endpoint: Cancelación de CFDI retornando el Acuse, el cual permite realizar la cancelación de uno o varios CFDI y obtener como respuesta el acuse de cancelación emitido por el SAT, incluyendo el estado fiscal y el código de estatus correspondiente.

El servicio está diseñado para ser consumido vía API REST, utilizando solicitudes HTTP en formato JSON.

2. Cancelación de CFDI retornando el Acuse

2.1 Estructura general de la petición

Endpoint para cancelar en XSA para retornar el acuse de cancelación. La petición consiste en el envío de un cuerpo JSON que incluye el listado de UUIDs a cancelar, el motivo de cancelación y, cuando aplique, el folio de sustitución.

2.2 Parámetros requeridos

Endpoint