consultoria-as
61320b44d8
- API REST para gestion de facturas electronicas mexicanas (CFDI) - Laravel 9 con autenticacion OAuth 2.0 (Passport) - Integracion con Syntage, Clerk y Facturama - 30 modelos Eloquent, 39 controladores - Documentacion completa en /docs Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
174 lines
4.6 KiB
Markdown
174 lines
4.6 KiB
Markdown
# 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.
|