Merge pull request #4 from FiscalAPI/agrega-soporte-facturas-cfdi-nomina

Agrega soporte facturas cfdi nomina

Author: mendozagit

.github/workflows/CICD.yml

@@ -14,7 +14,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.9"
+          python-version: "3.9.13"
 
       - name: Install build dependencies
         run: |

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-FiscalAPI Python SDK - Official SDK for integrating with FiscalAPI, Mexico's electronic invoicing (CFDI 4.0) and fiscal services platform. Simplifies integration with SAT (Mexico's tax authority) for invoice creation, tax certificate management, and bulk downloads.
+FiscalAPI Python SDK - Official SDK for integrating with FiscalAPI, Mexico's electronic invoicing (CFDI 4.0) and fiscal services platform. Simplifies integration with SAT (Mexico's tax authority) for invoice creation, tax certificate management, payroll invoices (CFDI de Nomina), and bulk downloads.
 
 ## Build and Publish Commands
 
@@ -21,9 +21,12 @@ twine check dist/*
 
 # Publish to PyPI (requires PYPI_API_TOKEN)
 twine upload --username __token__ --password $PYPI_API_TOKEN dist/*
+
+# Clean build artifacts
+rm -rf dist build fiscalapi.egg-info
 ```
 
-**Version management:** Version is defined in `setup.py`. CI/CD requires the version to match the git tag (vX.Y.Z format).
+**Version management:** Version is defined in `setup.py` (line 5: `VERSION = "X.Y.Z"`). CI/CD is manually triggered via `workflow_dispatch`.
 
 ## Architecture
 
@@ -35,13 +38,16 @@ FiscalApiClient (Facade)
     ├── FiscalApiSettings (Configuration)
     │
     └── Services (all inherit from BaseService)
-        ├── invoice_service.py    → Invoice CRUD, PDF, XML, cancellation, SAT status
-        ├── people_service.py     → Person/entity management
-        ├── product_service.py    → Product/service catalog
-        ├── tax_file_servive.py   → CSD/FIEL certificate uploads
-        ├── api_key_service.py    → API key management
-        ├── catalog_service.py    → SAT catalog searches
-        └── download_*_service.py → Bulk download management
+        ├── invoice_service.py        → Invoice CRUD, PDF, XML, cancellation, SAT status
+        ├── people_service.py         → Person/entity management
+        │   ├── employee_service.py   → Employee data (sub-service for payroll)
+        │   └── employer_service.py   → Employer data (sub-service for payroll)
+        ├── product_service.py        → Product/service catalog
+        ├── tax_file_service.py       → CSD/FIEL certificate uploads
+        ├── api_key_service.py        → API key management
+        ├── catalog_service.py        → SAT catalog searches
+        ├── stamp_service.py          → Stamp (timbres) transactions
+        └── download_*_service.py     → Bulk download management
 ```
 
 **Entry Point Pattern:**
@@ -54,23 +60,35 @@ client = FiscalApiClient(settings=settings)
 # Access services through client
 client.invoices.create(invoice)
 client.people.get_list(page_num, page_size)
+client.stamps.get_list(page_num, page_size)
 ```
 
 ### Models (Pydantic v2)
 
 Located in `fiscalapi/models/`:
 - **common_models.py** - Base DTOs: `ApiResponse[T]`, `PagedList[T]`, `ValidationFailure`, `FiscalApiSettings`
-- **fiscalapi_models.py** - Domain models: `Invoice`, `Person`, `Product`, `TaxFile`, and related entities
+- **fiscalapi_models.py** - Domain models: `Invoice`, `Person`, `Product`, `TaxFile`, payroll complements, stamp transactions
 
 **Key Pattern - Field Aliasing:** Models use Pydantic `Field(alias="...")` for API JSON field mapping. When serializing, use `by_alias=True` and `exclude_none=True`.
 
+### Public API Exports
+
+All types are exported from the main package (`fiscalapi/__init__.py`):
+```python
+from fiscalapi import Invoice, Person, Product, FiscalApiClient, ApiResponse
+```
+
+Also available via submodules:
+```python
+from fiscalapi.models import Invoice, Person
+from fiscalapi.services import InvoiceService, StampService
+```
+
 ### Two Operation Modes
 
 1. **By References** - Use pre-created object IDs (faster, less data transfer)
 2. **By Values** - Send all field data directly (self-contained, no prior setup)
 
-See `examples.py` and README.md for detailed examples of both modes.
-
 ### Request/Response Flow
 
 1. Service method receives domain object
@@ -86,21 +104,73 @@ See `examples.py` and README.md for detailed examples of both modes.
 
 ## Key Files
 
-- `fiscalapi/__init__.py` - Central exports for all models and services
+- `fiscalapi/__init__.py` - Central exports for all 85 public types (models + services)
 - `fiscalapi/services/base_service.py` - HTTP client, serialization, response handling
 - `fiscalapi/services/fiscalapi_client.py` - Main client facade
-- `examples.py` - 3600+ lines of usage examples (commented out)
 - `setup.py` - Package metadata, version, and dependencies
 
+## Example Files
+
+All example files are located in the `examples/` directory:
+
+- `examples/examples.py` - General usage examples (all invoice types)
+- `examples/ejemplos-facturas-de-nomina.py` - Payroll invoice examples (13 types)
+- `examples/ejemplos-facturas-de-complemento-pago.py` - Payment complement examples
+- `examples/ejemplos-timbres.py` - Stamp service examples
+- `examples/ejemplos-factura-impuestos-locales-valores.py` - Local taxes examples (by values)
+- `examples/ejemplos-factura-impuestos-locales-referencias.py` - Local taxes examples (by references)
+
+## Reference Documentation
+
+- `payroll-requirements.md` - Detailed payroll implementation spec with all models, services, and SAT codes
+
 ## Dependencies
 
-- Python >= 3.7
+- Python >= 3.9 (CI/CD uses Python 3.9.13)
 - pydantic >= 2.0.0 (validation & serialization)
 - requests >= 2.0.0 (HTTP client)
 - email_validator >= 2.2.0
 
+## Development Setup
+
+```bash
+# Create virtual environment with Python 3.9+
+python -m venv venv
+
+# Activate (Windows)
+.\venv\Scripts\activate
+
+# Activate (Linux/Mac)
+source venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+## Code Standards
+
+### Pydantic v2 Compatibility
+
+- Use `model_config = ConfigDict(...)` instead of `class Config:`
+- Use `list[T]` and `dict[K,V]` (Python 3.9+ built-in generics) instead of `List[T]` and `Dict[K,V]`
+- Use `default_factory=list` for mutable defaults, never `default=[]`
+- All Field() calls should have explicit `default=...` for required fields
+
+### Type Annotations
+
+- All service methods must have return type annotations
+- Use `Optional[T]` only for truly optional fields
+- `ApiResponse[T]` supports any type T (not just BaseModel subclasses)
+
+### Adding New Services
+
+1. Create service class inheriting from `BaseService` in `fiscalapi/services/`
+2. Export from `fiscalapi/services/__init__.py`
+3. Export from `fiscalapi/__init__.py`
+4. Add property to `FiscalApiClient` class
+
 ## External Resources
 
 - API Documentation: https://docs.fiscalapi.com
 - Test Certificates: https://docs.fiscalapi.com/recursos/descargas
-- Postman Collection: Available in docs
+- Postman Collection: https://documenter.getpostman.com/view/4346593/2sB2j4eqXr

MANIFEST.in

@@ -0,0 +1,3 @@
+include fiscalapi/py.typed
+include README.md
+include LICENSE.txt

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** 
+- **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**
 - [Ejemplos en Python](https://github.com/FiscalAPI/fiscalapi-samples-python)
 
@@ -33,6 +34,12 @@
 - **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
@@ -43,7 +50,13 @@
 - **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
 - Documentación completa con guías paso a paso
@@ -306,12 +319,22 @@ else:
 
 ## 📋 Operaciones Principales
 
-- **Facturas (CFDI)**  
+- **Facturas (CFDI)**
   Crear facturas de ingreso, notas de crédito, complementos de pago, cancelaciones, generación de PDF/XML.
-- **Personas (Clientes/Emisores)**  
+- **Personas (Clientes/Emisores)**
   Alta y administración de personas, gestión de certificados (CSD).
-- **Productos y Servicios**  
+- **Productos y Servicios**
   Administración de catálogos de productos, búsqueda en catálogos SAT.
+- **Timbres**
+  Listar transacciones, transferir y retirar timbres entre personas.
+
+## 📂 Más Ejemplos
+
+- [Gestión de Timbres](examples/ejemplos-timbres.py)
+- [Complementos de Pago](examples/ejemplos-facturas-de-complemento-pago.py)
+- [Facturas de Nómina](examples/ejemplos-facturas-de-nomina.py)
+- [Impuestos Locales (Por Valores)](examples/ejemplos-factura-impuestos-locales-valores.py)
+- [Impuestos Locales (Por Referencias)](examples/ejemplos-factura-impuestos-locales-referencias.py)
 
 ## 🤝 Contribuir
 
@@ -337,11 +360,10 @@ Este proyecto está licenciado bajo la Licencia **MPL**. Consulta el archivo [LI
 - [Documentación Oficial](https://docs.fiscalapi.com)
 - [Como obtener mis credenciales](https://docs.fiscalapi.com/credentials-info)
 - [Portal de FiscalAPI](https://fiscalapi.com)
-- [Ejemplos en Python](https://github.com/FiscalAPI/fiscalapi-samples-python)
 - [Soporte técnico](https://fiscalapi.com/contact-us)
-- [Certificados prueba](https://docs.fiscalapi.com/tax-files-info)
+- [Certificados de prueba](https://docs.fiscalapi.com/tax-files-info)
 - [Postman Collection](https://documenter.getpostman.com/view/4346593/2sB2j4eqXr)
-- [SDKs](https://docs.fiscalapi.com/sdks)
+- [SDKs en otros lenguajes](https://docs.fiscalapi.com/sdks)
 ---
 
 Desarrollado con ❤️ por [Fiscalapi](https://www.fiscalapi.com)