diff --git a/.github/workflows/publish-maven.yml b/.github/workflows/publish-maven.yml
new file mode 100644
index 00000000..827d2e72
--- /dev/null
+++ b/.github/workflows/publish-maven.yml
@@ -0,0 +1,40 @@
+name: Publish to Maven Central
+
+on:
+ push:
+ tags:
+ - 'release-*'
+
+jobs:
+ publish:
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+
+ - name: Set up JDK 11
+ uses: actions/setup-java@v4
+ with:
+ java-version: '11'
+ distribution: 'temurin'
+ cache: maven
+ server-id: central
+ server-username: MAVEN_USERNAME
+ server-password: MAVEN_PASSWORD
+
+ - name: Import GPG key
+ uses: crazy-max/ghaction-import-gpg@v6
+ with:
+ gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }}
+ passphrase: ${{ secrets.GPG_PASSPHRASE }}
+
+ - name: Build and verify
+ run: mvn clean verify -DskipTests
+
+ - name: Publish to Maven Central
+ run: mvn deploy -Prelease -DskipTests
+ env:
+ MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
+ MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
+ GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..6e19bec1
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,103 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+SW-JAVA is a Java SDK for consuming SW sapien® CFDI (Mexican electronic invoicing) services. It provides authentication, stamping (timbrado), cancellation, validation, and other tax document operations.
+
+## Build Commands
+
+```bash
+# Build the project
+mvn clean package
+
+# Build with dependencies JAR
+mvn clean package assembly:single
+
+# Run all tests
+mvn test
+
+# Run a single test class
+mvn test -Dtest=SWAuthenticationServiceTest
+
+# Run a specific test method
+mvn test -Dtest=SWAuthenticationServiceTest#testAuth
+
+# Build for release (includes GPG signing)
+mvn clean deploy -Prelease
+```
+
+## Test Environment Variables
+
+Tests require the following environment variables:
+- `SDKTEST_USER` - SW account username
+- `SDKTEST_PASSWORD` - SW account password
+- `SDKTEST_TOKEN` - SW authentication token
+
+Test endpoints:
+- Services URL: `https://services.test.sw.com.mx`
+- API URL: `https://api.test.sw.com.mx`
+
+## Architecture
+
+### Service Layer (`Services/`)
+All services extend the abstract `SWService` base class which handles:
+- Authentication (user/password or token-based)
+- Token auto-refresh based on expiration
+- Proxy support
+- TLS 1.2 enforcement
+
+Key services:
+- `SWAuthenticationService` - Token generation
+- `SWStampService` / `SWStampServiceV2` / `SWStampServiceV4` - CFDI stamping
+- `SWIssueService` / `SWIssueServiceV2` / `SWIssueServiceV4` - CFDI sealing and stamping
+- `SWCancelationService` - Invoice cancellation
+- `SWValidateService` - CFDI validation
+- `SWBalanceAccountService` - Account balance queries
+- `SWPdfService` - PDF generation from CFDI
+- `SWStorageService` - Document storage operations
+
+### Request/Response Pattern (`Utils/Requests/`, `Utils/Responses/`)
+Each service has corresponding request and response classes:
+- Request classes handle HTTP communication to SW APIs
+- Response classes model the API responses with status, data, and error information
+- Response versions (V1-V4) provide different levels of detail for stamping operations
+
+### Response Versions for Stamping
+| Version | Response Content |
+|---------|------------------|
+| V1 | Timbre fiscal digital (TFD) only |
+| V2 | TFD + timbrado CFDI |
+| V3 | Timbrado CFDI only |
+| V4 | All stamping data |
+
+### Exceptions (`Exceptions/`)
+- `AuthException` - Authentication failures
+- `GeneralException` - General API errors
+- `ValidationException` - Input validation errors
+
+### Helpers (`Utils/Helpers/`)
+- `BuildResponseV1-V4` - Response builders for different stamp versions
+- `RequestHelper` / `RequestZipHelper` - HTTP request utilities
+- `Validations` - Input validation utilities
+
+## CFDI Types Supported
+
+Test resources in `src/test/resources/CFDI40/` show supported document types:
+- Standard invoices (Ingreso)
+- Payments (Pagos20)
+- Payroll (Nomina12)
+- Foreign trade (ComercioExterior11)
+- Transportation (CartaPorte20)
+- Retentions (Retenciones20)
+- Donations (Donatarias11)
+- Other complements (INE, Addenda, etc.)
+
+## Dependencies
+
+The SDK uses:
+- Apache HttpClient 5 for HTTP operations
+- org.json and Gson for JSON processing
+- JUnit Jupiter 5 for testing
+- External dependency `sw-resources-java` for CFDI cadena original generation
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 00000000..78416b76
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lunasoft®
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
index 2fd63f4d..68adbe87 100644
--- a/README.md
+++ b/README.md
@@ -418,6 +418,205 @@ public class ExampleReadme {
```
+# Cancelación de Retenciones #
+
+Este servicio se utiliza para cancelar retenciones, aquí los métodos que se ofrecen:
+
+
+
+Cancelación de Retenciones por CSD
+
+Como su nombre lo indica, este método recibe todos los elementos que componen el CSD los cuales son los siguientes:
+
+- Certificado (.cer) en Base64
+- Key (.key) en Base64
+- RFC emisor
+- Password del archivo key
+- UUID
+- Motivo
+- Folio Sustitución (requerido sólo cuando Motivo es 01)
+
+**Ejemplo de consumo de la librería para cancelar retenciones con CSD**
+
+```java
+package com.mycompany.examplereadme;
+
+import Exceptions.AuthException;
+import Exceptions.GeneralException;
+import Services.CancelationRetention.SWCancelationRetentionService;
+import Utils.Responses.Cancelation.CancelationResponse;
+import java.io.IOException;
+
+public class ExampleReadme {
+
+ public static void main(String[] args) {
+ try {
+ //Instancia del servicio y autenticación
+ SWCancelationRetentionService sdk = new SWCancelationRetentionService("user", "password", "https://services.test.sw.com.mx");
+ CancelationResponse response = null;
+ //Paso de datos de cancelación
+ response = (CancelationResponse) sdk.Cancelation("uuid", "password_csd", "rfc", "b64Cer", "b64Key", "motivo", "folio_sustitucion");
+ //Muestra los resultados
+ System.out.println(response.Status);
+ System.out.println(response.HttpStatusCode);
+ System.out.println(response.acuse);
+ System.out.println(response.uuid);
+ System.out.println(response.uuidStatusCode);
+ //En caso de obtener un error, este puede obtenerse de los campos
+ System.out.println(response.message);
+ System.out.println(response.messageDetail);
+ } catch (AuthException | GeneralException | IOException e) {
+ System.out.println(e);
+ }
+
+ }
+}
+```
+
+**Cancelar retenciones con CSD utilizando token**
+
+```java
+ //Basta con sustituir esta linea en el ejemplo anterior, colocarás el token de tu cuenta y la URL base del ambiente que requieres acceder
+ SWCancelationRetentionService sdk = new SWCancelationRetentionService("tokenUser", "https://services.test.sw.com.mx");
+```
+
+
+
+
+Cancelación de Retenciones por PFX
+
+
+Este método recibe los siguientes parámetros:
+
+- Archivo PFX en Base64
+- RFC emisor
+- Password de PFX
+- UUID
+- Motivo
+- Folio Sustitución (requerido sólo cuando Motivo es 01)
+
+**Ejemplo de consumo de la librería para cancelar retenciones con PFX**
+
+```java
+package com.mycompany.examplereadme;
+
+import Exceptions.AuthException;
+import Exceptions.GeneralException;
+import Services.CancelationRetention.SWCancelationRetentionService;
+import Utils.Responses.Cancelation.CancelationResponse;
+import java.io.IOException;
+
+public class ExampleReadme {
+
+ public static void main(String[] args) {
+ try {
+ //Instancia del servicio y autenticación
+ SWCancelationRetentionService sdk = new SWCancelationRetentionService("user", "password", "https://services.test.sw.com.mx");
+ CancelationResponse response = null;
+ //Paso de datos de cancelación
+ response = (CancelationResponse) sdk.Cancelation("uuid", "password_pfx", "rfc", "pfxb64", "motivo", "folio_sustitucion");
+ //Muestra los resultados
+ System.out.println(response.Status);
+ System.out.println(response.HttpStatusCode);
+ System.out.println(response.acuse);
+ System.out.println(response.uuid);
+ System.out.println(response.uuidStatusCode);
+ //En caso de obtener un error, este puede obtenerse de los campos
+ System.out.println(response.message);
+ System.out.println(response.messageDetail);
+ } catch (AuthException | GeneralException | IOException e) {
+ System.out.println(e);
+ }
+
+ }
+}
+```
+
+**Cancelar retenciones con PFX utilizando token**
+
+```java
+ //Basta con sustituir esta linea en el ejemplo anterior, colocarás el token de tu cuenta y la URL base del ambiente que requieres acceder
+ SWCancelationRetentionService sdk = new SWCancelationRetentionService("tokenUser", "https://services.test.sw.com.mx");
+```
+
+
+
+
+Cancelación de Retenciones por XML
+
+
+Este método recibe únicamente el XML sellado con los UUID a cancelar.
+
+**Ejemplo de XML para cancelar retenciones**
+```xml
+
+
+
+
+
+
+
+
+
+```
+
+Para caso de motivo 01 deberá añadir el atributo "FolioSustitucion" dentro del Nodo
+**Ejemplo nodo Folio motivo 01**
+```xml
+
+
+
+```
+
+**Ejemplo de consumo de la librería para cancelar retenciones por XML**
+
+```java
+package com.mycompany.examplereadme;
+
+import Exceptions.AuthException;
+import Exceptions.GeneralException;
+import Services.CancelationRetention.SWCancelationRetentionService;
+import Utils.Responses.Cancelation.CancelationResponse;
+import java.io.IOException;
+
+public class ExampleReadme {
+
+ public static void main(String[] args) {
+ try {
+ //Instancia del servicio y autenticación
+ SWCancelationRetentionService sdk = new SWCancelationRetentionService("user", "password", "https://services.test.sw.com.mx");
+ CancelationResponse response = null;
+ //Paso de XML de cancelación
+ response = (CancelationResponse) sdk.Cancelation("xmlCancelacion");
+ //Muestra los resultados
+ System.out.println(response.Status);
+ System.out.println(response.HttpStatusCode);
+ System.out.println(response.acuse);
+ System.out.println(response.uuid);
+ System.out.println(response.uuidStatusCode);
+ //En caso de obtener un error, este puede obtenerse de los campos
+ System.out.println(response.message);
+ System.out.println(response.messageDetail);
+ } catch (AuthException | GeneralException | IOException e) {
+ System.out.println(e);
+ }
+
+ }
+}
+```
+
+**Cancelar retenciones por XML utilizando token**
+
+```java
+ //Basta con sustituir esta linea en el ejemplo anterior, colocarás el token de tu cuenta y la URL base del ambiente que requieres acceder
+ SWCancelationRetentionService sdk = new SWCancelationRetentionService("tokenUser", "https://services.test.sw.com.mx");
+```
+
+
# Validación #
@@ -628,6 +827,145 @@ public class ExampleReadme {
```
+
+
+Consulta de saldo de un usuario específico
+
+
+
Este método recibe los siguientes parametros:
+* Usuario y contraseña o Token
+* Url APIs SW (Url Servicios SW solo es necesaria cuando se usa autenticación con usuario y contraseña)
+* IdUser (UUID del usuario del cual se desea obtener el saldo)
+
+**Ejemplo de consumo de la libreria para consultar el saldo de un usuario específico utilizando Token**
+
+```java
+package com.mycompany.examplereadme;
+
+import Exceptions.AuthException;
+import Exceptions.GeneralException;
+import Services.BalanceAccount.SWBalanceAccountService;
+import Utils.Responses.BalanceAccount.BalanceAcctResponse;
+import java.io.IOException;
+import java.util.UUID;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+public class ExampleReadme {
+
+ public static void main(String[] args) {
+
+ try {
+ //Intancia del servicio de Consulta de saldo y autenticación con Token
+ SWBalanceAccountService sdk = new SWBalanceAccountService("T2lYQ0t4L0R...", "https://api.test.sw.com.mx");
+ BalanceAcctResponse response = null;
+ response = (BalanceAcctResponse) sdk.GetUserBalanceAccount(UUID.fromString("828f19b1-77dc-48bc-9cfa-d48b5cf7e30c"));
+
+ //Imprimimos los datos de la respuesta que se obtuvo
+ System.out.println(response.Status);
+ System.out.println(response.HttpStatusCode);
+ System.out.println(response.idUserBalance);
+ System.out.println(response.idUser);
+ System.out.println(response.stampsBalance);
+ System.out.println(response.stampsUsed);
+ System.out.println(response.expirationDate);
+ System.out.println(response.isUnlimited);
+ System.out.println(response.stampsAssigned);
+ if (response.lastTransaction != null) {
+ System.out.println("Folio: " + response.lastTransaction.folio);
+ System.out.println("ID Usuario: " + response.lastTransaction.idUser);
+ System.out.println("ID Usuario Receptor: " + response.lastTransaction.idUserReceiver);
+ System.out.println("Nombre Receptor: " + response.lastTransaction.nameReceiver);
+ System.out.println("Stamps In: " + response.lastTransaction.stampsIn);
+ System.out.println("Stamps Out: "
+ + (response.lastTransaction.stampsOut != null ? response.lastTransaction.stampsOut : "null"));
+ System.out.println("Stamps Current: " + response.lastTransaction.stampsCurrent);
+ System.out.println("Comentario: " + response.lastTransaction.comment);
+ System.out.println("Fecha: " + response.lastTransaction.date);
+ System.out.println("Email Enviado: " + response.lastTransaction.isEmailSent);
+ } else {
+ System.out.println("No hay transacción disponible.");
+ }
+ //En caso de obtener error, este puede obtenerse de los siguientes campos
+ System.out.println(response.message);
+ System.out.println(response.messageDetail);
+ } catch (AuthException ex) {
+ System.out.println(ex);
+ } catch (GeneralException ex) {
+ Logger.getLogger(ExampleReadme.class.getName()).log(Level.SEVERE, null, ex);
+ } catch (IOException ex) {
+ Logger.getLogger(ExampleReadme.class.getName()).log(Level.SEVERE, null, ex);
+ }
+ }
+}
+
+```
+
+**Ejemplo de consumo de la libreria para consultar el saldo de un usuario específico utilizando Usuario y Contraseña**
+
+```java
+package com.mycompany.examplereadme;
+
+import Exceptions.AuthException;
+import Exceptions.GeneralException;
+import Services.BalanceAccount.SWBalanceAccountService;
+import Utils.Responses.BalanceAccount.BalanceAcctResponse;
+import java.io.IOException;
+import java.util.UUID;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+public class ExampleReadme {
+
+ public static void main(String[] args) {
+
+ try {
+ //Intancia del servicio de Consulta de saldo y autenticación con Usuario y Contraseña
+ SWBalanceAccountService sdk = new SWBalanceAccountService("user", "password", "https://services.test.sw.com.mx", "https://api.test.sw.com.mx");
+ BalanceAcctResponse response = null;
+ response = (BalanceAcctResponse) sdk.GetUserBalanceAccount(UUID.fromString("828f19b1-77dc-48bc-9cfa-d48b5cf7e30c"));
+
+ //Imprimimos los datos de la respuesta que se obtuvo
+ System.out.println(response.Status);
+ System.out.println(response.HttpStatusCode);
+ System.out.println(response.idUserBalance);
+ System.out.println(response.idUser);
+ System.out.println(response.stampsBalance);
+ System.out.println(response.stampsUsed);
+ System.out.println(response.expirationDate);
+ System.out.println(response.isUnlimited);
+ System.out.println(response.stampsAssigned);
+ if (response.lastTransaction != null) {
+ System.out.println("Folio: " + response.lastTransaction.folio);
+ System.out.println("ID Usuario: " + response.lastTransaction.idUser);
+ System.out.println("ID Usuario Receptor: " + response.lastTransaction.idUserReceiver);
+ System.out.println("Nombre Receptor: " + response.lastTransaction.nameReceiver);
+ System.out.println("Stamps In: " + response.lastTransaction.stampsIn);
+ System.out.println("Stamps Out: "
+ + (response.lastTransaction.stampsOut != null ? response.lastTransaction.stampsOut : "null"));
+ System.out.println("Stamps Current: " + response.lastTransaction.stampsCurrent);
+ System.out.println("Comentario: " + response.lastTransaction.comment);
+ System.out.println("Fecha: " + response.lastTransaction.date);
+ System.out.println("Email Enviado: " + response.lastTransaction.isEmailSent);
+ } else {
+ System.out.println("No hay transacción disponible.");
+ }
+ //En caso de obtener error, este puede obtenerse de los siguientes campos
+ System.out.println(response.message);
+ System.out.println(response.messageDetail);
+ } catch (AuthException ex) {
+ System.out.println(ex);
+ } catch (GeneralException ex) {
+ Logger.getLogger(ExampleReadme.class.getName()).log(Level.SEVERE, null, ex);
+ } catch (IOException ex) {
+ Logger.getLogger(ExampleReadme.class.getName()).log(Level.SEVERE, null, ex);
+ }
+ }
+}
+
+```
+
+
Agregar timbres
@@ -2479,7 +2817,7 @@ namespace ExampleReadme
Emisión Timbrado (IssueV4)
**Ejemplo del consumo de la librería para el servicio IssueV4 (PDF) Json en formato string mediante usuario y contraseña.**
-```cs
+```java
import Services.Issue.SWIssueService;
import Utils.Responses.Stamp.SuccessV1Response;
@@ -2546,7 +2884,72 @@ public class ExampleReadme {
SWIssueServiceV4 stamp = new SWIssueServiceV4("tokenUser", "http://services.test.sw.com.mx");
```
-----------------
+
+# Timbrado Retenciones #
+Timbrado Retenciones
+
+
Recibe el contenido de un XML ya emitido (sellado) en formato String, posteriormente si la factura y el token son correctos devuelve el CFDI timbrado, en caso contrario lanza una excepción.
+
+Este método recibe los siguientes parámetros:
+* Archivo en formato **String** ó **Base64**
+* Usuario y contraseña ó Token
+* Url Servicios SW
+
+**Ejemplo de consumo de la librería para timbrar XML en formato string utilizando usuario y contraseña**
+```java
+import Utils.Responses.StampRetention.SuccessV3Response;
+import Services.StampRetention.SWStampRetentionService;
+
+public class ExampleReadme {
+ public static void main(String[] args) {
+ try {
+ // Inicializar el objeto con la información de la cuenta y especifica la URL base para acceder al entorno deseado
+ SWStampRetentionService api = new SWStampRetentionService("user", "password", "http://services.test.sw.com.mx");
+ // Inicializar un objeto de respuesta para almacenar la respuesta
+ SuccessV3Response response = null;
+ //Se llama al método StampRetention y se envia el xml y versión de respuesta
+ response = (SuccessV3Response) api.StampRetention(stringXML, "v3");
+ // En response se mostrará la informacion de respuesta del servicio
+ System.out.println(response.Status);
+ System.out.println(response.HttpStatusCode);
+ System.out.println(response.retencion);
+ } catch (Exception e) {
+ e.printStackTrace();
+ }
+ }
+}
+```
+
+**Ejemplo de consumo de la librería para timbrar XML en formato string utilizando token** [¿Como obtener token?](http://developers.sw.com.mx/knowledge-base/generar-un-token-infinito/)
+```java
+import Utils.Responses.StampRetention.SuccessV3Response;
+import Services.StampRetention.SWStampRetentionService;
+
+public class ExampleReadme {
+ public static void main(String[] args) {
+ try {
+ // Inicializar el objeto con la información del token de acceso y especifica la URL base para acceder al entorno deseado
+ SWStampRetentionService api = new SWStampRetentionService("tokenUser", "http://services.test.sw.com.mx");
+ // Inicializar un objeto de respuesta para almacenar la respuesta
+ SuccessV3Response response = null;
+ //Se llama al método StampRetention y se envia el xml y versión de respuesta
+ response = (SuccessV3Response) api.StampRetention(stringXML, "v3");
+ // En response se mostrará la informacion de respuesta del servicio
+ System.out.println(response.Status);
+ System.out.println(response.HttpStatusCode);
+ System.out.println(response.retencion);
+ } catch (Exception e) {
+ e.printStackTrace();
+ }
+ }
+}
+```
+
+