Add StampService export and update documentation

- Add StampService to services/__init__.py exports
- Update CLAUDE.md with complete service list, example files, and new sections
- Add StampService documentation to payroll-requirements.md
- Update implementation checklist with completed items
- Bump version to 4.0.360

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: 2 people

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,12 +104,22 @@ 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
+
+- `examples.py` - General usage examples (all invoice types)
+- `ejemplos-facturas-de-nomina.py` - Payroll invoice examples (13 types)
+- `ejemplos-facturas-de-complemento-pago.py` - Payment complement examples
+- `ejemplos-timbres.py` - Stamp service examples
+
+## Reference Documentation
+
+- `payroll-requirements.md` - Detailed payroll implementation spec with all models, services, and SAT codes
+
 ## Dependencies
 
 - Python >= 3.9 (CI/CD uses Python 3.9.13)
@@ -102,7 +130,7 @@ See `examples.py` and README.md for detailed examples of both modes.
 ## Development Setup
 
 ```bash
-# Create virtual environment with Python 3.9.13
+# Create virtual environment with Python 3.9+
 python -m venv venv
 
 # Activate (Windows)
@@ -130,8 +158,15 @@ pip install -r requirements.txt
 - 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

fiscalapi/services/__init__.py

@@ -12,6 +12,7 @@
 from .invoice_service import InvoiceService
 from .people_service import PeopleService
 from .product_service import ProductService
+from .stamp_service import StampService
 from .tax_file_service import TaxFileService
 
 __all__ = [
@@ -27,5 +28,6 @@
     "InvoiceService",
     "PeopleService",
     "ProductService",
+    "StampService",
     "TaxFileService",
 ]

payroll-requirements.md

@@ -9,6 +9,10 @@ This document describes the requirements for implementing payroll invoice (CFDI
 1. [Overview](#overview)
 2. [New Models Required](#new-models-required)
 3. [New Services Required](#new-services-required)
+   - [EmployeeService](#1-employeeservice)
+   - [EmployerService](#2-employerservice)
+   - [PeopleService Updates](#3-peopleservice-updates)
+   - [StampService](#4-stampservice)
 4. [Person Model Updates](#person-model-updates)
 5. [Invoice Model Updates](#invoice-model-updates)
 6. [Two Operation Modes](#two-operation-modes)
@@ -248,6 +252,82 @@ client.people.employee  -> EmployeeService
 client.people.employer  -> EmployerService
 ```
 
+### 4. StampService
+
+Service for managing stamp transactions (timbres fiscales). Stamps are the digital fiscal tokens required to certify CFDI invoices.
+
+```
+Endpoint pattern: stamps
+```
+
+| Method | HTTP | Endpoint | Description |
+|--------|------|----------|-------------|
+| get_list(page_number, page_size) | GET | stamps?pageNumber={n}&pageSize={s} | List stamp transactions with pagination |
+| get_by_id(transaction_id) | GET | stamps/{transactionId} | Get a stamp transaction by ID |
+| transfer_stamps(request) | POST | stamps | Transfer stamps from one person to another |
+| withdraw_stamps(request) | POST | stamps | Withdraw stamps (alias for transfer_stamps) |
+
+#### Stamp Models
+
+##### UserLookupDto
+
+Lookup DTO for user/person references in stamp transactions.
+
+| Field | JSON Alias | Type | Description |
+|-------|------------|------|-------------|
+| tin | tin | string | RFC of the user |
+| legal_name | legalName | string | Legal name of the user |
+
+##### StampTransaction
+
+Represents a stamp transfer/withdrawal transaction.
+
+| Field | JSON Alias | Type | Description |
+|-------|------------|------|-------------|
+| consecutive | consecutive | int | Transaction consecutive number |
+| from_person | fromPerson | UserLookupDto | Source person of the transfer |
+| to_person | toPerson | UserLookupDto | Destination person of the transfer |
+| amount | amount | int | Number of stamps transferred |
+| transaction_type | transactionType | int | Type of transaction |
+| transaction_status | transactionStatus | int | Status of the transaction |
+| reference_id | referenceId | string | Transaction reference ID |
+| comments | comments | string | Transaction comments |
+
+##### StampTransactionParams
+
+Request parameters for stamp transfer/withdraw operations.
+
+| Field | JSON Alias | Type | Required | Description |
+|-------|------------|------|----------|-------------|
+| from_person_id | fromPersonId | string | Yes | ID of the source person |
+| to_person_id | toPersonId | string | Yes | ID of the destination person |
+| amount | amount | int | Yes | Number of stamps to transfer |
+| comments | comments | string | No | Transfer comments |
+
+#### Example: Transfer Stamps
+
+```
+// Transfer 100 stamps from master account to sub-account
+params = StampTransactionParams(
+  from_person_id: "master-account-id",
+  to_person_id: "sub-account-id",
+  amount: 100,
+  comments: "Monthly stamp allocation"
+)
+
+response = client.stamps.transfer_stamps(params)
+```
+
+#### Example: List Stamp Transactions
+
+```
+// Get paginated list of stamp transactions
+response = client.stamps.get_list(page_number=1, page_size=10)
+
+for transaction in response.data.items:
+  print(f"Transfer: {transaction.amount} stamps from {transaction.from_person.legal_name}")
+```
+
 ---
 
 ## Person Model Updates
@@ -475,6 +555,14 @@ POST /api/{version}/invoices
 
 With `type_code: "N"` for payroll invoices.
 
+### Stamp Endpoints
+
+```
+GET    /api/{version}/stamps?pageNumber={n}&pageSize={s}
+GET    /api/{version}/stamps/{transactionId}
+POST   /api/{version}/stamps
+```
+
 ---
 
 ## Field Mappings (JSON Aliases)
@@ -692,22 +780,33 @@ response = client.invoices.create(invoice)
 
 ## Implementation Checklist
 
-- [ ] Add `curp` field to Person model
-- [ ] Create EmployeeData model
-- [ ] Create EmployerData model
-- [ ] Create InvoiceIssuerEmployerData model
-- [ ] Create InvoiceRecipientEmployeeData model
-- [ ] Create PayrollComplement and all sub-models
-- [ ] Add employer_data to InvoiceIssuer model
-- [ ] Add employee_data to InvoiceRecipient model
-- [ ] Add payroll to InvoiceComplement model
-- [ ] Create EmployeeService with CRUD operations
-- [ ] Create EmployerService with CRUD operations
-- [ ] Add employee and employer properties to PeopleService
+### Models
+- [x] Add `curp` field to Person model
+- [x] Create EmployeeData model
+- [x] Create EmployerData model
+- [x] Create InvoiceIssuerEmployerData model
+- [x] Create InvoiceRecipientEmployeeData model
+- [x] Create PayrollComplement and all sub-models
+- [x] Add employer_data to InvoiceIssuer model
+- [x] Add employee_data to InvoiceRecipient model
+- [x] Add payroll to InvoiceComplement model
+- [x] Create StampTransaction model
+- [x] Create StampTransactionParams model
+- [x] Create UserLookupDto model
+
+### Services
+- [x] Create EmployeeService with CRUD operations
+- [x] Create EmployerService with CRUD operations
+- [x] Add employee and employer properties to PeopleService
+- [x] Create StampService with get_list, get_by_id, transfer_stamps, withdraw_stamps
+
+### Examples & Testing
 - [ ] Create examples for all 13 payroll types (by values)
 - [ ] Create examples for all 13 payroll types (by references)
 - [ ] Create setup data methods for by-references mode
+- [ ] Create stamp service examples
 - [ ] Test all payroll types successfully
+- [ ] Test stamp transactions successfully
 
 ---
 

setup.py

@@ -2,7 +2,7 @@
 import os
 from setuptools import setup, find_packages
 
-VERSION = "4.0.270"
+VERSION = "4.0.360"
 
 DESCRIPTION = "Genera facturas CFDI válidas ante el SAT consumiendo el API de https://www.fiscalapi.com"