# Mobile App API Endpoints Design
## Overview
This document outlines the comprehensive API endpoints for the mobile application serving both B2B and B2C clients. The API follows RESTful conventions and uses Laravel Sanctum for authentication.
## Implementation Status
**Last Updated:** July 4, 2026
### ✅ Implemented Controllers
- **AuthController** - Registration (B2C/B2B), login, logout, password reset, email verification
- **UserController** - Profile management, preferences, favorites, notifications, booking history
- **VenueApiController** - Venue listing, search, details, availability, reviews, favorites
- **BookingManagementController** - Booking CRUD, cancellation, refunds
- **CompanyController** - B2B company profile, workspaces, bookings, user management, invoices
### ✅ Implemented Routes
All routes have been added to `routes/api.php` with proper authentication middleware grouping.
### 📋 Planned but Not Yet Implemented
- Payment endpoints (beyond existing MyPOS integration)
- Invoice download endpoints
- Knowledge base endpoints
- Support ticket endpoints
- Webhook endpoints
### 🔧 Existing Routes Preserved
- MyPOS payment integration (online & in-person)
- Fiscal receipt management
- Location search & geocoding
- Category management
- Venue translations
- Booking scanner (QR code, check-in/out)
## Base URL
```
https://api.zapazime.com/api/v1
```
## Authentication
All protected endpoints require Bearer token authentication via Laravel Sanctum.
## Response Format
All responses follow this structure:
```json
{
"success": true|false,
"data": {},
"message": "string",
"errors": {}
}
```
---
## 1. Authentication Endpoints
### 1.1 User Registration
```
POST /auth/register
POST /auth/register/b2b
```
**Request Body:**
```json
{
"name": "string",
"email": "string",
"phone": "string",
"password": "string",
"password_confirmation": "string",
"client_type_id": "integer (optional for B2C)",
"company_name": "string (B2B only)",
"company_vat": "string (B2B only)",
"locale": "string (en, bg, ru)"
}
```
### 1.2 User Login
```
POST /auth/login
```
**Request Body:**
```json
{
"email": "string",
"password": "string",
"device_name": "string"
}
```
**Response:**
```json
{
"success": true,
"data": {
"user": {
"id": 1,
"name": "string",
"email": "string",
"phone": "string",
"avatar": "string"
},
"token": "string"
}
}
```
### 1.3 Logout
```
POST /auth/logout
```
*Requires authentication*
### 1.4 Refresh Token
```
POST /auth/refresh
```
*Requires authentication*
### 1.5 Forgot Password
```
POST /auth/forgot-password
```
**Request Body:**
```json
{
"email": "string"
}
```
### 1.6 Reset Password
```
POST /auth/reset-password
```
**Request Body:**
```json
{
"token": "string",
"email": "string",
"password": "string",
"password_confirmation": "string"
}
```
### 1.7 Verify Email
```
POST /auth/verify-email/{token}
```
### 1.8 Resend Verification Email
```
POST /auth/resend-verification
```
*Requires authentication*
---
## 2. User Profile Endpoints
### 2.1 Get Profile
```
GET /user/profile
```
*Requires authentication*
### 2.2 Update Profile
```
PUT /user/profile
```
*Requires authentication*
**Request Body:**
```json
{
"name": "string",
"phone": "string",
"avatar": "file",
"locale": "string"
}
```
### 2.3 Change Password
```
POST /user/change-password
```
*Requires authentication*
**Request Body:**
```json
{
"current_password": "string",
"password": "string",
"password_confirmation": "string"
}
```
### 2.4 User Preferences
```
GET /user/preferences
PUT /user/preferences
```
*Requires authentication*
**Request Body:**
```json
{
"notification_email": "boolean",
"notification_push": "boolean",
"language": "string",
"currency": "string"
}
```
---
## 3. Venue Endpoints
### 3.1 List Venues
```
GET /venues
```
**Query Parameters:**
- `location_id` - Filter by location
- `category_id` - Filter by category
- `booking_type` - Filter by booking type (rentals, spots, services)
- `min_price` - Minimum price
- `max_price` - Maximum price
- `guests` - Number of guests
- `check_in` - Check-in date (YYYY-MM-DD)
- `check_out` - Check-out date (YYYY-MM-DD)
- `lat` - Latitude for geolocation search
- `lng` - Longitude for geolocation search
- `radius` - Search radius in km
- `sort` - Sorting (price_asc, price_desc, rating, newest)
- `page` - Page number
- `limit` - Items per page (default: 20, max: 100)
### 3.2 Get Venue Details
```
GET /venues/{id}
```
**Response:**
```json
{
"success": true,
"data": {
"id": 1,
"name": "string",
"description": "string",
"address": "string",
"city": "string",
"country": "string",
"latitude": "decimal",
"longitude": "decimal",
"phone": "string",
"email": "string",
"capacity": "integer",
"booking_type": "string",
"type": "string",
"image_url": "string",
"gallery_images": ["url1", "url2"],
"lowest_price": {
"price": 100.00,
"currency": "EUR",
"unit": "day",
"formatted": "EUR 100.00 / Day"
},
"average_rating": "decimal",
"total_reviews": "integer",
"facilities": ["WiFi", "Pool", "Parking"],
"venue_objects": [],
"venue_services": [],
"venue_packages": [],
"location": {},
"place": {}
}
}
```
### 3.3 Search Venues
```
GET /venues/search
```
**Query Parameters:**
- `q` - Search query (name, city, address)
- All filters from list venues
### 3.4 Get Venue Availability
```
GET /venues/{id}/availability
```
**Query Parameters:**
- `check_in` - Check-in date (required)
- `check_out` - Check-out date (required)
- `venue_object_id` - Specific venue object (optional)
### 3.5 Get Venue Reviews
```
GET /venues/{id}/reviews
```
**Query Parameters:**
- `page` - Page number
- `limit` - Items per page
- `sort` - Sorting (newest, highest, lowest)
### 3.6 Add Venue Review
```
POST /venues/{id}/reviews
```
*Requires authentication*
**Request Body:**
```json
{
"rating": "integer (1-5)",
"cleanliness": "integer (1-5)",
"location": "integer (1-5)",
"service": "integer (1-5)",
"value": "integer (1-5)",
"comment": "string"
}
```
### 3.7 Toggle Venue Favorite
```
POST /venues/{id}/favorite
```
*Requires authentication*
### 3.8 Get User Favorites
```
GET /user/favorites
```
*Requires authentication*
---
## 4. Venue Objects Endpoints
### 4.1 Get Venue Objects
```
GET /venues/{venue_id}/objects
```
**Query Parameters:**
- `check_in` - Check-in date
- `check_out` - Check-out date
- `guests` - Number of guests
### 4.2 Get Venue Object Details
```
GET /venue-objects/{id}
```
**Response:**
```json
{
"success": true,
"data": {
"id": 1,
"venue_id": 1,
"name": "string",
"description": "string",
"capacity": "integer",
"bedrooms": "integer",
"bathrooms": "integer",
"price": "decimal",
"currency": "string",
"booking_time_unit": "string (hour, day, week)",
"is_available": "boolean",
"images": ["url1", "url2"],
"amenities": ["WiFi", "AC", "TV"],
"venue": {}
}
}
```
---
## 5. Venue Spots Endpoints
### 5.1 Get Venue Spots
```
GET /venues/{venue_id}/spots
```
**Query Parameters:**
- `date` - Date for availability
- `start_time` - Start time
- `end_time` - End time
### 5.2 Get Venue Spot Details
```
GET /venue-spots/{id}
```
---
## 6. Booking Endpoints
### 6.1 Create Booking
```
POST /bookings
```
*Requires authentication*
**Request Body:**
```json
{
"venue_id": "integer",
"venue_object_id": "integer (optional)",
"venue_spot_id": "integer (optional)",
"booking_type": "string (rentals, spots, services)",
"check_in": "datetime",
"check_out": "datetime",
"num_adults": "integer",
"num_children": "integer",
"guests": [
{
"name": "string",
"age": "integer",
"gender": "string"
}
],
"services": [
{
"venue_service_id": "integer",
"quantity": "integer"
}
],
"packages": [
{
"venue_package_id": "integer",
"quantity": "integer"
}
],
"special_requests": "string",
"payment_method": "string"
}
```
### 6.2 Get User Bookings
```
GET /user/bookings
```
*Requires authentication*
**Query Parameters:**
- `status` - Filter by status (pending, confirmed, checked_in, checked_out, completed, cancelled)
- `booking_type` - Filter by booking type
- `page` - Page number
- `limit` - Items per page
### 6.3 Get Booking Details
```
GET /bookings/{id}
```
*Requires authentication* (user must own the booking)
### 6.4 Update Booking
```
PUT /bookings/{id}
```
*Requires authentication*
### 6.5 Cancel Booking
```
POST /bookings/{id}/cancel
```
*Requires authentication*
**Request Body:**
```json
{
"reason": "string"
}
```
### 6.6 Get Booking Refund Info
```
GET /bookings/{id}/refund-info
```
*Requires authentication*
### 6.7 Request Booking Refund
```
POST /bookings/{id}/refund
```
*Requires authentication*
### 6.8 Check-in via QR
```
POST /bookings/{id}/check-in
```
*Used by venue staff*
### 6.9 Check-out via QR
```
POST /bookings/{id}/check-out
```
*Used by venue staff*
### 6.10 Get Booking by QR Code
```
GET /bookings/qr/{qr_code}
```
*Used by venue staff*
---
## 7. Payment Endpoints
### 7.1 Get Payment Methods
```
GET /payment-methods
```
### 7.2 Create Payment Intent
```
POST /payments/create-intent
```
*Requires authentication*
**Request Body:**
```json
{
"booking_id": "integer",
"amount": "decimal",
"currency": "string",
"payment_method": "string"
}
```
### 7.3 Confirm Payment
```
POST /payments/confirm
```
*Requires authentication*
**Request Body:**
```json
{
"payment_intent_id": "string",
"payment_method_id": "string"
}
```
### 7.4 Get Payment History
```
GET /user/payments
```
*Requires authentication*
### 7.5 Get Payment Details
```
GET /payments/{id}
```
*Requires authentication*
### 7.6 MyPOS Integration (B2B)
```
POST /payments/mypos/create
POST /payments/mypos/confirm
POST /payments/mypos/void
POST /payments/mypos/refund
```
*Requires authentication*
---
## 8. Invoice Endpoints
### 8.1 Get User Invoices
```
GET /user/invoices
```
*Requires authentication*
### 8.2 Get Invoice Details
```
GET /invoices/{id}
```
*Requires authentication*
### 8.3 Download Invoice PDF
```
GET /invoices/{id}/download
```
*Requires authentication*
---
## 9. Location Endpoints
### 9.1 Get Locations
```
GET /locations
```
**Query Parameters:**
- `country_id` - Filter by country
- `city_id` - Filter by city
- `q` - Search query
### 9.2 Get Location Details
```
GET /locations/{id}
```
### 9.3 Get Countries
```
GET /countries
```
### 9.4 Get Cities
```
GET /cities
```
**Query Parameters:**
- `country_id` - Filter by country
### 9.5 Location Search (Auto-suggest)
```
GET /locations/suggest
GET /locations/search
GET /locations/advanced-search
```
---
## 10. Category Endpoints
### 10.1 Get Categories
```
GET /categories
```
**Query Parameters:**
- `booking_type` - Filter by booking type
### 10.2 Get Category Details
```
GET /categories/{id}
```
---
## 11. Geocoding Endpoints
### 11.1 Geocode Address
```
POST /geocode/address
```
**Request Body:**
```json
{
"address": "string"
}
```
### 11.2 Reverse Geocode
```
POST /geocode/reverse
```
**Request Body:**
```json
{
"latitude": "decimal",
"longitude": "decimal"
}
```
### 11.3 Validate Coordinates
```
POST /geocode/validate
```
**Request Body:**
```json
{
"latitude": "decimal",
"longitude": "decimal"
}
```
---
## 12. B2B Specific Endpoints
### 12.1 Company Management
#### Get Company Profile
```
GET /company/profile
```
*Requires B2B authentication*
#### Update Company Profile
```
PUT /company/profile
```
*Requires B2B authentication*
**Request Body:**
```json
{
"name": "string",
"vat_number": "string",
"address": "string",
"phone": "string",
"email": "string",
"logo": "file"
}
```
#### Get Company Workspaces
```
GET /company/workspaces
```
*Requires B2B authentication*
#### Create Workspace
```
POST /company/workspaces
```
*Requires B2B authentication*
**Request Body:**
```json
{
"name": "string",
"address": "string",
"phone": "string",
"email": "string"
}
```
### 12.2 Company Bookings
#### Get Company Bookings
```
GET /company/bookings
```
*Requires B2B authentication*
**Query Parameters:**
- `workspace_id` - Filter by workspace
- `status` - Filter by status
- `date_from` - Start date
- `date_to` - End date
- `page` - Page number
#### Create Company Booking
```
POST /company/bookings
```
*Requires B2B authentication*
**Request Body:**
```json
{
"workspace_id": "integer",
"venue_id": "integer",
"booking_type": "string",
"check_in": "datetime",
"check_out": "datetime",
"num_employees": "integer",
"contact_person": "string",
"contact_phone": "string",
"special_requests": "string",
"po_number": "string",
"cost_center": "string"
}
```
### 12.3 Company Invoices
#### Get Company Invoices
```
GET /company/invoices
```
*Requires B2B authentication*
#### Get Company Invoice Details
```
GET /company/invoices/{id}
```
*Requires B2B authentication*
### 12.4 Company Users
#### Get Company Users
```
GET /company/users
```
*Requires B2B admin authentication*
#### Invite Company User
```
POST /company/users/invite
```
*Requires B2B admin authentication*
**Request Body:**
```json
{
"email": "string",
"role": "string (admin, user, viewer)",
"workspace_id": "integer"
}
```
#### Remove Company User
```
DELETE /company/users/{id}
```
*Requires B2B admin authentication*
---
## 13. Notification Endpoints
### 13.1 Get User Notifications
```
GET /user/notifications
```
*Requires authentication*
**Query Parameters:**
- `read` - Filter by read status (true, false)
- `type` - Filter by type
- `page` - Page number
### 13.2 Mark Notification as Read
```
POST /user/notifications/{id}/read
```
*Requires authentication*
### 13.3 Mark All Notifications as Read
```
POST /user/notifications/read-all
```
*Requires authentication*
### 13.4 Get Notification Preferences
```
GET /user/notification-preferences
```
*Requires authentication*
### 13.5 Update Notification Preferences
```
PUT /user/notification-preferences
```
*Requires authentication*
**Request Body:**
```json
{
"email_notifications": "boolean",
"push_notifications": "boolean",
"sms_notifications": "boolean",
"booking_updates": "boolean",
"payment_reminders": "boolean",
"promotional": "boolean"
}
```
---
## 14. Knowledge Base Endpoints
### 14.1 Get Knowledge Base Articles
```
GET /knowledge-base
```
**Query Parameters:**
- `category` - Filter by category
- `q` - Search query
- `locale` - Language (en, bg, ru)
### 14.2 Get Article Details
```
GET /knowledge-base/{id}
```
---
## 15. Fiscal Receipt Endpoints (B2B)
### 15.1 Get Pending Fiscal Receipts
```
GET /fiscal-receipts/pending
```
*Requires authentication*
### 15.2 Get Fiscal Receipt Status
```
GET /fiscal-receipts/status
```
*Requires authentication*
### 15.3 Mark Receipt as Processing
```
PATCH /fiscal-receipts/{receipt}/processing
```
*Requires authentication*
### 15.4 Mark Receipt as Printed
```
PATCH /fiscal-receipts/{receipt}/printed
```
*Requires authentication*
### 15.5 Mark Receipt as Failed
```
PATCH /fiscal-receipts/{receipt}/failed
```
*Requires authentication*
---
## 16. Support & Help Endpoints
### 16.1 Submit Support Ticket
```
POST /support/tickets
```
*Requires authentication*
**Request Body:**
```json
{
"subject": "string",
"category": "string",
"priority": "string (low, medium, high)",
"description": "string",
"attachments": ["file"]
}
```
### 16.2 Get User Support Tickets
```
GET /user/support-tickets
```
*Requires authentication*
### 16.3 Get Support Ticket Details
```
GET /support/tickets/{id}
```
*Requires authentication*
---
## Error Codes
| Code | Description |
|------|-------------|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 422 | Validation Error |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
## Rate Limiting
- **Authenticated users**: 1000 requests per hour
- **Unauthenticated users**: 100 requests per hour
- **B2B endpoints**: 2000 requests per hour
## Pagination
All list endpoints support pagination:
- `page` - Page number (default: 1)
- `limit` - Items per page (default: 20, max: 100)
Response includes:
```json
{
"data": [],
"meta": {
"current_page": 1,
"per_page": 20,
"total": 100,
"last_page": 5
}
}
```
## Localization
All endpoints support localization via:
- `Accept-Language` header: `en`, `bg`, `ru`
- `locale` query parameter
## Versioning
API version is included in the URL: `/api/v1/`
Future versions will be: `/api/v2/`, etc.
## Webhooks (B2B)
### Booking Webhooks
```
POST /webhooks/booking-created
POST /webhooks/booking-confirmed
POST /webhooks/booking-cancelled
POST /webhooks/booking-completed
```
### Payment Webhooks
```
POST /webhooks/payment-succeeded
POST /webhooks/payment-failed
POST /webhooks/payment-refunded
```
## Security
- All sensitive endpoints require authentication
- API tokens expire after 30 days
- Refresh tokens available
- Rate limiting enforced
- Input validation on all endpoints
- SQL injection protection
- XSS protection
- CSRF protection for web endpoints
## Testing
Use the test endpoint to verify API connectivity:
```
GET /api/v1/test
```
Response:
```json
{
"message": "API is working",
"timestamp": "2026-07-04T14:26:00Z"
}
```
---
## Changelog / Revision History
### v1.0.0 - July 4, 2026
**Initial Release**
**Implemented:**
- ✅ Authentication endpoints (B2C/B2B registration, login, logout, password reset, email verification)
- ✅ User profile management (profile CRUD, preferences, favorites)
- ✅ Venue endpoints (listing, search, details, availability, reviews, favorites)
- ✅ Booking management (CRUD, cancellation, refunds)
- ✅ B2B Company management (profile, workspaces, bookings, users, invoices)
- ✅ User notifications (listing, read status, preferences)
- ✅ Location search & geocoding (existing)
- ✅ Category management (existing)
- ✅ Fiscal receipt management (existing)
- ✅ MyPOS payment integration (existing)
- ✅ Booking scanner/QR code functionality (existing)
**Documentation:**
- Created comprehensive API design document
- Created OpenAPI 3.0 specification (openapi.yaml)
- Added implementation status tracking
**Controllers Created:**
- AuthController.php
- UserController.php
- VenueApiController.php
- BookingManagementController.php
- CompanyController.php
**Routes Updated:**
- routes/api.php - Added all new endpoints with proper authentication middleware
---
## Future Enhancements
### Planned Endpoints
- Payment processing endpoints (beyond MyPOS)
- Invoice download/preview endpoints
- Knowledge base article endpoints
- Support ticket management
- Webhook subscriptions
- Real-time notifications (WebSocket/SSE)
- Advanced search filters
- Analytics and reporting endpoints
### Performance Improvements
- Response caching
- Database query optimization
- API response compression
- Rate limiting per endpoint type
### Security Enhancements
- API key authentication for B2B partners
- Enhanced rate limiting
- Request signing
- IP whitelisting for enterprise clients