Added payroll support

Author: Anidem1995

CLAUDE.md

@@ -0,0 +1,82 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Official Java SDK for FiscalAPI - a Mexican CFDI electronic invoicing service (SAT integration). Provides CFDI 4.0 invoicing, certificate management, mass downloads, payroll, and SAT catalog queries.
+
+## Build Commands
+
+```bash
+mvn clean compile          # Compile
+mvn test                   # Run tests
+mvn package                # Create JAR
+mvn clean deploy -Prelease # Deploy to Maven Central (requires GPG)
+```
+
+## Architecture
+
+### Entry Point
+`FiscalApiClient.create(FiscalApiSettings)` - Factory method creating the main client with all services.
+
+### Service Layer Pattern
+```
+IFiscalApiClient (facade)
+  ├── getInvoiceService()      → IInvoiceService extends IFiscalApiService<Invoice>
+  ├── getPersonService()       → IPersonService extends IFiscalApiService<Person>
+  ├── getProductService()      → IProductService extends IFiscalApiService<Product>
+  ├── getTaxFileService()      → ITaxFileService extends IFiscalApiService<TaxFile>
+  ├── getCatalogService()      → ICatalogService extends IFiscalApiService<CatalogDto>
+  └── ... (other services)
+```
+
+### Generic CRUD Base
+All services extend `BaseFiscalApiService<T>` which implements standard CRUD:
+- `getList(pageNumber, pageSize)` → `ApiResponse<PagedList<T>>`
+- `getById(id, details)` → `ApiResponse<T>`
+- `create(model)` → `ApiResponse<T>`
+- `update(model)` → `ApiResponse<T>`
+- `delete(id)` → `ApiResponse<Boolean>`
+
+Subclasses must implement `getTypeParameterClass()` to return the entity type for Jackson deserialization.
+
+### DTO Hierarchy
+```
+SerializableDto → AuditableDto (createdAt, updatedAt) → BaseDto (id)
+```
+All models extend `BaseDto`. Responses wrapped in `ApiResponse<T>`.
+
+### HTTP Layer
+- `OkHttpClientFactory` - Creates/caches OkHttpClient instances with auth headers (X-API-KEY, X-TENANT-KEY, X-API-VERSION, X-TIMEZONE)
+- `FiscalApiHttpClient` - Wraps OkHttp with Jackson, handles request/response logging in debug mode
+
+### Key Packages
+- `abstractions/` - Service interfaces
+- `common/` - ApiResponse, PagedList, settings
+- `http/` - HTTP client implementation
+- `models/` - All DTOs (invoicing/, downloading/ subpackages)
+- `services/` - Service implementations
+
+## Configuration
+
+```java
+FiscalApiSettings settings = new FiscalApiSettings();
+settings.setApiUrl("https://test.fiscalapi.com");  // or https://live.fiscalapi.com
+settings.setApiKey("sk_test_...");
+settings.setTenant("...");
+settings.setDebugMode(true);  // Logs requests/responses
+FiscalApiClient client = FiscalApiClient.create(settings);
+```
+
+## API Endpoint Pattern
+
+`{apiUrl}/api/{apiVersion}/{resource}/{id?}/{action?}`
+
+Example: `POST api/v4/invoices`, `GET api/v4/invoices/{id}?details=true`
+
+## Dependencies
+
+- OkHttp3 4.12.0 (HTTP)
+- Jackson 2.14.2 (JSON)
+- Java 8+ (source/target)

pom.xml

@@ -7,7 +7,7 @@
     <!-- Coordenadas del proyecto -->
     <groupId>com.fiscalapi</groupId>
     <artifactId>fiscalapi</artifactId>
-    <version>4.0.273</version>
+    <version>4.0.306</version>
     <name>${project.groupId}:${project.artifactId}</name>
     <description>Genera facturas CFDI válidas ante el SAT consumiendo la API de https://www.fiscalapi.com</description>
     <url>https://www.fiscalapi.com</url>
@@ -97,7 +97,7 @@
                 <executions>
                     <execution>
                         <id>sign-artifacts</id>
-                        <phase>verify</phase>
+                        <phase>vegpghrify</phase>
                         <goals>
                             <goal>sign</goal>
                         </goals>

src/main/java/com/fiscalapi/OptUtil.java

@@ -0,0 +1,31 @@
+package com.fiscalapi;
+
+import java.time.LocalDateTime;
+import java.time.ZonedDateTime;
+import java.time.format.DateTimeParseException;
+
+import static com.fiscalapi.models.invoicing.InvoiceConstants.SAT_DATE_FORMAT_IN;
+
+public class OptUtil {
+    public static LocalDateTime formatInputDateToSATFormat(String stringDate) {
+        LocalDateTime parsedDate = LocalDateTime.MIN;
+        if (stringDate == null || stringDate.isEmpty()) {
+            return parsedDate;
+        }
+
+        try {
+            // Intenta primero parsearlo como LocalDateTime
+            parsedDate = LocalDateTime.parse(stringDate, SAT_DATE_FORMAT_IN);
+        } catch (DateTimeParseException e) {
+            try {
+                // Si falla, intenta parsearlo como ZonedDateTime y convertirlo a LocalDateTime
+                ZonedDateTime zdt = ZonedDateTime.parse(stringDate);
+                parsedDate = zdt.toLocalDateTime();
+            } catch (DateTimeParseException e2) {
+                throw new IllegalArgumentException("Formato de fecha inválido: " + stringDate +
+                        " (debe ser compatible con el formato yyyy-MM-ddTHH:mm:ss)", e);
+            }
+        }
+        return parsedDate;
+    }
+}

src/main/java/com/fiscalapi/abstractions/IFiscalApiClient.java

@@ -10,5 +10,6 @@ public interface IFiscalApiClient {
     IDownloadCatalogService getDownloadCatalogService();
     IDownloadRuleService getDownloadRuleService();
     IDownloadRequestService getDownloadRequestService();
+    IStampService getStampService();
     // ... etc
 }

src/main/java/com/fiscalapi/abstractions/IPersonService.java

@@ -1,12 +1,16 @@
 package com.fiscalapi.abstractions;
 
 import com.fiscalapi.models.Person;
+import com.fiscalapi.services.EmployeeService;
+import com.fiscalapi.services.EmployerService;
 
 /**
  * Define el contrato específico para operaciones con "Person".
  * Hereda las operaciones básicas (CRUD) de IFiscalApiService<Person>.
  */
 public interface IPersonService extends IFiscalApiService<Person> {
+    EmployerService employer = null;
 
-    // other specific methods
+    EmployeeService getEmployeeService();
+    EmployerService getEmployerService();
 }

src/main/java/com/fiscalapi/abstractions/IStampService.java

@@ -0,0 +1,10 @@
+package com.fiscalapi.abstractions;
+
+import com.fiscalapi.common.ApiResponse;
+import com.fiscalapi.models.StampTransaction;
+import com.fiscalapi.models.StampTransactionParams;
+
+public interface IStampService extends IFiscalApiService<StampTransaction>{
+    ApiResponse<Boolean> TransferStamps(StampTransactionParams requestModel);
+    ApiResponse<Boolean> WithdrawStamps(StampTransactionParams requestModel);
+}

src/main/java/com/fiscalapi/models/Person.java

@@ -23,8 +23,8 @@ public class Person extends BaseDto {
     private String zipCode;
     private String base64Photo;
     private String taxPassword;
-    private Double availableBalance;
-    private Double committedBalance;
+    private java.math.BigDecimal availableBalance;
+    private java.math.BigDecimal committedBalance;
     private String tenantId;
 //    private String phoneNumber;
 //    private LocalDateTime validTo;
@@ -146,19 +146,19 @@ public void setTaxPassword(String taxPassword) {
         this.taxPassword = taxPassword;
     }
 
-    public Double getAvailableBalance() {
+    public java.math.BigDecimal getAvailableBalance() {
         return availableBalance;
     }
 
-    public void setAvailableBalance(Double availableBalance) {
+    public void setAvailableBalance(java.math.BigDecimal availableBalance) {
         this.availableBalance = availableBalance;
     }
 
-    public Double getCommittedBalance() {
+    public java.math.BigDecimal getCommittedBalance() {
         return committedBalance;
     }
 
-    public void setCommittedBalance(Double committedBalance) {
+    public void setCommittedBalance(java.math.BigDecimal committedBalance) {
         this.committedBalance = committedBalance;
     }
 
@@ -169,4 +169,4 @@ public String getTenantId() {
     public void setTenantId(String tenantId) {
         this.tenantId = tenantId;
     }
-}
+}

src/main/java/com/fiscalapi/models/Product.java

@@ -29,7 +29,7 @@ public class Product extends BaseDto {
     /**
      * Precio unitario del producto sin impuestos (requerido).
      */
-    private double unitPrice;
+    private java.math.BigDecimal unitPrice;
 
     /**
      * Código de la unidad de medida. Catálogo del SAT c_ClaveUnidad.
@@ -101,7 +101,7 @@ public void setDescription(String description) {
      *
      * @return el precio unitario.
      */
-    public double getUnitPrice() {
+    public java.math.BigDecimal getUnitPrice() {
         return unitPrice;
     }
 
@@ -110,7 +110,7 @@ public double getUnitPrice() {
      *
      * @param unitPrice el precio unitario a establecer.
      */
-    public void setUnitPrice(double unitPrice) {
+    public void setUnitPrice(java.math.BigDecimal unitPrice) {
         this.unitPrice = unitPrice;
     }
 

src/main/java/com/fiscalapi/models/ProductTax.java

@@ -31,7 +31,7 @@ public class ProductTax extends BaseDto {
     /**
      * Tasa del impuesto. El valor debe estar entre 0.00000 y 1.000000 (ej: 0.160000).
      */
-    private double rate;
+    private java.math.BigDecimal rate;
 
     /**
      * Código del impuesto según el catálogo del SAT (valores: "001", "002", "003").
@@ -93,7 +93,7 @@ public void setProductId(String productId) {
      *
      * @return la tasa del impuesto.
      */
-    public double getRate() {
+    public java.math.BigDecimal getRate() {
         return rate;
     }
 
@@ -102,7 +102,7 @@ public double getRate() {
      *
      * @param rate la tasa a establecer.
      */
-    public void setRate(double rate) {
+    public void setRate(java.math.BigDecimal rate) {
         this.rate = rate;
     }
 

src/main/java/com/fiscalapi/models/StampTransaction.java

@@ -0,0 +1,70 @@
+package com.fiscalapi.models;
+
+import com.fiscalapi.common.BaseDto;
+
+public class StampTransaction extends BaseDto {
+    private int consecutive;
+
+    public int getConsecutive() {
+        return consecutive;
+    }
+
+    public void setConsecutive(int consecutive) {
+        this.consecutive = consecutive;
+    }
+
+    public UserLookupDto getFromPerson() {
+        return fromPerson;
+    }
+
+    public void setFromPerson(UserLookupDto fromPerson) {
+        this.fromPerson = fromPerson;
+    }
+
+    public UserLookupDto getToPerson() {
+        return toPerson;
+    }
+
+    public void setToPerson(UserLookupDto toPerson) {
+        this.toPerson = toPerson;
+    }
+
+    public int getAmount() {
+        return amount;
+    }
+
+    public void setAmount(int amount) {
+        this.amount = amount;
+    }
+
+    public int getTransactionType() {
+        return transactionType;
+    }
+
+    public void setTransactionType(int transactionType) {
+        this.transactionType = transactionType;
+    }
+
+    public String getReferenceId() {
+        return referenceId;
+    }
+
+    public void setReferenceId(String referenceId) {
+        this.referenceId = referenceId;
+    }
+
+    public String getComments() {
+        return comments;
+    }
+
+    public void setComments(String comments) {
+        this.comments = comments;
+    }
+
+    private UserLookupDto fromPerson;
+    private UserLookupDto toPerson;
+    private int amount;
+    private int transactionType;
+    private String referenceId;
+    private String comments;
+}