Merge pull request #1 from FiscalAPI/feat/AddPayrollSupport

Feat/add 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)

README.md

@@ -10,14 +10,15 @@
 - **Soporte completo para CFDI 4.0** con todas las especificaciones oficiales
 - **Timbrado de facturas de ingreso** con validación automática
 - **Timbrado de notas de crédito** (facturas de egreso)
-- **Timbrado de complementos de pago** en MXN, USD y EUR.
+- **Timbrado de complementos de pago** en MXN, USD y EUR
+- **Timbrado de facturas de nómina** - Soporte para los 13 tipos de CFDI de nómina
 - **Consulta del estatus de facturas** en el SAT en tiempo real
 - **Cancelación de facturas** 
 - **Generación de archivos PDF** de las facturas con formato profesional
 - **Personalización de logos y colores** en los PDF generados
 - **Envío de facturas por correo electrónico** automatizado
 - **Descarga de archivos XML** con estructura completa
-- **Almacenamiento y recuperación** de facturas por 5 años.
+- **Almacenamiento y recuperación** de facturas por 5 años
 - Dos [modos de operación](https://docs.fiscalapi.com/modes-of-operation): **Por valores** o **Por referencias**
 
 ## 📥 Descarga Masiva
@@ -32,16 +33,29 @@
 - **Administración de personas** (emisores, receptores, clientes, usuarios, etc.)
 - **Gestión de certificados CSD y FIEL** (subir archivos .cer y .key a FiscalAPI)
 - **Configuración de datos fiscales** (RFC, domicilio fiscal, régimen fiscal)
+- **Datos de empleado** (agrega/actualiza/elimina datos de empleado a una persona. CFDI Nómina)
+- **Datos de empleador** (agrega/actualiza/elimina datos de empleador a una persona. CFDI Nómina)
+
+## 🎖️ Gestión de Timbres 
+- **Gestión de folios fiscales** Compra timbres a fiscalapi y transfiere/retira a las personas de tu organizacion segun tus reglas de negocio.
 
 ## 🛍️ Gestión de Productos/Servicios
 - **Gestión de productos y servicios** con catálogo personalizable
 - **Administración de impuestos aplicables** (IVA, ISR, IEPS)
+- **Timbres**
+  Listar transacciones, transferir y retirar timbres entre personas.
 
 ## 📚 Consulta de Catálogos SAT
 - **Consulta en catálogos oficiales del SAT** actualizados
 - **Consulta en catálogos oficiales de Descarga masiva del SAT** actualizados
 - **Búsqueda de información** en catálogos del SAT con filtros avanzados
 - **Acceso y búsqueda** en catálogos completos
+
+## 🎫 Gestión de Timbres
+- **Listar transacciones de timbres** con paginación
+- **Consultar transacciones** por ID
+- **Transferir timbres** entre personas
+- **Retirar timbres** de una persona
 
 ## 📖 Recursos Adicionales
 - **Cientos de ejemplos de código** disponibles en múltiples lenguajes de programación

pom.xml

@@ -7,7 +7,7 @@
     <!-- Coordenadas del proyecto -->
     <groupId>com.fiscalapi</groupId>
     <artifactId>fiscalapi</artifactId>
-    <version>4.0.273</version>
+    <version>4.0.360</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>