From d74889a1c62c0dfcddd82cca591b7bbd804e50b7 Mon Sep 17 00:00:00 2001 From: Maciej Pienczyn Date: Sat, 10 Jan 2026 09:43:53 +0100 Subject: [PATCH] auto-claude: subtask-3-7 - Add API endpoints documentation --- README.md | 308 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 308 insertions(+) diff --git a/README.md b/README.md index 56ffa53..fb63ffd 100644 --- 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//message` | POST | Send a message in an existing conversation | +| `/api/chat//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//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/` | GET | Get recommendations for a company | +| `/api/recommendations/create` | POST | Create a new recommendation | +| `/api/recommendations//edit` | POST | Edit existing recommendation | +| `/api/recommendations//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/` | 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/` | 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/` | GET | Get collaboration matches for company | +| `/api/it-audit/history/` | 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//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/` - 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/` - Password reset +- `/verify-email/` - Email verification +- `/resend-verification` - Resend verification email + +#### User Dashboard Routes + +- `/dashboard` - User dashboard +- `/wiadomosci` - Private messages +- `/company//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/` - SEO audit details for company +- `/audit/social/` - Social media audit details +- `/audit/gbp/` - GBP audit details +- `/audit/it/` - 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: