auto-claude: subtask-3-7 - Add API endpoints documentation

2026-01-10 09:43:53 +01:00 · 2026-01-10 09:43:53 +01:00 · d74889a1c6
commit d74889a1c6
parent 40ff7e950e
1 changed files with 308 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -641,6 +641,314 @@ If issues persist, check NPM configuration on R11-REVPROXY-01 (Proxy Host ID: 27

 **For detailed incident reports and troubleshooting guides, see `docs/INCIDENT_REPORT_20260102.md`.**

+## API Documentation
+
+The Norda Biznes Hub provides a comprehensive RESTful API for programmatic access to company data, user management, and administrative functions. All API endpoints return JSON responses.
+
+### Base URL
+
+- **Development:** `http://localhost:5000`
+- **Production:** `https://nordabiznes.pl`
+
+### Authentication
+
+API endpoints requiring authentication expect a valid session cookie (`session`). Users must be logged in via the web interface or obtain a session through the login endpoint.
+
+### Public API Endpoints
+
+These endpoints are accessible without authentication:
+
+| Endpoint | Method | Description | Response |
+|----------|--------|-------------|----------|
+| `/health` | GET | Health check endpoint for monitoring | `{"status": "healthy"}` |
+| `/api/companies` | GET | Retrieve list of all companies with filtering options | Array of company objects with full details |
+| `/api/verify-nip` | POST | Verify NIP number via KRS API | Company data or error message |
+| `/api/verify-krs` | GET/POST | Verify KRS number and retrieve company data | KRS registry information |
+| `/api/model-info` | GET | Get information about AI model configuration | Model name, version, capabilities |
+| `/api/check-email` | POST | Check if email address is already registered | `{"exists": true/false}` |
+
+**Example - Get Companies:**
+```bash
+curl https://nordabiznes.pl/api/companies
+```
+
+**Example - Verify NIP:**
+```bash
+curl -X POST https://nordabiznes.pl/api/verify-nip \
+  -H "Content-Type: application/json" \
+  -d '{"nip": "5882436505"}'
+```
+
+### User API Endpoints
+
+These endpoints require user authentication (regular or admin):
+
+#### Chat & AI Assistant
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/chat/start` | POST | Start a new AI chat conversation |
+| `/api/chat/<conversation_id>/message` | POST | Send a message in an existing conversation |
+| `/api/chat/<conversation_id>/history` | GET | Retrieve conversation history |
+| `/api/chat/feedback` | POST | Submit feedback on AI chat response (thumbs up/down) |
+
+**Example - Start Chat:**
+```bash
+curl -X POST https://nordabiznes.pl/api/chat/start \
+  -H "Content-Type: application/json" \
+  -H "Cookie: session=YOUR_SESSION" \
+  -d '{"message": "Szukam firm IT w Wejherowie"}'
+```
+
+#### Notifications
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/notifications` | GET | Get user notifications (new news, approvals, etc.) |
+| `/api/notifications/<notification_id>/read` | POST | Mark specific notification as read |
+| `/api/notifications/read-all` | POST | Mark all notifications as read |
+| `/api/notifications/unread-count` | GET | Get count of unread notifications |
+
+**Example - Get Notifications:**
+```bash
+curl https://nordabiznes.pl/api/notifications \
+  -H "Cookie: session=YOUR_SESSION"
+```
+
+#### Messages
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/messages/unread-count` | GET | Get count of unread private messages |
+
+#### Recommendations
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/recommendations/<company_id>` | GET | Get recommendations for a company |
+| `/api/recommendations/create` | POST | Create a new recommendation |
+| `/api/recommendations/<rec_id>/edit` | POST | Edit existing recommendation |
+| `/api/recommendations/<rec_id>/delete` | POST | Delete a recommendation |
+
+### Admin API Endpoints
+
+These endpoints require admin privileges (`is_admin=True`):
+
+#### SEO Audits
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/seo/audit` | GET | Get all SEO audit results |
+| `/api/seo/audit/<slug>` | GET | Get SEO audit for specific company |
+| `/api/seo/audit` | POST | Trigger new SEO audit for company |
+
+**Example - Trigger SEO Audit:**
+```bash
+curl -X POST https://nordabiznes.pl/api/seo/audit \
+  -H "Content-Type: application/json" \
+  -H "Cookie: session=YOUR_ADMIN_SESSION" \
+  -d '{"company_id": 26, "url": "https://example.com"}'
+```
+
+#### Google Business Profile Audits
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/gbp/audit/health` | GET | Check GBP audit service health |
+| `/api/gbp/audit` | GET | Get all GBP audit results |
+| `/api/gbp/audit/<slug>` | GET | Get GBP audit for specific company |
+| `/api/gbp/audit` | POST | Trigger new GBP audit |
+
+#### Social Media Audits
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/social/audit` | POST | Trigger social media profile audit |
+
+#### IT Infrastructure Audits
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/it-audit/matches/<company_id>` | GET | Get collaboration matches for company |
+| `/api/it-audit/history/<company_id>` | GET | Get IT audit history for company |
+| `/api/it-audit/export` | GET | Export IT audit data (CSV format) |
+
+#### User Management
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/admin/users/ai-parse` | POST | Parse user data from natural language using AI |
+| `/api/admin/users/bulk-create` | POST | Create multiple users from parsed data |
+
+#### Analytics & Monitoring
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/admin/chat-stats` | GET | Get AI chat usage statistics |
+| `/api/admin/logs` | GET | Retrieve application logs |
+| `/api/admin/logs/stream` | GET | Stream application logs (SSE) |
+| `/api/admin/logs/clear` | POST | Clear application logs |
+| `/api/admin/test-log` | POST | Generate test log entry |
+
+### Company Refresh Endpoint
+
+| Endpoint | Method | Description | Auth Required |
+|----------|--------|-------------|---------------|
+| `/api/company/<company_id>/refresh-krs` | POST | Refresh company data from KRS registry | User (company owner or admin) |
+
+### Rate Limiting
+
+The API implements rate limiting to ensure fair usage:
+
+- **Global limit:** 200 requests per day per IP
+- **Burst limit:** 50 requests per hour per IP
+- **AI Chat:** 200 requests per day (Google Gemini free tier)
+- **SEO Audits:** 25,000 requests per day (Google PageSpeed Insights free tier)
+- **News Monitoring:** 2,000 requests per month (Brave Search API free tier)
+
+### Error Responses
+
+All API endpoints return standard HTTP status codes:
+
+| Status Code | Meaning |
+|-------------|---------|
+| **200** | Success - Request completed successfully |
+| **201** | Created - Resource created successfully |
+| **400** | Bad Request - Invalid parameters or missing required fields |
+| **401** | Unauthorized - Authentication required |
+| **403** | Forbidden - Insufficient permissions (admin required) |
+| **404** | Not Found - Resource does not exist |
+| **429** | Too Many Requests - Rate limit exceeded |
+| **500** | Internal Server Error - Server error occurred |
+
+**Error Response Format:**
+```json
+{
+  "error": "Error message",
+  "details": "Additional error details (optional)"
+}
+```
+
+### API Response Examples
+
+**Success Response - Company List:**
+```json
+{
+  "companies": [
+    {
+      "id": 1,
+      "name": "PIXLAB Sp. z o.o.",
+      "slug": "pixlab-sp-z-o-o",
+      "category": "IT",
+      "description": "Innowacyjne rozwiązania IT...",
+      "nip": "5882436505",
+      "website": "https://pixlab.pl",
+      "email": "biuro@pixlab.pl",
+      "phone": "+48 58 xxx xx xx",
+      "city": "Wejherowo",
+      "services": ["Strony WWW", "Aplikacje webowe"],
+      "competencies": ["Python", "Flask", "React"]
+    }
+  ],
+  "total": 80
+}
+```
+
+**Success Response - SEO Audit:**
+```json
+{
+  "company_id": 26,
+  "company_name": "PIXLAB Sp. z o.o.",
+  "url": "https://pixlab.pl",
+  "seo_score": 92,
+  "performance_score": 88,
+  "accessibility_score": 95,
+  "best_practices_score": 90,
+  "audited_at": "2026-01-10T10:30:00Z"
+}
+```
+
+**Error Response - Authentication Required:**
+```json
+{
+  "error": "Authentication required",
+  "details": "Please log in to access this endpoint"
+}
+```
+
+### Web Interface Endpoints
+
+In addition to JSON API endpoints, the application provides web interface routes:
+
+#### Public Routes
+
+- `/` - Company directory listing
+- `/company/<slug>` - Company profile page
+- `/search` - Search interface
+- `/chat` - AI chat interface
+- `/aktualnosci` - News feed
+- `/forum` - Discussion forum
+- `/kalendarz` - Events calendar
+- `/tablica` - Classifieds board
+- `/nowi-czlonkowie` - New members
+
+#### Authentication Routes
+
+- `/register` - User registration
+- `/login` - User login
+- `/logout` - User logout
+- `/forgot-password` - Password recovery
+- `/reset-password/<token>` - Password reset
+- `/verify-email/<token>` - Email verification
+- `/resend-verification` - Resend verification email
+
+#### User Dashboard Routes
+
+- `/dashboard` - User dashboard
+- `/wiadomosci` - Private messages
+- `/company/<slug>/recommend` - Submit recommendation
+
+#### Admin Dashboard Routes
+
+- `/admin/news` - News moderation panel
+- `/admin/seo` - SEO audit dashboard
+- `/admin/gbp-audit` - Google Business Profile audit
+- `/admin/social-media` - Social media audit
+- `/admin/social-audit` - Social media batch audit
+- `/admin/it-audit` - IT infrastructure audit
+- `/admin/forum` - Forum management
+- `/admin/kalendarz` - Calendar management
+- `/admin/users` - User management
+- `/admin/fees` - Membership fees management
+- `/admin/recommendations` - Recommendations moderation
+- `/admin/chat-analytics` - AI chat analytics
+- `/admin/digital-maturity` - Digital maturity assessment
+- `/admin/debug` - Debug panel
+
+#### Audit Detail Routes
+
+- `/audit/seo/<slug>` - SEO audit details for company
+- `/audit/social/<slug>` - Social media audit details
+- `/audit/gbp/<slug>` - GBP audit details
+- `/audit/it/<slug>` - IT audit details
+
+### API Best Practices
+
+1. **Always check the `/health` endpoint** before making API calls to ensure the service is available
+2. **Implement exponential backoff** for rate-limited requests
+3. **Cache responses** when appropriate to reduce API load
+4. **Use HTTPS** in production for secure communication
+5. **Handle errors gracefully** and provide meaningful error messages to users
+6. **Log API requests** for debugging and monitoring purposes
+
+### Further Documentation
+
+For detailed information about specific features:
+- **AI Chat:** See `nordabiz_chat.py` and `tests/ai_quality_test_cases.json`
+- **Search System:** See `search_service.py` for SearchService implementation
+- **Database Schema:** See `database/schema.sql` and `database.py`
+- **External APIs:** See `CLAUDE.md` for integration details
+
 ## Roadmap & Future Enhancements

 While the platform is fully functional and in production, the following features are planned for future releases: