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

Agrega soporte facturas cfdi nomina

Author: mendozagit

.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run build:*)",
+      "Bash(npm test)",
+      "Bash(npx ts-node:*)",
+      "Bash(findstr:*)"
+    ],
+    "defaultMode": "bypassPermissions"
+  }
+}

.github/workflows/main.yml

@@ -46,10 +46,19 @@ jobs:
             echo "ESM build missing"
             exit 1
           fi
-          if [ ! -d "dist/types" ]; then
+          if [ ! -f "dist/cjs/index.d.ts" ]; then
             echo "TypeScript definitions missing"
             exit 1
           fi
+          if [ ! -f "dist/cjs/package.json" ]; then
+            echo "CJS package.json missing"
+            exit 1
+          fi
+          if [ ! -f "dist/esm/package.json" ]; then
+            echo "ESM package.json missing"
+            exit 1
+          fi
+          echo "Build artifacts verified successfully"
       
       - name: Publish to NPM
         run: npm publish --access public

CLAUDE.md

@@ -0,0 +1,67 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+FiscalAPI SDK for Node.js - Official TypeScript SDK for Mexican electronic invoicing (CFDI 4.0) and fiscal services. Wraps the FiscalAPI REST API for invoice creation, payment complements, bulk XML downloads, and SAT catalog queries.
+
+## Build Commands
+
+```bash
+npm run build          # Full build: clean + esm + cjs + types
+npm run build:esm      # TypeScript to ES Modules (dist/esm)
+npm run build:cjs      # TypeScript to CommonJS (dist/cjs)
+npm run build:types    # TypeScript declaration files (dist/types)
+npm run clean          # Remove dist directory
+npm test               # Run Jest tests
+npm run lint           # ESLint on src/**/*.ts
+npm run main           # Run examples/main.ts with ts-node
+```
+
+## Architecture
+
+**Facade Pattern**: `FiscalapiClient` is the main entry point exposing all services:
+- `invoices` - CFDI invoice creation, cancellation, PDF generation
+- `products` - Product/service catalog management
+- `persons` - Issuer/recipient (emisor/receptor) management
+- `taxFiles` - CSD certificate upload
+- `catalogs` - SAT catalog queries
+- `downloadCatalogs`, `downloadRules`, `downloadRequests` - Bulk XML download
+
+**Directory Structure**:
+- `src/abstractions/` - Service interfaces (I*Service)
+- `src/services/` - Service implementations extending `BaseFiscalapiService`
+- `src/models/` - Data models (Invoice, Person, Product, etc.)
+- `src/common/` - Shared DTOs (ApiResponse, PagedList, FiscalapiSettings)
+- `src/utils/` - Date formatting (Luxon), Base64 encoding, validation helpers
+
+**Key Patterns**:
+- All services implement interfaces from `abstractions/`
+- HTTP client injected via factory pattern
+- Dual-package output: ESM + CommonJS + TypeScript declarations
+- Date handling uses Luxon with `America/Mexico_City` timezone
+- SAT date format: `yyyy-MM-ddTHH:mm:ss`
+
+## Configuration
+
+```typescript
+const settings: FiscalapiSettings = {
+  apiUrl: "https://test.fiscalapi.com",  // or https://live.fiscalapi.com
+  apiKey: "<api_key>",
+  tenant: "<tenant>",
+  apiVersion?: "v4",                      // default
+  timeZone?: "America/Mexico_City",       // default
+  debug?: false
+};
+const client = FiscalapiClient.create(settings);
+```
+
+## Two Operation Modes
+
+1. **By References**: Send only IDs of pre-configured entities in FiscalAPI dashboard
+2. **By Values**: Send complete data in each request (no prior setup needed)
+
+## TypeScript Configuration
+
+Strict mode enabled with all checks: `noImplicitAny`, `strictNullChecks`, `noImplicitReturns`, `noUnusedParameters`. Target ES2018.

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** (CFDI Nómina 1.2)
 - **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**
 
 ## 📥 Descarga Masiva
@@ -32,11 +33,16 @@
 - **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 Productos/Servicios
 - **Gestión de productos y servicios** con catálogo personalizable
 - **Administración de impuestos aplicables** (IVA, ISR, IEPS)
 
+## 🎖️ 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.
+
 ## 📚 Consulta de Catálogos SAT
 - **Consulta en catálogos oficiales del SAT** actualizados
 - **Consulta en catálogos oficiales de Descarga masiva del SAT** actualizados
@@ -381,16 +387,24 @@ try {
 }
 ```
 
+## 📂 Más Ejemplos
+
+- [Gestión de Timbres](examples/ejemplo-timbres.ts)
+- [Datos Empleador/Empleado](examples/ejemplo-datos-empleado-empleador.ts)
+- [Facturas de Nómina (Por Valores)](examples/ejemplos-factura-nomina-valores.ts)
+- [Facturas de Nómina (Por Referencias)](examples/ejemplos-factura-nomina-referencias.ts) 
+- [Facturas de Impuestos Locales (Por Referencias)](examples/ejemplos-factura-impuestos-locales-referencias.ts) 
+- [Facturas de Impuestos Locales (Por Valores)](examples/ejemplos-factura-impuestos-locales-valores.ts) 
+
+
 ---
 
 ## 📋 Operaciones Principales
 
-- **Facturas (CFDI)**  
-  Crear facturas de ingreso, notas de crédito, complementos de pago, cancelaciones, generación de PDF/XML.
-- **Personas (Clientes/Emisores)**  
-  Alta y administración de personas, gestión de certificados (CSD).
-- **Productos y Servicios**  
-  Administración de catálogos de productos, búsqueda en catálogos SAT.
+- **Facturas (CFDI)** - Ingreso, egreso, pago, nómina, cancelaciones, PDF/XML
+- **Personas** - Emisores, receptores, certificados CSD
+- **Productos** - Catálogo de productos/servicios
+- **Timbres** - Transferencias y retiros
 
 
 ## 🤝 Contribuir

examples/ejemplo-datos-empleado-empleador.ts

@@ -0,0 +1,60 @@
+import {
+  FiscalapiClient,
+  FiscalapiSettings,
+  CreateEmployerRequest,
+  CreateEmployeeRequest
+} from '../src';
+
+async function main(): Promise<void> {
+
+   const settings: FiscalapiSettings = {
+    apiUrl: 'https://test.fisalapi.com',
+    apiKey: '<API_KEY>',
+    tenant: '<TENANT_ID>',
+    debug: true
+  };
+
+  const client = FiscalapiClient.create(settings);
+
+  const escuelaKemperUrgateId = '<id-empleador>';
+  const karlaFuenteNolascoId = '<id-empleado>';
+
+  // Crear datos de empleador
+  const employerRequest: CreateEmployerRequest = {
+    personId: escuelaKemperUrgateId,
+    employerRegistration: 'B5510768108',
+  };
+  const employerResult = await client.persons.employer.create(employerRequest);
+  console.log('Empleador:', JSON.stringify(employerResult, null, 2));
+
+  // Crear datos de empleado
+  const employeeRequest: CreateEmployeeRequest = {
+    employerPersonId: escuelaKemperUrgateId,
+    employeePersonId: karlaFuenteNolascoId,
+    employeeNumber: '123456789',
+    socialSecurityNumber: '04078873454',
+    laborRelationStartDate: '2024-08-18',
+    satContractTypeId: '01',
+    satTaxRegimeTypeId: '02',
+    satJobRiskId: '1',
+    satPaymentPeriodicityId: '05',
+    satBankId: '012',
+    satPayrollStateId: 'JAL',
+    department: 'GenAI',
+    position: 'Sr Software Engineer',
+    seniority: 'P54W',
+    baseSalaryForContributions: 2828.50,
+    integratedDailySalary: 0.00,
+  };
+  const employeeResult = await client.persons.employee.create(employeeRequest);
+  console.log('Empleado:', JSON.stringify(employeeResult, null, 2));
+
+  // Consultar datos
+  const employer = await client.persons.employer.getById(escuelaKemperUrgateId);
+  console.log('Consulta empleador:', JSON.stringify(employer, null, 2));
+
+  const employee = await client.persons.employee.getById(karlaFuenteNolascoId);
+  console.log('Consulta empleado:', JSON.stringify(employee, null, 2));
+}
+
+main().catch(console.error);

examples/ejemplo-timbres.ts

@@ -0,0 +1,41 @@
+import { FiscalapiClient, FiscalapiSettings } from '../src/index';
+
+async function main(): Promise<void> {
+  
+  const settings: FiscalapiSettings = {
+    apiUrl: 'https://test.fisalapi.com',
+    apiKey: '<API_KEY>',
+    tenant: '<TENANT_ID>',
+    debug: true
+  };
+
+  const client = FiscalapiClient.create(settings);
+
+  // 1. Listar transacciones de timbres
+  const list = await client.stamps.getList(1, 10);
+  console.log('Lista de transacciones:', list);
+
+  // 2. Obtener transacción por ID
+  const transaction = await client.stamps.getById('77678d6d-94b1-4635-aa91-15cdd7423aab');
+  console.log('Transacción por ID:', transaction);
+
+  // 3. Transferir timbres
+  const transfer = await client.stamps.transferStamps({
+    fromPersonId: '2e7b988f-3a2a-4f67-86e9-3f931dd48581',
+    toPersonId: '5fd9f48c-a6a2-474f-944b-88a01751d432',
+    amount: 1,
+    comments: 'Transferencia de prueba'
+  });
+  console.log('Transferencia:', transfer);
+
+  // 4. Retirar timbres
+  const withdraw = await client.stamps.withdrawStamps({
+    fromPersonId: '5fd9f48c-a6a2-474f-944b-88a01751d432',
+    toPersonId: '2e7b988f-3a2a-4f67-86e9-3f931dd48581',
+    amount: 1,
+    comments: 'Retiro de prueba'
+  });
+  console.log('Retiro:', withdraw);
+}
+
+main();