Data Models
==========

This section describes the main data models and structures used in the Taglife API.

User Models
-----------

User Profile
~~~~~~~~~~~~

.. code-block:: json

   {
     "id": 123,
     "username": "user123",
     "email": "user@example.com",
     "first_name": "John",
     "last_name": "Doe",
     "date_joined": "2024-01-01T00:00:00Z",
     "last_login": "2024-08-01T10:00:00Z",
     "is_active": true,
     "is_staff": false,
     "is_superuser": false,
     "country": {
       "id": 1,
       "name": "United States"
     },
     "city": {
       "id": 1,
       "name": "New York"
     },
     "language": "en",
     "timezone": "UTC"
   }

User Preferences
~~~~~~~~~~~~~~~

.. code-block:: json

   {
     "user_id": 123,
     "language": "en",
     "notifications": {
       "new_campaign": true,
       "end_campaign": true,
       "near_campaign": true,
       "cause_campaign": true,
       "profile_status": true,
       "post_status": true,
       "update_balance": true
     },
     "categories": ["fashion", "beauty", "technology"],
     "networks": ["instagram", "facebook"],
     "privacy_settings": {
       "profile_public": true,
       "show_earnings": false,
       "show_campaigns": true
     }
   }

Campaign Models
---------------

Campaign
~~~~~~~~

.. code-block:: json

   {
     "id": 123,
     "type": "influencer",
     "name": "Summer Fashion Campaign",
     "tagline": "Show off your summer style",
     "description": "Promote our latest summer collection",
     "image_logo": "https://example.com/logo.jpg",
     "image_post": "https://example.com/post.jpg",
     "hashtags": ["#summer", "#fashion"],
     "date_created": "2024-08-01T00:00:00Z",
     "date_start": "2024-08-01T00:00:00Z",
     "date_end": "2024-08-31T23:59:59Z",
     "status": "active",
     "networks": ["instagram", "facebook"],
     "currency": "USD",
     "advertiser": {
       "id": 456,
       "name": "Fashion Brand",
       "email": "contact@fashionbrand.com"
     },
     "settings": {
       "post_rate": 25,
       "has_bonus": true,
       "promo_reach_bonus": 50,
       "promo_engagement_rate_bonus": 25,
       "promo_best_post_bonus": 100,
       "maximum_task_complete_hours": 72
     },
     "statistics": {
       "total_participants": 50,
       "active_participants": 35,
       "completed_tasks": 150,
       "total_reach": 50000,
       "total_engagement": 2500
     }
   }

Task
~~~~~

.. code-block:: json

   {
     "id": 456,
     "campaign_id": 123,
     "type": "post",
     "title": "Create Instagram Post",
     "description": "Post about our summer collection",
     "requirements": "Include hashtags and tag our brand",
     "deadline": "2024-08-31T23:59:59Z",
     "status": "pending",
     "assigned_to": 789,
     "assigned_at": "2024-08-01T10:00:00Z",
     "completed_at": null,
     "bonus": {
       "reach": 50,
       "engagement_rate": 25,
       "best_post": 100
     },
     "payments": {
       "minimum": 25,
       "post": 30,
       "total": 30
     },
     "submissions": [
       {
         "id": 1,
         "post_url": "https://instagram.com/p/example",
         "screenshots": ["https://example.com/screenshot1.jpg"],
         "reach": 1000,
         "engagement": 50,
         "submitted_at": "2024-08-15T10:00:00Z",
         "status": "pending_review"
       }
     ]
   }

Social Network Models
---------------------

Social Network
~~~~~~~~~~~~~

.. code-block:: json

   {
     "id": 123,
     "user_id": 456,
     "network": "instagram",
     "network_id": "user123",
     "network_url": "https://instagram.com/user123",
     "status": "accepted",
     "followers": 5000,
     "verified": true,
     "category": "fashion",
     "engagement_rate": 3.5,
     "connected_at": "2024-01-01T00:00:00Z",
     "last_updated": "2024-08-01T10:00:00Z",
     "extra_data": {
       "bio": "Fashion influencer",
       "website": "https://example.com",
       "verified_badge": true
     }
   }

Social Page
~~~~~~~~~~~

.. code-block:: json

   {
     "id": 456,
     "user_id": 456,
     "network": "facebook",
     "page_id": "page123",
     "page_name": "Fashion Blog",
     "page_url": "https://facebook.com/page123",
     "status": "accepted",
     "followers": 10000,
     "category": "fashion",
     "engagement_rate": 2.8,
     "connected_at": "2024-01-01T00:00:00Z",
     "last_updated": "2024-08-01T10:00:00Z",
     "extra_data": {
       "description": "Fashion and lifestyle blog",
       "category": "Fashion",
       "verification_status": "verified"
     }
   }

Social Wall
~~~~~~~~~~~

.. code-block:: json

   {
     "id": 789,
     "user_id": 456,
     "network": "instagram",
     "wall_id": "wall123",
     "wall_name": "Fashion Wall",
     "wall_url": "https://instagram.com/wall123",
     "status": "accepted",
     "followers": 5000,
     "category": "fashion",
     "engagement_rate": 4.2,
     "connected_at": "2024-01-01T00:00:00Z",
     "last_updated": "2024-08-01T10:00:00Z",
     "extra_data": {
       "description": "Curated fashion content",
       "posts_count": 150,
       "average_likes": 200
     }
   }

Social Channel
~~~~~~~~~~~~~

.. code-block:: json

   {
     "id": 101,
     "user_id": 456,
     "network": "youtube",
     "channel_id": "channel123",
     "channel_name": "Fashion Channel",
     "channel_url": "https://youtube.com/channel123",
     "status": "accepted",
     "subscribers": 15000,
     "category": "fashion",
     "engagement_rate": 5.1,
     "connected_at": "2024-01-01T00:00:00Z",
     "last_updated": "2024-08-01T10:00:00Z",
     "extra_data": {
       "description": "Fashion and beauty videos",
       "videos_count": 50,
       "average_views": 5000
     }
   }

Payment Models
--------------

Payout
~~~~~~

.. code-block:: json

   {
     "id": 123,
     "user_id": 456,
     "amount": 500,
     "currency": "USD",
     "status": "completed",
     "method": "bank_transfer",
     "bank_account": {
       "id": 456,
       "bank_name": "Chase Bank",
       "account_number": "****1234",
       "routing_number": "****0021",
       "account_type": "checking",
       "account_holder_name": "John Doe"
     },
     "paypal_email": null,
     "stripe_account": null,
     "requested_at": "2024-08-01T10:00:00Z",
     "processed_at": "2024-08-02T15:30:00Z",
     "cancelled_at": null,
     "reference": "PAY-2024-001",
     "transaction_id": "TXN-2024-001",
     "notes": "Processed via bank transfer",
     "fees": 0,
     "net_amount": 500
   }

Bank Account
~~~~~~~~~~~~

.. code-block:: json

   {
     "id": 456,
     "user_id": 456,
     "bank_name": "Chase Bank",
     "account_number": "****1234",
     "routing_number": "****0021",
     "account_type": "checking",
     "account_holder_name": "John Doe",
     "is_primary": true,
     "verified": true,
     "verification_status": "verified",
     "created_at": "2024-01-01T00:00:00Z",
     "updated_at": "2024-08-01T10:00:00Z"
   }

User Balance
~~~~~~~~~~~~

.. code-block:: json

   {
     "user_id": 456,
     "available_balance": 750,
     "pending_balance": 250,
     "total_earned": 5000,
     "total_paid": 4000,
     "currency": "USD",
     "minimum_payout": 50,
     "last_updated": "2024-08-01T10:00:00Z"
   }

Notification Models
-------------------

Notification
~~~~~~~~~~~~

.. code-block:: json

   {
     "id": 456,
     "user_id": 123,
     "title": "New Campaign Available",
     "message": "A new fashion campaign is available for you",
     "type": "campaign",
     "read": false,
     "created_at": "2024-08-01T10:00:00Z",
     "data": {
       "campaign_id": 789,
       "campaign_name": "Summer Fashion Campaign"
     }
   }

Notification Settings
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: json

   {
     "user_id": 123,
     "new_campaign": true,
     "end_campaign": true,
     "near_campaign": true,
     "cause_campaign": true,
     "profile_status": true,
     "post_status": true,
     "update_balance": true
   }

Location Models
---------------

Country
~~~~~~~

.. code-block:: json

   {
     "id": 1,
     "name": "United States",
     "code": "US",
     "currency_code": "USD",
     "currency_symbol": "$",
     "timezone": "UTC",
     "utc_offset": 0
   }

City
~~~~

.. code-block:: json

   {
     "id": 1,
     "name": "New York",
     "country_id": 1,
     "country_name": "United States",
     "timezone": "America/New_York",
     "utc_offset": -300
   }

Category Models
---------------

Category
~~~~~~~~

.. code-block:: json

   {
     "id": 1,
     "name": "Fashion",
     "description": "Fashion and style related content",
     "icon": "fashion-icon.png",
     "color": "#FF6B6B",
     "active": true
   }

Network Models
--------------

Network
~~~~~~~

.. code-block:: json

   {
     "id": 1,
     "name": "instagram",
     "display_name": "Instagram",
     "description": "Instagram social network",
     "icon": "instagram-icon.png",
     "color": "#E4405F",
     "active": true,
     "features": ["posts", "stories", "reels"]
   }

Statistics Models
-----------------

Campaign Statistics
~~~~~~~~~~~~~~~~~~

.. code-block:: json

   {
     "campaign_id": 123,
     "total_participants": 50,
     "active_participants": 35,
     "completed_tasks": 150,
     "total_reach": 50000,
     "total_engagement": 2500,
     "average_engagement_rate": 5.0,
     "total_spent": 3750,
     "currency": "USD",
     "by_network": {
       "instagram": {
         "posts": 50,
         "reach": 10000,
         "engagement": 500
       },
       "facebook": {
         "posts": 30,
         "reach": 8000,
         "engagement": 400
       }
     }
   }

User Statistics
~~~~~~~~~~~~~~~

.. code-block:: json

   {
     "user_id": 456,
     "total_campaigns": 10,
     "completed_tasks": 50,
     "total_earned": 1500,
     "total_reach": 100000,
     "total_engagement": 5000,
     "average_engagement_rate": 5.0,
     "currency": "USD",
     "by_category": {
       "fashion": 30,
       "beauty": 20,
       "technology": 10
     },
     "by_network": {
       "instagram": 40,
       "facebook": 30,
       "twitter": 20
     }
   }

Error Models
------------

API Error
~~~~~~~~~

.. code-block:: json

   {
     "error": "validation_error",
     "message": "Invalid email format",
     "field": "email",
     "code": "INVALID_EMAIL",
     "details": {
       "expected_format": "email@domain.com"
     }
   }

Authentication Error
~~~~~~~~~~~~~~~~~~~

.. code-block:: json

   {
     "error": "authentication_required",
     "message": "Authentication is required for this endpoint",
     "code": "AUTH_REQUIRED",
     "details": {
       "required_scopes": ["read", "write"]
     }
   }

Common Field Types
------------------

Date Fields
~~~~~~~~~~~

All date fields in the API use ISO 8601 format:

.. code-block:: text

   YYYY-MM-DDTHH:MM:SSZ

Examples:
- "2024-08-01T10:00:00Z"
- "2024-08-01T10:00:00+00:00"

Status Fields
~~~~~~~~~~~~

Common status values used across the API:

**Campaign Status:**
- `draft`: Campaign is in draft mode
- `pending`: Campaign is pending approval
- `active`: Campaign is active and accepting participants
- `paused`: Campaign is temporarily paused
- `completed`: Campaign has ended
- `cancelled`: Campaign has been cancelled

**Task Status:**
- `pending`: Task is available for assignment
- `assigned`: Task has been assigned to a user
- `in_progress`: User is working on the task
- `submitted`: Task has been submitted for review
- `approved`: Task has been approved
- `rejected`: Task has been rejected
- `completed`: Task has been completed and paid

**Network Status:**
- `pending`: Network is submitted but not yet reviewed
- `accepted`: Network has been approved and is active
- `rejected`: Network has been rejected
- `suspended`: Network has been temporarily suspended
- `disconnected`: Network has been disconnected by user

**Payout Status:**
- `pending`: Payout request submitted but not yet processed
- `processing`: Payout is being processed
- `completed`: Payout has been successfully processed
- `rejected`: Payout request has been rejected
- `cancelled`: Payout request has been cancelled by user
- `failed`: Payout processing failed

Currency Fields
~~~~~~~~~~~~~~

All monetary values use ISO 4217 currency codes:

- `USD`: US Dollar
- `EUR`: Euro
- `PLN`: Polish Złoty
- `GBP`: British Pound

Network Fields
~~~~~~~~~~~~~

Supported social networks:

- `instagram`: Instagram
- `facebook`: Facebook
- `twitter`: Twitter
- `youtube`: YouTube
- `tiktok`: TikTok
- `linkedin`: LinkedIn
- `pinterest`: Pinterest

Language Fields
~~~~~~~~~~~~~~

Supported languages:

- `en`: English
- `es`: Spanish
- `pl`: Polish