189 lines
5.6 KiB
Markdown
189 lines
5.6 KiB
Markdown
# Simulator API - Quick Start Guide
|
|
|
|
## What is the Simulator API?
|
|
|
|
The Simulator API provides mock endpoints for testing email and SMS notifications without using real third-party services. It:
|
|
- **Sends real emails** via Django SMTP
|
|
- **Prints SMS messages** to terminal with formatted output
|
|
- **Integrates seamlessly** with the existing `NotificationService`
|
|
|
|
## Quick Start (5 Minutes)
|
|
|
|
### 1. Start the Development Server
|
|
|
|
```bash
|
|
cd /home/ismail/projects/HH
|
|
python manage.py runserver
|
|
```
|
|
|
|
### 2. Enable the Simulator
|
|
|
|
Edit your `.env` file and add these lines:
|
|
|
|
```bash
|
|
# Enable external API notifications
|
|
EMAIL_API_ENABLED=true
|
|
SMS_API_ENABLED=true
|
|
|
|
# Point to simulator endpoints
|
|
EMAIL_API_URL=http://localhost:8000/api/simulator/send-email
|
|
SMS_API_URL=http://localhost:8000/api/simulator/send-sms
|
|
|
|
# Simulator authentication (any value works)
|
|
EMAIL_API_KEY=simulator-test-key
|
|
SMS_API_KEY=simulator-test-key
|
|
|
|
# Authentication method
|
|
EMAIL_API_AUTH_METHOD=bearer
|
|
SMS_API_AUTH_METHOD=bearer
|
|
|
|
# Email SMTP settings (for real emails)
|
|
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
|
|
EMAIL_HOST=10.10.1.110
|
|
EMAIL_PORT=2225
|
|
EMAIL_USE_TLS=true
|
|
DEFAULT_FROM_EMAIL=noreply@px360.sa
|
|
```
|
|
|
|
### 3. Test the Simulator
|
|
|
|
Run the test script:
|
|
|
|
```bash
|
|
python test_simulator.py
|
|
```
|
|
|
|
This will:
|
|
- ✅ Send test emails (via SMTP)
|
|
- ✅ Send test SMS (printed to terminal)
|
|
- ✅ Check simulator health
|
|
- ✅ Test error handling
|
|
- ✅ Display statistics
|
|
|
|
### 4. Use in Your Code
|
|
|
|
```python
|
|
from apps.notifications.services import NotificationService
|
|
|
|
# Send email
|
|
log = NotificationService.send_email_via_api(
|
|
message='Your account has been created!',
|
|
email='user@example.com',
|
|
subject='Welcome to PX360'
|
|
)
|
|
|
|
# Send SMS
|
|
log = NotificationService.send_sms_via_api(
|
|
message='Your verification code is 123456',
|
|
phone='+966501234567'
|
|
)
|
|
```
|
|
|
|
## Expected Output
|
|
|
|
### Email (in terminal)
|
|
```
|
|
======================================================================
|
|
📧 EMAIL SIMULATOR - Request #1
|
|
======================================================================
|
|
To: user@example.com
|
|
Subject: Welcome to PX360
|
|
Message: Your account has been created!
|
|
HTML: No
|
|
======================================================================
|
|
```
|
|
|
|
### SMS (in terminal)
|
|
```
|
|
══════════════════════════════════════════════════════════════════════
|
|
📱 SMS SIMULATOR
|
|
══════════════════════════════════════════════════════════════════════
|
|
Request #: 1
|
|
══════════════════════════════════════════════════════════════════════
|
|
To: +966501234567
|
|
Time: 2026-01-12 18:08:00
|
|
══════════════════════════════════════════════════════════════════════
|
|
Message:
|
|
Your verification code is 123456
|
|
══════════════════════════════════════════════════════════════════════
|
|
```
|
|
|
|
## Available Endpoints
|
|
|
|
| Endpoint | Method | Description |
|
|
|----------|--------|-------------|
|
|
| `/api/simulator/send-email` | POST | Send email via SMTP |
|
|
| `/api/simulator/send-sms` | POST | Print SMS to terminal |
|
|
| `/api/simulator/health` | GET | Check simulator status |
|
|
| `/api/simulator/reset` | GET | Reset counters |
|
|
|
|
## Check Simulator Status
|
|
|
|
```bash
|
|
curl http://localhost:8000/api/simulator/health
|
|
```
|
|
|
|
Response:
|
|
```json
|
|
{
|
|
"status": "healthy",
|
|
"statistics": {
|
|
"total_requests": 5,
|
|
"email_requests": 3,
|
|
"sms_requests": 2
|
|
}
|
|
}
|
|
```
|
|
|
|
## Switching to Real APIs
|
|
|
|
When ready to use real notification services, just update `.env`:
|
|
|
|
```bash
|
|
EMAIL_API_ENABLED=true
|
|
EMAIL_API_URL=https://api.yourservice.com/send-email
|
|
SMS_API_ENABLED=true
|
|
SMS_API_URL=https://api.yourservice.com/send-sms
|
|
```
|
|
|
|
**No code changes required!**
|
|
|
|
## Troubleshooting
|
|
|
|
### Simulator not working?
|
|
1. Check server is running: `python manage.py runserver`
|
|
2. Check `.env` has correct URLs
|
|
3. Check health: `curl http://localhost:8000/api/simulator/health`
|
|
|
|
### Emails not received?
|
|
1. Verify SMTP settings in `.env`
|
|
2. Check `logs/px360.log` for errors
|
|
3. Check spam folder
|
|
|
|
### SMS not showing in terminal?
|
|
1. Ensure server running in visible terminal
|
|
2. Check `logs/px360.log` for SMS logs
|
|
|
|
## Documentation
|
|
|
|
- **Full Documentation**: [SIMULATOR_API.md](SIMULATOR_API.md)
|
|
- **External API Service**: [EXTERNAL_API_NOTIFICATION.md](EXTERNAL_API_NOTIFICATION.md)
|
|
- **Test Script**: `test_simulator.py`
|
|
|
|
## Support
|
|
|
|
For issues or questions:
|
|
1. Check logs: `logs/px360.log`
|
|
2. Run test script: `python test_simulator.py`
|
|
3. See full documentation: `docs/SIMULATOR_API.md`
|
|
|
|
## Summary
|
|
|
|
✅ **Email Simulator**: Sends real emails via SMTP
|
|
✅ **SMS Simulator**: Prints formatted SMS to terminal
|
|
✅ **Easy Setup**: Just update `.env` file
|
|
✅ **No Code Changes**: Works with existing `NotificationService`
|
|
✅ **Production Ready**: Easy switch to real APIs
|
|
|
|
Happy testing! 🚀
|