Retenciones
Timbrado y Cancelación de CFDI de Retenciones
Producto: PAC Timbrador
1 Introducción
Este manual describe el uso de los servicios del PAC Tralix para:
Timbrado de CFDI de Retenciones.
Cancelación de CFDI de Retenciones.
El servicio valida:
Estructura del XML
Certificados y sellos digitales
Reglas del SAT
Parámetros de seguridad (customer key, IP, etc.)
Todas las respuestas del servicio regresan un HTTP 200, incluso en casos de error, salvo en los casos en que el recurso que se pide no exista, entonces regresa un 404 o cuando faltan parámetros en la llamada en cuyo caso se devuelve un un 400 respectivamente.
2 Timbrado de CFDI de Retenciones
2.1 Estructura general de la petición
El servicio se invoca mediante una petición HTTP tipo POST, enviando un archivo XML de retenciones conforme a la estructura del SAT.
2.2 Parámetros requeridos
Ambientes disponibles:
Endpoint
Método
Ambiente
Ruta
POST
Pruebas
🔗 https://pruebastfd.tralix.com:7070/retenciones/
POST
Productivo
🔗 https://timbrador.tralix.com:7070/retenciones/
Parámetros
Atributo
Tipo
Uso
Descripción
Content-Type
Header
Requerido
text/xml; charset=UTF-8. El valor debe de ser tal cual se muestra.
customerKey
Header
Requerido
Clave única del cliente que desea timbrar el comprobante de retenciones.
Contenido
Body
Requerido
XML del comprobante de retenciones
2.3 Ejemplo de la petición:
HTTP:
POST /retenciones/ HTTP/1.1
Content-Type: text/xml;charset=UTF-8
customerKey: b391655ac2242d85ddd36d37b482259b1b7dfc1a
Content-Length: 4506
Host: timbrador.tralix.com
Connection: Keep-Alive
XML Cuerpo (Body):
Ejemplo:
HTTP:
POST /retenciones/ HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
customerkey: b391655ac2242d85ddd36d37b482259b1b7dfc1a
Content-Length: 4506
Host: 10.0.4.122:9000
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
XML Cuerpo (Body):
2.4 Ejemplo de respuesta
Salida: El xml del timbre o xml con error.
Respuesta exitosa:
HTTP/1.1 200 OK
Content-Type: text/xml;charset=utf-8
Content-Length: 1111
Respuesta con error:
HTTP/1.1 200 OK
Content-Type: text/xml;charset=utf-8
Content-Length: 356
El CFD no cumple con la estructura correcta: org.xml.sax.SAXParseException; lineNumber: 2; columnNumber: 141; The element type "retenciones:Emisores" must be terminated by the matching end-tag "</retenciones:Emisores>".
2.5 Códigos de respuesta
Código
Tipo
Descripción
200
SUCCESS
Se pudo hacer la autenticación con el SAT y se regresa el token dado por el servicio del SAT.
400
ERROR
Si hay un error en los parámetros de llamada, por ejemplo si la petición no es cancelación o recepción
500
ERROR
Si hay algún error interno en el servicio
Código
Tipo
Descripción
200
SUCCESS
Se pudo timbrar el comprobante y se regresa el timbre.
301
ERROR
El XML no está construido conforme al W3C y/o con la estructura del XSD publicado en el Anexo 20 del RMF
302
ERROR
El sello del emisor no está generado correctamente.
303
ERROR
El CSD del emisor no corresponda al RFC establecido como emisor del comprobante.
304
ERROR
El CSD del emisor ha sido revocado
305
ERROR
La fecha de emisión no se encuentre dentro de la vigencia del CSD del emisor.
306
ERROR
El certificado utilizado corresponde a una FIEL
307
ERROR
El XML ya cuenta con un nodo TimbreFiscalDigital
308
ERROR
El CSD del emisor no es un certificado emitido por la autoridad del SAT
401
ERROR
El rango de la fecha de generación es mayor a 72 horas con base en la fecha de emisión
402
ERROR
El RFC del emisor no está autorizado para emisión de CFDI (no se encuentra en la lista autorizada del SAT)
901
ERROR
El cliente con el key #CUSTOMER_KEY no es válido.
902
ERROR
El RFC #RFC no está registrado
903
ERROR
El RFC #RFC se encuentra inactivo por el momento
904
ERROR
No cuenta con licencia para realizar peticiones
905
ERROR
El RFC #RFC no pertenece al cliente con el key #KEY
907
ERROR
Debe invocar al servicio con el customerkey que le fue asignado
910
ERROR
No se puede determinar el cliente a partir del RFC #RFC, verifique que el valor de la cabecera de customerkey
990
ERROR
Su comprobante es válido, pero no se puede generar un timbre fiscal por el momento.
999
ERROR
Error interno en el servidor, por favor intente más tarde
3 Cancelación de CFDI de Retenciones
3.1 Estructura general
El servicio permite cancelar CFDI de retenciones conforme al estándar del SAT, haciendo validaciones de estructura, firma y relación emisor-UUID. Este servicio recibe el xml de cancelación de retenciones de acuerdo al estándar del SAT, hace las validaciones necesarias de estructura, hace la petición de token de cancelación y manda a cancelar con el xml proporcionado.
Ambientes disponibles:
Endpoint
Método
Ambiente
Ruta
POST
Producción
🔗 https://timbrador.tralix.com:8081/retenciones/cancelaUno/
POST
Pruebas
🔗 https://pruebastfd.tralix.com:8081/retenciones/cancelaUno/
3.2 Parámetros requeridos
Parámetro
Tipo
Uso
Descripción
Content-Type
Header
Requerido
text/xml; charset=UTF-8, el valor debe de ser tal cual se muestra.
idCustomer
Header
Requerido
Customer key del cliente que desea cancelar el comprobante de retenciones.
ipAddress
Header
Requerido
IP con la que se está intentado cancelar.
Contenido
Body
Requerido
XML de cancelación de acuerdo al estándar del SAT.
3.3 Ejemplo de petición
HTTP:
POST /retenciones/cancelaUno/ HTTP/1.1
Content-Type: text/xml; charset=UTF-8
idCustomer: b391655ac2242d85ddd36d37b482259b1b7dfc1a
ipAddress: 10.0.0.88
Cuerpo (Body):
0E6F67DD-6765-46EC-9447-D8CD759D2286
...
HTTP:
POST /retenciones/cancelaUno/ HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml; charset=UTF-8
idCustomer: b391655ac2242d85ddd36d37b482259b1b7dfc1a
ipAddress: 10.0.0.88
Content-Length: 4007
Host: 10.0.4.122:9000
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
Cuerpo (Body):
0E6F67DD-6765-46EC-9447-D8CD759D2286WMQbS6vPsNK9Qj0ItYXpT2MORWA=GlFeSOMtP7gHMHXF0XT2XmqsS1f2Qg6xINwmO6V6K3ft8s4O3MoSw6fxnxEFLlOeojOadSaPL+py
OJSQqIF8XChyeE2J1dAdvqmZV3jWN2jX0TyY3FwBd/QClVY3vLvIxIiroJgkGeduefYy3DC4cC6V
QwvwAkTwRi9SnYuROb5f/NAmsLnB5aTLTen0eNDS8PFTnMfkxnb5e5dP+aBxV4wo5oANez11ABYu
1OctfRcdVuJ371Hr16qUSgFGi6kCYJ1TIwj07qdXOaDK+FebNYBOQzwqd0AQRSYADUBeJRtBiaWl
h6ij/NsHBjvboz1m8uBGsUsOJOCAAG13CSIOSQ==OID.1.2.840.113549.1.9.2=Responsable: ACDMA, OID.2.5.4.45=SAT970701NN3, L=Coyoac[0xc3][0xa1]n, ST=Distrito Federal, C=MX, OID.2.5.4.17=06300, STREET="Av. Hidalgo 77, Col. Guerrero", EMAILADDRESS=asisnet@pruebas.sat.gob.mx, OU=Administraci[0xc3][0xb3]n de Seguridad de la Informaci[0xc3][0xb3]n, O=Servicio de Administraci[0xc3][0xb3]n Tributaria, CN=A.C. 2 de pruebas(4096)286524172099382162235533054548081509954831791922MIIGEDCCA/igAwIBAgIUMjAwMDEwMDAwMDAzMDAwMDQ4NzIwDQYJKoZIhvcNAQELBQAwggFmMSAw
HgYDVQQDDBdBLkMuIDIgZGUgcHJ1ZWJhcyg0MDk2KTEvMC0GA1UECgwmU2VydmljaW8gZGUgQWRt
aW5pc3RyYWNpw7NuIFRyaWJ1dGFyaWExODA2BgNVBAsML0FkbWluaXN0cmFjacOzbiBkZSBTZWd1
cmlkYWQgZGUgbGEgSW5mb3JtYWNpw7NuMSkwJwYJKoZIhvcNAQkBFhphc2lzbmV0QHBydWViYXMu
c2F0LmdvYi5teDEmMCQGA1UECQwdQXYuIEhpZGFsZ28gNzcsIENvbC4gR3VlcnJlcm8xDjAMBgNV
BBEMBTA2MzAwMQswCQYDVQQGEwJNWDEZMBcGA1UECAwQRGlzdHJpdG8gRmVkZXJhbDESMBAGA1UE
BwwJQ295b2Fjw6FuMRUwEwYDVQQtEwxTQVQ5NzA3MDFOTjMxITAfBgkqhkiG9w0BCQIMElJlc3Bv
bnNhYmxlOiBBQ0RNQTAeFw0xNDEwMDgxNTA5MzBaFw0xODEwMDcxNTA5MzBaMIHKMSAwHgYDVQQD
ExdIRUNUT1IgVkFaUVVFWiBCRUNFUlJJTDEgMB4GA1UEKRMXSEVDVE9SIFZBWlFVRVogQkVDRVJS
SUwxIDAeBgNVBAoTF0hFQ1RPUiBWQVpRVUVaIEJFQ0VSUklMMQswCQYDVQQGEwJNWDEgMB4GCSqG
SIb3DQEJARYRcHJ1ZWJhQHNhdC5nb2IubXgxFjAUBgNVBC0TDUdBVkE3MzA3MTdBRTExGzAZBgNV
BAUTEkdBVkE3MzA3MTdIREZSR1IwNTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJjn
MOxpkQkTGXmJpXf0qnBSRatOtkbi8c0iHAKYS1XASXrxkJLXt2ZkFg83EkkZxyRZ7+5qFG7qKUET
3BDmdLW8RTBuWSLzonlUAjNfSTjuNNG0ZNxpTGHHsOenRUfPwNx9yopzU6YKHAfNoeoyXsbsLg1I
yezal/vu86pa5Bonb/hTj6GMHg7Wj7oFit3ilVUu5Bc9a1djT3JJVuCXaT+Mspd3UiwtYxZihD4h
ZhuT8wqYEFfulUykofIeuexCKBdV6ugaD9Ub1/GOyhzNymYzM1WlPfgKxCed6KQ1CaJLM3jo3U79
izakxfH45ghlol7SxXHidF3tYpgknv6TgU8CAwEAAaNPME0wDAYDVR0TAQH/BAIwADALBgNVHQ8E
BAMCA9gwEQYJYIZIAYb4QgEBBAQDAgWgMB0GA1UdJQQWMBQGCCsGAQUFBwMEBggrBgEFBQcDAjAN
BgkqhkiG9w0BAQsFAAOCAgEAkRIj1K/mOCyd/cyxb9m9HpAWgUUwKG00gQXwiM6cJYMGhjk6e2kc
lCUPUnp2Ct8Gn4JoHA8jTI8JOv1C7sJor0eO+xAtElvYh4d7NmGZvpZ1BkCt43EAt0gq/NVH37GL
WuPC934dlLiq0m9Tv/7UqjVKQKWAKnQc008GJTY+vI8bk1rRctY6RqvhiKnDcwJeNvQfWAnFUJ2L
6+ffphvbvuuWZrAvi8CNIZ6ZFwCkGpFAoKXErPTy4lyTPfsPpg5B6BxhskJH5g5QL8KrpkCheMHg
YfQv+YxOKK8ohpcxaEK+CF/QQkfWGSfzTjKO/fN+uht18UYiuGblwXkGV+N0OLPQZUzjtwEJSLFH
LI+3BuDU96baJXmxC31RhdNnRepqoKtALKNVDadpaoCZtTICb6y1FAvI31RrPOUh1O7GbGGhqGQL
96eD3q8UvG99/FRc0Ah4xRCjOg52TLbnhx7eQFA2HIccRBdceELUSGE3YoadB6q1AE68Q6hfP8Oh
i20TvgmLZOTfncVIqszK3jn+e71nYCQdH1D6ZsLIx0L5h7CiWRvliiMulloiA9UxjJ1nwssVNHgN
BhqAOFPw0rYnHrsbcKW5yiNPAhZinqPVdxBWgeIP3ClyhhrV5jG6GxEUQcf0CWdwHLYTxcWksqqB
vkRhj++ft29e5p/lm47XThE=
3.4 Ejemplo de respuesta
Salida: El XML del acuse o el ERROR dado por el SAT o por negocio.
Respuesta exitosa
Ejemplo de salida satisfactoria con código http 200 y código de status 1201:
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 1501
Content-Type: application/xml; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.5
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Wed, 31 Dec 2014 19:17:53 GMT
CF93C8F6-E9EE-4AD5-9CC0-4E771CE726B6
1201
not(ancestor-or-self::*[local-name()='Signature'])XG1pp/m3TuS2j971YCxqMa7aTi2MW/pHNElJwEzFB9So5QEjgcRXnyC4xoEJDG5yZF8yqo9aNWuDMkfwAvQKQA==s8trd9ZLoW2axhyXXssfa4MeBrCK0T5p1JfuRGOFbj8JCF5f3+hqgx5tSyvuEWo3leDGpSs7gmYjgBCc4xF7gw==20001000000300003586n77fbi0dTENVn43LCUOIF/8iyQObFg/AaTRBdpf0fVuozOOy48INue46sN54AHL+I50s1U8Nh6Dq+MRvRNc8WyHPQWsnmSaicT5vAkkzqucVj004WyLcmpysY45DrCxSitPMRzop3XboPr1msWd3EuyduUtbu3QmNRin8uzpYg8=AQAB
Ejemplo de salida de error con código http 200 y código de status 1XXX:
HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 1409
Content-Type: application/xml; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.5
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Wed, 31 Dec 2014 20:46:59 GMT
not(ancestor-or-self::*[local-name()='Signature'])KVsuu6MBIq35WvJZ4regrxHPg9UEtiMizXsX14P6o2Dm0UbI1BHz7xUW5AqZ5HzY399PTzRSAPgmT8DEDQQjkg==LpABcSjt+vbvRp876GcR0l1UajX5Z5P6/f4qilRyIH1Y06DWYbmy74Fnc3iyKtTqXDSPkPzg7J3Ktfyc7WbSuw==20001000000300003586n77fbi0dTENVn43LCUOIF/8iyQObFg/AaTRBdpf0fVuozOOy48INue46sN54AHL+I50s1U8Nh6Dq+MRvRNc8WyHPQWsnmSaicT5vAkkzqucVj004WyLcmpysY45DrCxSitPMRzop3XboPr1msWd3EuyduUtbu3QmNRin8uzpYg8=AQAB
Respuesta con error
Ejemplo de salida de error con código http 400 y código de status XXX:
HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8
Content-Length: 88
{"errorCodigo":"902", "descripcionError":"El RFC 'GAVA730717AE1' no está registrado."}
Ejemplo de salida de error con código http 400 y sin código de status:
HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=utf-8
Content-Length: 23
Falta Header: ipAddress
3.5 Códigos de respuesta
Código HTTP
Código
Tipo
Descripción
200
1201
SUCCESS
UUID Cancelado
200
1202
ERROR
Previamente cancelado
200
1203
ERROR
UUID no corresponde con el emisor
200
1205
ERROR
UUID No existe
200
1300
ERROR
Autenticación no válida
200
1301
ERROR
XML mal formado
200
1302
ERROR
Estructura de folios no válida
200
1303
ERROR
Estructura de RFC no válida
200
1304
ERROR
Estructura de fecha no válida
200
1305
ERROR
Certificado no corresponde al emisor
200
1306
ERROR
Certificado no vigente
200
1307
ERROR
Uso de FIEL no permitido
200
1308
ERROR
Certificado revocado o caduco
200
1309
ERROR
Firma mal formada o inválida
400
308
ERROR
El CSD del emisor no es un certificado emitido por la autoridad del SAT.
400
401
ERROR
El rango de la fecha de generación es mayor a 72 horas con base en la fecha de emisión
400
901
ERROR
El cliente con el CustomerKey proporcionado no es válido
400
902
ERROR
El RFC no esta registrado como cliente
400
903
ERROR
El RFC se encuentra inactivo por el momento
400
904
ERROR
No cuenta con licencia para realizar peticiones
400
905
ERROR
El RFC no pertenece al cliente con el CustomerKey que proporciono
400
910
ERROR
No se puede determinar el cliente a partir del RFC
400
999
ERROR
Error interno en el servidor
400
407
ERROR
Error en el servicio de Cancelación del SAT
400
ERROR
Cuando faltan parámetros requeridos en la petición
4 Consideraciones Técnicas
Toda comunicación debe realizarse con codificación UTF-8.
Las URLs deben invocarse vía POST con contenido tipo text/xml.
El uso de certificados y estructura XML debe cumplir lo indicado por el Anexo 20 del SAT.
En todos los casos, incluya siempre el CustomerKey correcto.
5 Contacto y soporte
Para soporte técnico, dudas sobre el uso del servicio o solicitud de su CustomerKey, puede comunicarse con su ejecutivo o con el área de soporte técnico de Tralix vía ticket.