# Horux Backend API

API REST Backend especializada en gestión de facturas electrónicas mexicanas (CFDI).

## Descripcion

Horux es una plataforma de gestión fiscal que permite a los usuarios:
- Gestionar y consultar facturas electrónicas (CFDI) emitidas y recibidas
- Realizar conciliaciones de facturas
- Obtener metricas financieras y analisis de rentabilidad
- Consultar informacion de contribuyentes y riesgos fiscales
- Importar facturas masivamente desde archivos Excel

## Tecnologias

| Tecnologia | Version | Proposito |
|------------|---------|-----------|
| PHP | 8.0.2+ | Lenguaje principal |
| Laravel | 9.19 | Framework backend |
| MySQL | 5.7+ | Base de datos |
| Laravel Passport | 11.0 | Autenticacion OAuth 2.0 |
| Maatwebsite Excel | 3.1 | Importacion de Excel |
| Vite | 4.0 | Build de assets |

## Integraciones Externas

- **Syntage API** - Obtencion de facturas y datos fiscales del SAT
- **Clerk** - Autenticacion social OAuth 2.0
- **Facturama** - Generacion y timbrado de CFDIs

## Estructura del Proyecto

```
Horux_back/
├── app/
│   ├── Console/           # Comandos Artisan
│   ├── Exceptions/        # Manejo de excepciones
│   ├── Http/
│   │   ├── Controllers/   # 39 controladores
│   │   ├── Middleware/    # Middleware personalizado
│   │   └── Kernel.php
│   ├── Imports/           # Importadores Excel
│   ├── Models/            # 30 modelos Eloquent
│   ├── Providers/         # Service Providers
│   └── Services/          # Servicios de negocio
├── bootstrap/             # Inicializacion
├── config/                # Configuracion
├── database/
│   ├── migrations/        # 41 migraciones
│   ├── seeders/           # Seeders
│   └── factories/         # Model factories
├── docs/                  # Documentacion
├── public/                # Punto de entrada web
├── resources/             # Vistas y assets
├── routes/
│   ├── api.php            # Rutas API (54+ endpoints)
│   └── web.php            # Rutas web
├── storage/               # Almacenamiento
├── tests/                 # Tests PHPUnit
└── vendor/                # Dependencias
```

## Instalacion Rapida

```bash
# Clonar repositorio
git clone <url-repositorio>
cd Horux_back

# Instalar dependencias PHP
composer install

# Instalar dependencias NPM
npm install

# Configurar entorno
cp .env.example .env
php artisan key:generate

# Configurar base de datos en .env
# DB_DATABASE=horux360bd
# DB_USERNAME=tu_usuario
# DB_PASSWORD=tu_password

# Ejecutar migraciones
php artisan migrate

# Configurar Passport
php artisan passport:install

# Iniciar servidor
php artisan serve
```

## Documentacion

- [Guia de Instalacion](docs/INSTALLATION.md)
- [Documentacion de API](docs/API.md)
- [Modelos y Base de Datos](docs/MODELS.md)
- [Arquitectura](docs/ARCHITECTURE.md)

## Endpoints Principales

### Autenticacion
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | `/api/auth` | Autenticacion con Clerk |

### Facturas
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | `/api/obtener-facturas` | Obtener todas las facturas |
| GET | `/api/facturas-emitidas` | Facturas emitidas |
| GET | `/api/facturas-recibidas` | Facturas recibidas |
| POST | `/api/conciliar-facturas` | Conciliar facturas |
| GET | `/api/descargar-factura` | Descargar CFDI |

### Metricas
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | `/api/obtener-metricas` | Metricas globales |
| GET | `/api/obtener-metricas-mensuales` | Metricas por mes |
| GET | `/api/ivaAFavor` | IVA a favor |

Ver documentacion completa en [docs/API.md](docs/API.md)

## Modelos Principales

- **User** - Usuarios del sistema
- **Rfc** - RFCs asociados a usuarios
- **Invoice** - Facturas electronicas
- **InvoiceLine** - Lineas/conceptos de facturas
- **InvoicePayment** - Pagos de facturas (PPD)
- **Taxpayer** - Informacion de contribuyentes

Ver documentacion completa en [docs/MODELS.md](docs/MODELS.md)

## Requisitos del Sistema

- PHP >= 8.0.2
- Composer >= 2.0
- MySQL >= 5.7 o MariaDB >= 10.3
- Node.js >= 16.0
- NPM >= 8.0

## Variables de Entorno Requeridas

```env
APP_NAME=Horux
APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=https://tu-dominio.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=horux360bd
DB_USERNAME=
DB_PASSWORD=

# Passport OAuth
PASSPORT_CLIENT_ID=
PASSPORT_CLIENT_SECRET=
```

## Licencia

Proyecto propietario - Todos los derechos reservados.

## Contacto

Para soporte tecnico o consultas sobre el proyecto.