campaigns

Ver en Git

---

Campaigns API Documentation

Base URL

/api/sales/campaigns

Authentication

All endpoints require JWT authentication. Include the JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Rate Limiting

All endpoints are limited to 10 requests per second.

---

Endpoints

1. Get All Campaigns

Retrieve all campaigns for the authenticated workspace, ordered by start date (most recent first).

Endpoint: GET /api/sales/campaigns/all

Request:

• Method: GET
• Headers: Authorization required
• Body: None

Response:

{
  "code": 0,
  "data": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "description": "Summer Campaign 2024",
      "workspace_id": 1,
      "start_date": "2024-06-01",
      "end_date": "2024-08-31"
    }
  ]
}

Response Fields:

• uuid: Unique campaign identifier (string, UUID format)
• description: Campaign description (string)
• workspace_id: Workspace ID (integer)
• start_date: Start date (string, YYYY-MM-DD format)
• end_date: End date (string, YYYY-MM-DD format)

---

2. Get Campaign by UUID

Retrieve a specific campaign by its UUID.

Endpoint: GET /api/sales/campaigns/campaign

Request:

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000"
}

Request Fields:

• uuid: Campaign UUID (string, required, UUID format)

Response:

{
  "code": 0,
  "data": {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "description": "Summer Campaign 2024",
    "workspace_id": 1,
    "start_date": "2024-06-01",
    "end_date": "2024-08-31"
  }
}

Error Codes:

• Code 4: "Campaign not found" - The specified campaign UUID doesn't exist or doesn't belong to the workspace

---

3. Create Campaign

Create a new campaign.

Endpoint: POST /api/sales/campaigns/campaign

Request:

{
  "action": "create",
  "description": "Summer Campaign 2024",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31"
}

Request Fields:

• action: Must be "create" (string, required)
• description: Campaign description (string, required, minimum 1 character)
• start_date: Start date (string, required, YYYY-MM-DD format)
• end_date: End date (string, required, YYYY-MM-DD format)

Response:

{
  "code": 0,
  "message": "Campaign created successfully",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "data": {
    "description": "Summer Campaign 2024",
    "start_date": "2024-06-01",
    "end_date": "2024-08-31"
  }
}

Error Codes:

• Code 5: "Invalid date format or values" - Invalid date format provided or start_date must be before end_date
• Code 6: "Dates overlap with another existing campaign" - The date range conflicts with an existing campaign

---

4. Update Campaign

Update an existing campaign.

Endpoint: POST /api/sales/campaigns/campaign

Request:

{
  "action": "update",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "description": "Updated Summer Campaign 2024",
  "start_date": "2024-06-15",
  "end_date": "2024-09-15"
}

Request Fields:

• action: Must be "update" (string, required)
• uuid: Campaign UUID (string, required, UUID format)
• description: Campaign description (string, required, minimum 1 character)
• start_date: Start date (string, required, YYYY-MM-DD format)
• end_date: End date (string, required, YYYY-MM-DD format)

Response:

{
  "code": 0,
  "message": "Campaign updated successfully",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "data": {
    "description": "Updated Summer Campaign 2024",
    "start_date": "2024-06-15",
    "end_date": "2024-09-15"
  }
}

Error Codes:

• Code 4: "Campaign not found or dates overlap" - Cannot update (campaign not found or dates overlap with another campaign)
• Code 5: "Invalid date format or values" - Invalid date format provided or start_date must be before end_date

---

5. Delete Campaign

Delete an existing campaign (soft delete).

Endpoint: POST /api/sales/campaigns/campaign

Request:

{
  "action": "delete",
  "uuid": "123e4567-e89b-12d3-a456-426614174000"
}

Request Fields:

• action: Must be "delete" (string, required)
• uuid: Campaign UUID (string, required, UUID format)

Response:

{
  "code": 0,
  "message": "Campaign deleted successfully",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "data": {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "description": "Summer Campaign 2024",
    "workspace_id": 1,
    "start_date": "2024-06-01",
    "end_date": "2024-08-31"
  }
}

Error Codes:

• Code 4: "Campaign not found" - The specified campaign UUID doesn't exist or doesn't belong to the workspace

---

Error Response Format

All error responses follow this format:

{
  "res": "error",
  "code": <error_code>,
  "info": "<error_description>"
}

HTTP Status Codes:

• 200: Success
• 400: Bad Request (validation errors)
• 401: Unauthorized (missing or invalid JWT token)
• 429: Too Many Requests (rate limit exceeded)
• 500: Internal Server Error

---

Business Rules

Date Validation

1. Date Range: start_date must be before end_date
2. Date Overlap: Campaign dates cannot overlap with other existing campaigns in the same workspace
3. Date Format: Dates must be in YYYY-MM-DD format

Overlap Detection

The system checks for date overlaps using the following logic:

• New campaign start date falls within an existing campaign's date range
• New campaign end date falls within an existing campaign's date range
• Existing campaign dates fall within the new campaign's date range

Soft Delete

• Campaigns are not physically deleted from the database
• Instead, the fecha_fin field is set to the current timestamp
• Deleted campaigns won't appear in list or get operations

---

Field Mapping

The API uses English field names in requests/responses, but the database uses Spanish names:

API Field	Database Field	Description
uuid	uuid_campaign	Campaign UUID
start_date	fecha_desde	Campaign start date
end_date	fecha_hasta	Campaign end date
description	description	Campaign description
workspace_id	id_escritorio	Workspace ID

---

Usage Examples

JavaScript/Fetch Example:

// Get all campaigns
const response = await fetch('/api/sales/campaigns/all', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  }
});

// Create campaign
const createResponse = await fetch('/api/sales/campaigns/campaign', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'create',
    description: 'Holiday Campaign 2024',
    start_date: '2024-12-01',
    end_date: '2024-12-31'
  })
});

// Update campaign
const updateResponse = await fetch('/api/sales/campaigns/campaign', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'update',
    uuid: '123e4567-e89b-12d3-a456-426614174000',
    description: 'Extended Holiday Campaign 2024',
    start_date: '2024-11-15',
    end_date: '2025-01-15'
  })
});

// Delete campaign
const deleteResponse = await fetch('/api/sales/campaigns/campaign', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'delete',
    uuid: '123e4567-e89b-12d3-a456-426614174000'
  })
});

Date Handling Tips:

// Convert JavaScript Date to API format
const formatDate = (date) => {
  return date.toISOString().split('T')[0]; // YYYY-MM-DD
};

// Example usage
const startDate = new Date('2024-06-01');
const endDate = new Date('2024-08-31');

const campaignData = {
  action: 'create',
  description: 'My Campaign',
  start_date: formatDate(startDate),
  end_date: formatDate(endDate)
};

---

Common Use Cases

1. Campaign Planning

When planning campaigns, ensure dates don't overlap:

1. Get all existing campaigns to check current date ranges
2. Choose non-overlapping dates for new campaigns
3. Create the campaign with validated dates

2. Campaign Management

For ongoing campaign management:

1. List all campaigns to see current status
2. Update campaign details as needed (description, dates)
3. Extend or shorten campaigns by updating dates (respecting overlap rules)

3. Campaign Cleanup

For removing old campaigns:

1. Get campaign details to confirm deletion
2. Delete campaigns that are no longer needed
3. Note that deleted campaigns are soft-deleted and can be recovered if needed