138 lines
3.9 KiB
Markdown
138 lines
3.9 KiB
Markdown
|
# POS Integration Service
|
||
|
|
|
||
|
|
This service handles integration with external Point of Sale (POS) systems for the Bakery IA platform.
|
||
|
|
|
||
|
|
## Supported POS Systems
|
||
|
|
|
||
|
|
- **Square POS** - Popular payment and POS solution with strong API support
|
||
|
|
- **Toast POS** - Restaurant-focused POS system with comprehensive features
|
||
|
|
- **Lightspeed Restaurant** - Full-featured restaurant management system
|
||
|
|
|
||
|
|
## Features
|
||
|
|
|
||
|
|
- **Real-time webhook handling** from POS systems
|
||
|
|
- **Bidirectional data synchronization** with sales service
|
||
|
|
- **Secure credential management** with encryption
|
||
|
|
- **Multi-tenant support** with tenant-specific configurations
|
||
|
|
- **Comprehensive transaction logging** and audit trails
|
||
|
|
- **Automatic duplicate detection** and handling
|
||
|
|
- **Rate limiting and retry mechanisms** for reliability
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
The POS service follows the established microservices architecture:
|
||
|
|
|
||
|
|
```
|
||
|
|
POS Service
|
||
|
|
├── API Layer (FastAPI)
|
||
|
|
├── Business Logic (Services)
|
||
|
|
├── Data Access (Repositories)
|
||
|
|
├── External Integrations (POS Providers)
|
||
|
|
├── Webhook Handlers
|
||
|
|
└── Background Sync Jobs
|
||
|
|
```
|
||
|
|
|
||
|
|
## API Endpoints
|
||
|
|
|
||
|
|
### Configuration Management
|
||
|
|
- `GET /api/v1/tenants/{tenant_id}/pos/configurations` - List POS configurations
|
||
|
|
- `POST /api/v1/tenants/{tenant_id}/pos/configurations` - Create new configuration
|
||
|
|
- `PUT /api/v1/tenants/{tenant_id}/pos/configurations/{config_id}` - Update configuration
|
||
|
|
- `DELETE /api/v1/tenants/{tenant_id}/pos/configurations/{config_id}` - Delete configuration
|
||
|
|
|
||
|
|
### Webhook Handling
|
||
|
|
- `POST /api/v1/webhooks/{pos_system}` - Receive webhooks from POS systems
|
||
|
|
- `GET /api/v1/webhooks/{pos_system}/status` - Get webhook status
|
||
|
|
|
||
|
|
### Data Synchronization
|
||
|
|
- `POST /api/v1/tenants/{tenant_id}/pos/configurations/{config_id}/sync` - Trigger sync
|
||
|
|
- `GET /api/v1/tenants/{tenant_id}/pos/configurations/{config_id}/sync/status` - Get sync status
|
||
|
|
- `GET /api/v1/tenants/{tenant_id}/pos/transactions` - Get POS transactions
|
||
|
|
|
||
|
|
## Database Schema
|
||
|
|
|
||
|
|
### Core Tables
|
||
|
|
- `pos_configurations` - POS system configurations per tenant
|
||
|
|
- `pos_transactions` - Transaction data from POS systems
|
||
|
|
- `pos_transaction_items` - Individual items within transactions
|
||
|
|
- `pos_webhook_logs` - Webhook event logs
|
||
|
|
- `pos_sync_logs` - Synchronization operation logs
|
||
|
|
|
||
|
|
## Environment Variables
|
||
|
|
|
||
|
|
See `app/core/config.py` for all configuration options. Key variables include:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Database
|
||
|
|
POS_DATABASE_URL=postgresql+asyncpg://pos_user:pos_pass123@pos-db:5432/pos_db
|
||
|
|
|
||
|
|
# POS Provider Credentials
|
||
|
|
SQUARE_APPLICATION_ID=your_square_app_id
|
||
|
|
SQUARE_ACCESS_TOKEN=your_square_token
|
||
|
|
TOAST_CLIENT_ID=your_toast_client_id
|
||
|
|
LIGHTSPEED_CLIENT_ID=your_lightspeed_client_id
|
||
|
|
|
||
|
|
# Webhook Configuration
|
||
|
|
WEBHOOK_BASE_URL=https://your-domain.com
|
||
|
|
WEBHOOK_SECRET=your_webhook_secret
|
||
|
|
```
|
||
|
|
|
||
|
|
## Development
|
||
|
|
|
||
|
|
### Running the Service
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Using Docker Compose (recommended)
|
||
|
|
docker-compose up pos-service
|
||
|
|
|
||
|
|
# Local development
|
||
|
|
cd services/pos
|
||
|
|
pip install -r requirements.txt
|
||
|
|
uvicorn app.main:app --reload --port 8000
|
||
|
|
```
|
||
|
|
|
||
|
|
### Database Migrations
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Create migration
|
||
|
|
alembic revision --autogenerate -m "Description"
|
||
|
|
|
||
|
|
# Apply migrations
|
||
|
|
alembic upgrade head
|
||
|
|
```
|
||
|
|
|
||
|
|
### Testing
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Run tests
|
||
|
|
pytest tests/
|
||
|
|
|
||
|
|
# Run with coverage
|
||
|
|
pytest --cov=app tests/
|
||
|
|
```
|
||
|
|
|
||
|
|
## Security Considerations
|
||
|
|
|
||
|
|
- POS credentials are encrypted before storage
|
||
|
|
- Webhook signatures are verified for authenticity
|
||
|
|
- All API endpoints require tenant-based authentication
|
||
|
|
- Rate limiting prevents abuse
|
||
|
|
- Sensitive data is logged with appropriate redaction
|
||
|
|
|
||
|
|
## Monitoring
|
||
|
|
|
||
|
|
The service includes comprehensive monitoring:
|
||
|
|
|
||
|
|
- Health check endpoints
|
||
|
|
- Prometheus metrics
|
||
|
|
- Structured logging
|
||
|
|
- Performance tracking
|
||
|
|
- Error rate monitoring
|
||
|
|
|
||
|
|
## Integration Flow
|
||
|
|
|
||
|
|
1. **Configuration**: Set up POS system credentials via API
|
||
|
|
2. **Webhook Registration**: Register webhook URLs with POS providers
|
||
|
|
3. **Real-time Events**: Receive and process webhook events
|
||
|
|
4. **Data Sync**: Periodic synchronization of transaction data
|
||
|
|
5. **Sales Integration**: Forward processed data to sales service
|