Skip to content

api.md

Latest commit

 

History

History
421 lines (361 loc) · 7.68 KB

api.md

File metadata and controls

421 lines (361 loc) · 7.68 KB

📚 API Documentation

Service Endpoints and Contracts

🔗 Service Endpoints

PHP CRM Gateway

Base URL: http://localhost:8000 (local) / https://api.cloudvelous.com (production)

Lead Management

POST /api/leads
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "company": "Acme Corp",
  "source": "website",
  "notes": "Interested in enterprise plan"
}

Response:

{
  "id": "lead_123456",
  "status": "pending",
  "created_at": "2025-10-18T10:30:00Z",
  "message": "Lead created successfully"
}

Health Check

GET /health

Response:

{
  "status": "healthy",
  "timestamp": "2025-10-18T10:30:00Z",
  "version": "1.0.0",
  "services": {
    "database": "connected",
    "queue": "connected"
  }
}

C# Analytics API

Base URL: http://localhost:5000 (local) / https://analytics.cloudvelous.com (production)

Lead Analytics

GET /api/analytics/leads?date_from=2024-01-01&date_to=2024-01-31
Authorization: Bearer <jwt_token>

Response:

{
  "total_leads": 1250,
  "conversion_rate": 0.15,
  "leads_by_source": {
    "website": 800,
    "social": 300,
    "referral": 150
  },
  "leads_by_status": {
    "new": 500,
    "contacted": 400,
    "qualified": 250,
    "converted": 100
  },
  "trends": {
    "daily": [
      {"date": "2024-01-01", "count": 45},
      {"date": "2024-01-02", "count": 52}
    ]
  }
}

Sentiment Analysis

GET /api/analytics/sentiment?lead_id=lead_123456
Authorization: Bearer <jwt_token>

Response:

{
  "lead_id": "lead_123456",
  "sentiment": "positive",
  "confidence": 0.85,
  "entities": ["product", "pricing", "support"],
  "analysis_date": "2025-10-18T10:30:00Z"
}

Python AI Agent

Base URL: http://localhost:8001 (local) / https://ai.cloudvelous.com (production)

Text Analysis

POST /api/analyze
Content-Type: application/json

{
  "text": "I love your product! The pricing is great and support is excellent.",
  "analysis_type": "sentiment"
}

Response:

{
  "sentiment": "positive",
  "confidence": 0.92,
  "entities": [
    {"text": "product", "type": "product", "confidence": 0.95},
    {"text": "pricing", "type": "feature", "confidence": 0.88},
    {"text": "support", "type": "service", "confidence": 0.90}
  ],
  "summary": "Highly positive feedback about product, pricing, and support"
}

Lead Classification

POST /api/classify-lead
Content-Type: application/json

{
  "lead_id": "lead_123456",
  "text_content": "We're looking for an enterprise solution for 500+ users",
  "context": {
    "company_size": "large",
    "industry": "technology"
  }
}

Response:

{
  "lead_id": "lead_123456",
  "classification": "enterprise",
  "confidence": 0.89,
  "priority": "high",
  "recommended_action": "schedule_demo",
  "tags": ["enterprise", "large_company", "high_value"]
}

📋 Data Contracts

Lead Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^lead_[a-zA-Z0-9]+$"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "phone": {
      "type": "string",
      "pattern": "^\\+?[1-9]\\d{1,14}$"
    },
    "company": {
      "type": "string",
      "maxLength": 100
    },
    "source": {
      "type": "string",
      "enum": ["website", "social", "referral", "email", "phone"]
    },
    "status": {
      "type": "string",
      "enum": ["new", "contacted", "qualified", "converted", "lost"]
    },
    "notes": {
      "type": "string",
      "maxLength": 1000
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": ["id", "name", "email", "source", "status", "created_at"]
}

Analytics Response Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "total_leads": {
      "type": "integer",
      "minimum": 0
    },
    "conversion_rate": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "leads_by_source": {
      "type": "object",
      "additionalProperties": {
        "type": "integer",
        "minimum": 0
      }
    },
    "leads_by_status": {
      "type": "object",
      "additionalProperties": {
        "type": "integer",
        "minimum": 0
      }
    },
    "trends": {
      "type": "object",
      "properties": {
        "daily": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "date": {
                "type": "string",
                "format": "date"
              },
              "count": {
                "type": "integer",
                "minimum": 0
              }
            },
            "required": ["date", "count"]
          }
        }
      }
    }
  },
  "required": ["total_leads", "conversion_rate"]
}

🔐 Authentication

JWT Token Structure

{
  "header": {
    "alg": "RS256",
    "typ": "JWT"
  },
  "payload": {
    "sub": "user_123456",
    "iss": "cloudvelous.com",
    "aud": "cloudvelous-api",
    "exp": 1642234567,
    "iat": 1642148167,
    "scope": ["read:leads", "write:analytics"],
    "role": "analyst"
  }
}

API Key Authentication

GET /api/analytics/leads
X-API-Key: ak_1234567890abcdef

📊 Error Responses

Standard Error Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ],
    "timestamp": "2025-10-18T10:30:00Z",
    "request_id": "req_123456789"
  }
}

HTTP Status Codes

Code Description Usage
200 OK Successful GET, PUT, PATCH
201 Created Successful POST
400 Bad Request Invalid request data
401 Unauthorized Missing or invalid authentication
403 Forbidden Insufficient permissions
404 Not Found Resource not found
422 Unprocessable Entity Validation errors
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error
503 Service Unavailable Service temporarily unavailable

🔄 Webhook Events

Lead Created Event

{
  "event": "lead.created",
  "timestamp": "2025-10-18T10:30:00Z",
  "data": {
    "lead_id": "lead_123456",
    "name": "John Doe",
    "email": "john@example.com",
    "source": "website"
  }
}

Lead Status Updated Event

{
  "event": "lead.status_updated",
  "timestamp": "2025-10-18T10:30:00Z",
  "data": {
    "lead_id": "lead_123456",
    "old_status": "new",
    "new_status": "contacted",
    "updated_by": "user_789"
  }
}

📈 Rate Limits

Endpoint Limit Window
/api/leads 100 requests 1 minute
/api/analytics/* 50 requests 1 minute
/api/analyze 20 requests 1 minute
/health 1000 requests 1 minute

🧪 Testing Endpoints

Test Data Generation

POST /api/test/generate-leads
Content-Type: application/json

{
  "count": 10,
  "source": "website"
}

Mock Responses

GET /api/test/mock-analytics

Response:

{
  "total_leads": 1000,
  "conversion_rate": 0.12,
  "leads_by_source": {
    "website": 600,
    "social": 250,
    "referral": 150
  }
}

This API documentation is maintained by the Cloudvelous team and updated with each API change.