163 lines
5.0 KiB
Markdown
163 lines
5.0 KiB
Markdown
# Freelancer Invoicing API
|
|
|
|
A professional invoicing API for freelancers and small businesses built with FastAPI and SQLite.
|
|
|
|
**Version: 0.1.0**
|
|
|
|
## Features
|
|
|
|
- Secure authentication system with JWT tokens
|
|
- Client management (CRUD operations)
|
|
- Invoice management with line items
|
|
- Automatic total calculation
|
|
- PDF generation for invoices
|
|
- Activity logging
|
|
- Data protection (users can only access their own data)
|
|
- CORS support for all domains
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
freelancerinvoicingapi/
|
|
├── app/
|
|
│ ├── api/
|
|
│ │ ├── endpoints/ # API route handlers
|
|
│ │ │ ├── auth.py # Authentication endpoints
|
|
│ │ │ ├── clients.py # Client management endpoints
|
|
│ │ │ ├── invoices.py # Invoice management endpoints
|
|
│ │ │ └── users.py # User endpoints
|
|
│ │ ├── deps.py # Dependencies for routes
|
|
│ │ ├── health.py # Health check endpoint
|
|
│ │ └── routes.py # Route registration
|
|
│ ├── core/
|
|
│ │ ├── config.py # Application configuration
|
|
│ │ ├── logging.py # Logging setup
|
|
│ │ └── security.py # Security utilities
|
|
│ ├── crud/
|
|
│ │ ├── crud_client.py # Client CRUD operations
|
|
│ │ ├── crud_invoice.py # Invoice CRUD operations
|
|
│ │ └── crud_user.py # User CRUD operations
|
|
│ ├── db/
|
|
│ │ ├── base.py # Database models import
|
|
│ │ ├── base_class.py # Base class for models
|
|
│ │ └── session.py # Database session
|
|
│ ├── models/
|
|
│ │ ├── client.py # Client model
|
|
│ │ ├── invoice.py # Invoice and InvoiceItem models
|
|
│ │ └── user.py # User model
|
|
│ ├── schemas/
|
|
│ │ ├── client.py # Client schemas
|
|
│ │ ├── invoice.py # Invoice schemas
|
|
│ │ ├── token.py # Token schemas
|
|
│ │ └── user.py # User schemas
|
|
│ ├── services/ # Business logic services
|
|
│ └── utils/
|
|
│ └── pdf.py # PDF generation utility
|
|
├── migrations/ # Alembic migrations
|
|
│ ├── versions/ # Migration scripts
|
|
│ ├── env.py # Alembic environment
|
|
│ └── script.py.mako # Migration script template
|
|
├── storage/ # Storage directory
|
|
│ ├── db/ # Database files
|
|
│ ├── logs/ # Log files
|
|
│ └── pdfs/ # Generated PDFs
|
|
├── alembic.ini # Alembic configuration
|
|
├── main.py # Application entry point
|
|
└── requirements.txt # Dependencies
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### Authentication
|
|
|
|
- `POST /api/v1/auth/register` - Register a new user
|
|
- `POST /api/v1/auth/login` - Login to get access token
|
|
|
|
### Users
|
|
|
|
- `GET /api/v1/users/me` - Get current user info
|
|
- `PUT /api/v1/users/me` - Update current user
|
|
|
|
### Clients
|
|
|
|
- `GET /api/v1/clients` - List all clients
|
|
- `POST /api/v1/clients` - Create a new client
|
|
- `GET /api/v1/clients/{client_id}` - Get a client
|
|
- `PUT /api/v1/clients/{client_id}` - Update a client
|
|
- `DELETE /api/v1/clients/{client_id}` - Delete a client
|
|
|
|
### Invoices
|
|
|
|
- `GET /api/v1/invoices` - List all invoices
|
|
- `POST /api/v1/invoices` - Create a new invoice
|
|
- `GET /api/v1/invoices/{invoice_id}` - Get an invoice
|
|
- `PUT /api/v1/invoices/{invoice_id}` - Update an invoice
|
|
- `DELETE /api/v1/invoices/{invoice_id}` - Delete an invoice
|
|
- `POST /api/v1/invoices/{invoice_id}/items` - Add an item to an invoice
|
|
- `DELETE /api/v1/invoices/{invoice_id}/items/{item_id}` - Remove an item from an invoice
|
|
- `GET /api/v1/invoices/{invoice_id}/pdf` - Generate and download a PDF for an invoice
|
|
|
|
### Health Check
|
|
|
|
- `GET /health` - Check API health
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.8+
|
|
- pip
|
|
|
|
### Installation
|
|
|
|
1. Clone the repository
|
|
2. Install dependencies:
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. Run the migrations:
|
|
|
|
```bash
|
|
alembic upgrade head
|
|
```
|
|
|
|
4. Start the application:
|
|
|
|
```bash
|
|
uvicorn main:app --reload
|
|
```
|
|
|
|
The API will be available at http://localhost:8000.
|
|
|
|
API documentation is available at:
|
|
- Swagger UI: http://localhost:8000/docs
|
|
- ReDoc: http://localhost:8000/redoc
|
|
|
|
## Databaseș
|
|
|
|
The application uses SQLite as its database. The database file is stored in the `/app/storage/db` directory.
|
|
|
|
## Security
|
|
|
|
- JWT token-based authentication
|
|
- Password hashing with bcrypt
|
|
- User-specific data isolation
|
|
- HTTPS recommended for production
|
|
|
|
## PDF Generation
|
|
|
|
The application uses ReportLab to generate PDF invoices, which can be downloaded by clients.
|
|
|
|
## Logging
|
|
|
|
Activity logs are stored in the `/app/storage/logs` directory.
|
|
|
|
## Version Information
|
|
|
|
- **Current Version**: 0.1.0
|
|
- **API Version Path**: /api/v1
|
|
- **Release Date**: May 2023
|
|
- **FastAPI Version**: 0.104.1+
|
|
- **Python Compatibility**: 3.8+ |