194 lines
5.1 KiB
Markdown
194 lines
5.1 KiB
Markdown
# LittleShop API
|
|
|
|
A basic online sales system backend built with ASP.NET Core 9.0, featuring multi-cryptocurrency payment support via BTCPay Server.
|
|
|
|
## Features
|
|
|
|
### Admin Panel
|
|
- **Authentication**: JWT-based authentication for admin users
|
|
- **Categories**: Full CRUD operations for product categories
|
|
- **Products**: Complete product management with image upload support
|
|
- **Users**: Staff user management (username/password only)
|
|
- **Orders**: Order management with status tracking
|
|
- **Accounting**: Dashboard and financial overview
|
|
|
|
### Public API
|
|
- **Catalog**: Public product and category browsing
|
|
- **Orders**: Order creation and management by client identity reference
|
|
- **Payments**: Multi-cryptocurrency payment processing
|
|
- **Tracking**: Order status and tracking
|
|
|
|
### Cryptocurrency Support
|
|
- **BTC** (Bitcoin) + Lightning Network
|
|
- **XMR** (Monero) - Privacy coin
|
|
- **USDT** (Tether) - Stablecoin
|
|
- **LTC** (Litecoin)
|
|
- **ETH** (Ethereum)
|
|
- **ZEC** (Zcash) - Privacy coin
|
|
- **DASH** (Dash)
|
|
- **DOGE** (Dogecoin)
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
- .NET 9.0 SDK
|
|
- SQLite (included)
|
|
- BTCPay Server instance (for production)
|
|
|
|
### Configuration
|
|
|
|
Update `appsettings.json` with your settings:
|
|
|
|
```json
|
|
{
|
|
"ConnectionStrings": {
|
|
"DefaultConnection": "Data Source=littleshop.db"
|
|
},
|
|
"Jwt": {
|
|
"Key": "YourSuperSecretKeyThatIsAtLeast32CharactersLong!",
|
|
"Issuer": "LittleShop",
|
|
"Audience": "LittleShop",
|
|
"ExpiryInHours": 24
|
|
},
|
|
"BTCPayServer": {
|
|
"BaseUrl": "https://your-btcpay-server.com",
|
|
"ApiKey": "your-api-key",
|
|
"StoreId": "your-store-id",
|
|
"WebhookSecret": "your-webhook-secret"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Running the Application
|
|
|
|
1. **Clone and build**:
|
|
```bash
|
|
dotnet restore
|
|
dotnet build
|
|
```
|
|
|
|
2. **Run**:
|
|
```bash
|
|
dotnet run
|
|
```
|
|
|
|
3. **Access**:
|
|
- API: `https://localhost:5001`
|
|
- Swagger UI: `https://localhost:5001/swagger`
|
|
|
|
### Default Admin User
|
|
- **Username**: `admin`
|
|
- **Password**: `admin`
|
|
|
|
## API Endpoints
|
|
|
|
### Authentication
|
|
- `POST /api/auth/login` - Login (get JWT token)
|
|
- `GET /api/auth/users` - List users (admin)
|
|
- `POST /api/auth/users` - Create user (admin)
|
|
|
|
### Categories
|
|
- `GET /api/categories` - List categories
|
|
- `POST /api/categories` - Create category (admin)
|
|
- `PUT /api/categories/{id}` - Update category (admin)
|
|
- `DELETE /api/categories/{id}` - Delete category (admin)
|
|
|
|
### Products
|
|
- `GET /api/products` - List products
|
|
- `GET /api/products?categoryId={id}` - Products by category
|
|
- `POST /api/products` - Create product (admin)
|
|
- `POST /api/products/{id}/photos` - Upload product photo (admin)
|
|
|
|
### Public Catalog
|
|
- `GET /api/catalog/categories` - Public category list
|
|
- `GET /api/catalog/products` - Public product list
|
|
|
|
### Orders
|
|
- `POST /api/orders` - Create order
|
|
- `GET /api/orders/by-identity/{identity}` - Get orders by identity
|
|
- `POST /api/orders/{id}/payments` - Create crypto payment
|
|
- `GET /api/orders/{id}/payments` - Get order payments
|
|
- `POST /api/orders/{id}/cancel` - Cancel order
|
|
|
|
### Admin Order Management
|
|
- `GET /api/orders` - List all orders (admin)
|
|
- `PUT /api/orders/{id}/status` - Update order status (admin)
|
|
|
|
## Product Weight Units
|
|
|
|
- `Unit` (0) - Generic unit
|
|
- `Micrograms` (1)
|
|
- `Grams` (2)
|
|
- `Ounces` (3)
|
|
- `Pounds` (4)
|
|
- `Millilitres` (5)
|
|
- `Litres` (6)
|
|
|
|
## Order Statuses
|
|
|
|
- `PendingPayment` (0) - Awaiting payment
|
|
- `PaymentReceived` (1) - Payment confirmed
|
|
- `Processing` (2) - Being processed
|
|
- `PickingAndPacking` (3) - Preparing for shipment
|
|
- `Shipped` (4) - Shipped with tracking
|
|
- `Delivered` (5) - Delivered
|
|
- `Cancelled` (6) - Cancelled
|
|
- `Refunded` (7) - Refunded
|
|
|
|
## Payment Workflow
|
|
|
|
1. Customer creates order via API
|
|
2. Order receives unique ID and pending status
|
|
3. Customer requests payment in preferred cryptocurrency
|
|
4. System generates unique wallet address and amount
|
|
5. Customer sends payment to provided address
|
|
6. BTCPay Server detects payment and triggers webhook
|
|
7. Order status updates to PaymentReceived
|
|
8. Admin processes order through picking & packing
|
|
9. Shipping label generated via Royal Mail API
|
|
10. Customer receives tracking information
|
|
|
|
## Security Features
|
|
|
|
- JWT authentication for admin endpoints
|
|
- Password hashing with PBKDF2
|
|
- No customer personal data stored (identity reference only)
|
|
- Self-hosted payment processing (no third-party data sharing)
|
|
- CORS configuration for web clients
|
|
|
|
## Logging
|
|
|
|
- Structured logging with Serilog
|
|
- Console and file output
|
|
- Request/response logging
|
|
- Payment processing audit trail
|
|
|
|
## Development
|
|
|
|
The API is built with:
|
|
- **ASP.NET Core 9.0** - Web framework
|
|
- **Entity Framework Core** - Database ORM
|
|
- **SQLite** - Database
|
|
- **JWT** - Authentication
|
|
- **AutoMapper** - Object mapping
|
|
- **FluentValidation** - Input validation
|
|
- **Serilog** - Logging
|
|
- **Swagger** - API documentation
|
|
- **BTCPay Server Client** - Crypto payments
|
|
|
|
## Privacy & Compliance
|
|
|
|
- No KYC requirements
|
|
- No customer personal data retention
|
|
- Privacy-focused cryptocurrencies supported (XMR, ZEC)
|
|
- Self-hosted payment processing
|
|
- GDPR-friendly design (minimal data collection)
|
|
|
|
## Future Enhancements
|
|
|
|
- Royal Mail API integration for shipping
|
|
- Email notifications
|
|
- Inventory management
|
|
- Multi-currency pricing
|
|
- Advanced reporting
|
|
- Order export functionality |