maciejpi/nordabiz
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Maciej Pienczyn 2026-01-10 09:43:53 +01:00
parent 40ff7e950e
commit d74889a1c6
1 changed files with 308 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

308
README.md
View File

@ -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`.** **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 ## Roadmap & Future Enhancements
While the platform is fully functional and in production, the following features are planned for future releases: While the platform is fully functional and in production, the following features are planned for future releases: