Fix/fix technical debt and add missing payroll classes

Abstractions/IEmployeeService.cs

@@ -0,0 +1,18 @@
+using System.Threading.Tasks;
+using Fiscalapi.Common;
+using Fiscalapi.Models;
+
+namespace Fiscalapi.Abstractions
+{
+    /// <summary>
+    /// Interfaz para el servicio de Empleado — gestiona los datos del empleado anidados bajo una Persona.
+    /// Patrón de endpoint: api/{version}/people/{personId}/employee
+    /// </summary>
+    public interface IEmployeeService
+    {
+        Task<ApiResponse<EmployeeData>> GetByIdAsync(string id);
+        Task<ApiResponse<EmployeeData>> CreateAsync(EmployeeData requestModel);
+        Task<ApiResponse<EmployeeData>> UpdateAsync(EmployeeData requestModel);
+        Task<ApiResponse<bool>> DeleteAsync(string id);
+    }
+}

Abstractions/IEmployerService.cs

@@ -0,0 +1,18 @@
+using System.Threading.Tasks;
+using Fiscalapi.Common;
+using Fiscalapi.Models;
+
+namespace Fiscalapi.Abstractions
+{
+    /// <summary>
+    /// Interfaz para el servicio de Empleador — gestiona los datos del empleador anidados bajo una Persona.
+    /// Patrón de endpoint: api/{version}/people/{personId}/employer
+    /// </summary>
+    public interface IEmployerService
+    {
+        Task<ApiResponse<EmployerData>> GetByIdAsync(string id);
+        Task<ApiResponse<EmployerData>> CreateAsync(EmployerData requestModel);
+        Task<ApiResponse<EmployerData>> UpdateAsync(EmployerData requestModel);
+        Task<ApiResponse<bool>> DeleteAsync(string id);
+    }
+}

Abstractions/IPersonService.cs

@@ -1,5 +1,4 @@
 using Fiscalapi.Models;
-using Fiscalapi.Services;
 
 namespace Fiscalapi.Abstractions
 {
@@ -8,7 +7,7 @@ namespace Fiscalapi.Abstractions
     /// </summary>
     public interface IPersonService : IFiscalApiService<Person>
     {
-        EmployerService Employer {  get; }
-        EmployeeService Employee { get; }
+        IEmployerService Employer { get; }
+        IEmployeeService Employee { get; }
     }
 }

Models/Payroll.cs

@@ -61,13 +61,27 @@ public class PayrollRetirement
         public decimal NonAccumulableIncome { get; set; }
     }
 
+    public class PayrollStockOptions
+    {
+        /// <summary>
+        /// Valor de mercado de las acciones o títulos valor al momento de ejercer la opción.
+        /// </summary>
+        public decimal MarketPrice { get; set; }
+
+        /// <summary>
+        /// Precio pactado al otorgarse la opción de ingresos en acciones o títulos valor.
+        /// </summary>
+        public decimal GrantPrice { get; set; }
+    }
+
     public class PayrollEarning
     {
         public string EarningTypeCode { get; set; }
         public string Code { get; set; }
         public string Concept { get; set; }
         public decimal TaxedAmount { get; set; }
         public decimal ExemptAmount { get; set; }
+        public PayrollStockOptions StockOptions { get; set; }
         public List<PayrollEarningOvertime> Overtime { get; set; }
     }
 

README.md

@@ -13,7 +13,8 @@
 - **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
@@ -35,6 +36,11 @@
 - **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 organización según tus reglas de negocio.
 
 ## 🛍️ Gestión de Productos/Servicios
 - **Gestión de productos y servicios** con catálogo personalizable
@@ -45,7 +51,7 @@
 - **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
-  
+
 ## 📖 Recursos Adicionales
 - **Cientos de ejemplos de código** disponibles en múltiples lenguajes de programación
 - Documentación completa con guías paso a paso

Services/EmployeeService.cs

@@ -1,50 +1,63 @@
-using Fiscalapi.Common;
+using Fiscalapi.Abstractions;
+using Fiscalapi.Common;
 using Fiscalapi.Http;
 using Fiscalapi.Models;
+using System;
 using System.Threading.Tasks;
 
 namespace Fiscalapi.Services
 {
-    public class EmployeeService
+    public class EmployeeService : IEmployeeService
     {
         private IFiscalApiHttpClient HttpClient { get; }
-        private string baseEndpoint = "api/v4/people";
+        private readonly string _baseEndpoint;
 
-        public EmployeeService(IFiscalApiHttpClient fiscalApiHttpClient)
+        public EmployeeService(IFiscalApiHttpClient fiscalApiHttpClient, string apiVersion)
         {
             HttpClient = fiscalApiHttpClient;
+            _baseEndpoint = $"api/{apiVersion}/people";
         }
 
-        // GET /api/v4/people/{personId}/employee
+        private string BuildEndpoint(string personId)
+            => $"{_baseEndpoint}/{personId}/employee";
+
+        // GET /api/{version}/people/{personId}/employee
         public async Task<ApiResponse<EmployeeData>> GetByIdAsync(string id)
         {
-            string endpoint = $"{baseEndpoint}/{id}/employee";
-
-            return await HttpClient.GetAsync<EmployeeData>(endpoint);
+            if (string.IsNullOrWhiteSpace(id))
+                throw new ArgumentException("Employee person ID is required to build endpoint", nameof(id));
+            return await HttpClient.GetAsync<EmployeeData>(BuildEndpoint(id));
         }
 
-        //POST /api/v4/people/{personId}/employee
+        // POST /api/{version}/people/{personId}/employee
         public async Task<ApiResponse<EmployeeData>> CreateAsync(EmployeeData requestModel)
         {
-            string endpoint = $"{baseEndpoint}/{requestModel.EmployeePersonId}/employee";
-
-            return await HttpClient.PostAsync<EmployeeData>(endpoint, requestModel);
+            ValidateRequestModel(requestModel);
+            return await HttpClient.PostAsync<EmployeeData>(BuildEndpoint(requestModel.EmployeePersonId), requestModel);
         }
 
-        // PUT /api/v4/people/{personId}/employee
+        // PUT /api/{version}/people/{personId}/employee
         public async Task<ApiResponse<EmployeeData>> UpdateAsync(EmployeeData requestModel)
         {
-            string endpoint = $"{baseEndpoint}/{requestModel.EmployeePersonId}/employee";
-
-            return await HttpClient.PutAsync<EmployeeData>(endpoint, requestModel);
+            ValidateRequestModel(requestModel);
+            return await HttpClient.PutAsync<EmployeeData>(BuildEndpoint(requestModel.EmployeePersonId), requestModel);
         }
 
-        // DELETE /api/v4/people/{personId}/employee
+        // DELETE /api/{version}/people/{personId}/employee
         public async Task<ApiResponse<bool>> DeleteAsync(string id)
         {
-            string endpoint = $"{baseEndpoint}/{id}/employee";
+            if (string.IsNullOrWhiteSpace(id))
+                throw new ArgumentException("El ID de la persona requerido", nameof(id));
+            return await HttpClient.DeleteAsync(BuildEndpoint(id));
+        }
+
+        private void ValidateRequestModel(EmployeeData requestModel)
+        {
+            if (requestModel == null)
+                throw new ArgumentNullException(nameof(requestModel), "El modelo de solicitud no puede ser nulo");
 
-            return await HttpClient.DeleteAsync(endpoint);
+            if (string.IsNullOrWhiteSpace(requestModel.EmployeePersonId))
+                throw new ArgumentException("Se requiere el ID de la persona para crear o actualizar los datos del empleado", nameof(requestModel.EmployeePersonId));
         }
     }
 }

Services/EmployerService.cs

@@ -1,50 +1,63 @@
-using Fiscalapi.Common;
+using Fiscalapi.Abstractions;
+using Fiscalapi.Common;
 using Fiscalapi.Http;
 using Fiscalapi.Models;
+using System;
 using System.Threading.Tasks;
 
 namespace Fiscalapi.Services
 {
-    public class EmployerService
+    public class EmployerService : IEmployerService
     {
         private IFiscalApiHttpClient HttpClient { get; }
-        private string baseEndpoint = "api/v4/people";
+        private readonly string _baseEndpoint;
 
-        public EmployerService(IFiscalApiHttpClient fiscalApiHttpClient)
+        public EmployerService(IFiscalApiHttpClient fiscalApiHttpClient, string apiVersion)
         {
             HttpClient = fiscalApiHttpClient;
+            _baseEndpoint = $"api/{apiVersion}/people";
         }
 
-        // GET /api/v4/people/{personId}/employer
+        private string BuildEndpoint(string personId)
+            => $"{_baseEndpoint}/{personId}/employer";
+
+        // GET /api/{version}/people/{personId}/employer
         public async Task<ApiResponse<EmployerData>> GetByIdAsync(string id)
         {
-            string endpoint = $"{baseEndpoint}/{id}/employer";
-
-            return await HttpClient.GetAsync<EmployerData>(endpoint);
+            if (string.IsNullOrWhiteSpace(id))
+                throw new ArgumentException("Person ID is required to build endpoint", nameof(id));
+            return await HttpClient.GetAsync<EmployerData>(BuildEndpoint(id));
         }
 
-        //POST /api/v4/people/{personId}/employer
+        // POST /api/{version}/people/{personId}/employer
         public async Task<ApiResponse<EmployerData>> CreateAsync(EmployerData requestModel)
         {
-            string endpoint = $"{baseEndpoint}/{requestModel.PersonId}/employer";
-
-            return await HttpClient.PostAsync<EmployerData>(endpoint, requestModel);
+            ValidateRequestModel(requestModel);
+            return await HttpClient.PostAsync<EmployerData>(BuildEndpoint(requestModel.PersonId), requestModel);
         }
 
-        // PUT /api/v4/people/{personId}/employer
+        // PUT /api/{version}/people/{personId}/employer
         public async Task<ApiResponse<EmployerData>> UpdateAsync(EmployerData requestModel)
         {
-            string endpoint = $"{baseEndpoint}/{requestModel.PersonId}/employer";
-
-            return await HttpClient.PutAsync<EmployerData>(endpoint, requestModel);
+            ValidateRequestModel(requestModel);
+            return await HttpClient.PutAsync<EmployerData>(BuildEndpoint(requestModel.PersonId), requestModel);
         }
 
-        // DELETE /api/v4/people/{personId}/employer
+        // DELETE /api/{version}/people/{personId}/employer
         public async Task<ApiResponse<bool>> DeleteAsync(string id)
         {
-            string endpoint = $"{baseEndpoint}/{id}/employer";
+            if (string.IsNullOrWhiteSpace(id))
+                throw new ArgumentException("El ID de la persona requerido", nameof(id));
+            return await HttpClient.DeleteAsync(BuildEndpoint(id));
+        }
+
+        private void ValidateRequestModel(EmployerData requestModel)
+        {
+            if (requestModel == null)
+                throw new ArgumentNullException(nameof(requestModel), "El modelo de solicitud no puede ser nulo");
 
-            return await HttpClient.DeleteAsync(endpoint);
+            if (string.IsNullOrWhiteSpace(requestModel.PersonId))
+                throw new ArgumentException("Se requiere el ID de la persona para crear o actualizar los datos del empleador", nameof(requestModel.PersonId));
         }
     }
 }

Services/PersonService.cs

@@ -6,14 +6,14 @@ namespace Fiscalapi.Services
 {
     public class PersonService : BaseFiscalApiService<Person>, IPersonService
     {
-        public EmployerService Employer { get; }
-        public EmployeeService Employee { get; }
+        public IEmployerService Employer { get; }
+        public IEmployeeService Employee { get; }
 
         public PersonService(IFiscalApiHttpClient httpClient, string apiVersion)
             : base(httpClient, "people", apiVersion)
         {
-            Employer = new EmployerService(httpClient);
-            Employee = new EmployeeService(httpClient);
+            Employer = new EmployerService(httpClient, apiVersion);
+            Employee = new EmployeeService(httpClient, apiVersion);
         }
     }
 }

Services/StampService.cs

@@ -2,6 +2,7 @@
 using Fiscalapi.Common;
 using Fiscalapi.Http;
 using Fiscalapi.Models;
+using System;
 using System.Threading.Tasks;
 
 namespace Fiscalapi.Services
@@ -15,12 +16,29 @@ public StampService(IFiscalApiHttpClient httpClient, string apiVersion)
 
         public async Task<ApiResponse<bool>> TransferStamps(StampTransactionParams requestModel)
         {
+            ValidateRequest(requestModel);
             return await HttpClient.PostAsync<bool>(BuildEndpoint(), requestModel);
         }
 
         public async Task<ApiResponse<bool>> WithdrawStamps(StampTransactionParams requestModel)
         {
+            ValidateRequest(requestModel);
             return await HttpClient.PostAsync<bool>(BuildEndpoint(), requestModel);
         }
+
+        private void ValidateRequest(StampTransactionParams requestModel)
+        {
+            if (requestModel == null)
+                throw new ArgumentNullException(nameof(requestModel), "No se acepta modelo de transaccion nulo");
+
+            if (string.IsNullOrWhiteSpace(requestModel.FromPersonId))
+                throw new ArgumentException("Se requiere el ID de la persona de origen para la transferencia de timbres", nameof(requestModel.FromPersonId));
+
+            if (string.IsNullOrWhiteSpace(requestModel.ToPersonId))
+                throw new ArgumentException("Se requiere el ID de la persona de destino para la transferencia de timbres", nameof(requestModel.ToPersonId));
+
+            if (requestModel.Amount <= 0)
+                throw new ArgumentException("La cantidad debe ser mayor que cero", nameof(requestModel.Amount));
+        }
     }
 }

fiscalapi-net.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <TargetFrameworks>netstandard2.0;net461;net48;netcoreapp3.1;net5.0;net6.0;net8.0</TargetFrameworks>
-	  <Version>4.0.360</Version>
+	  <Version>4.0.361</Version>
 	  <AssemblyVersion>$(Version)</AssemblyVersion>
 	  <FileVersion>$(Version)</FileVersion>
 	  <PackageVersion>$(Version)</PackageVersion>