igny8/docs/working-docs/CORRECT-API-ENDPOINTS-REFERENCE.md

# CORRECT API Endpoints Reference
**Date:** December 5, 2025  
**Purpose:** Document ACTUAL working backend endpoints for frontend integration

## ✅ WORKING BILLING ENDPOINTS

### Credit Balance
**Endpoint:** `GET /v1/billing/credits/balance/balance/`  
**Returns:**
```json
{
  "success": true,
  "data": {
    "credits": 100,
    "plan_credits_per_month": 100,
    "credits_used_this_month": 0,
    "credits_remaining": 100
  }
}
```

### Credit Transactions
**Endpoint:** `GET /v1/billing/transactions/`  
**Returns:**
```json
{
  "success": true,
  "data": {
    "results": [
      {
        "id": 1,
        "amount": 100,
        "transaction_type": "grant",
        "description": "Initial credits",
        "created_at": "2025-12-05T10:00:00Z",
        "balance_after": 100
      }
    ],
    "count": 1
  }
}
```

### Credit Usage Logs
**Endpoint:** `GET /v1/billing/credits/usage/`  
**Returns:**
```json
{
  "success": true,
  "data": {
    "results": [
      {
        "id": 1,
        "operation_type": "clustering",
        "credits_used": 10,
        "cost_usd": "0.10",
        "created_at": "2025-12-05T10:00:00Z"
      }
    ],
    "count": 1
  }
}
```

### Invoices
**Endpoint:** `GET /v1/billing/invoices/`  
**Returns:**
```json
{
  "results": [
    {
      "id": 1,
      "invoice_number": "INV-2025-001",
      "status": "paid",
      "total_amount": "29.00",
      "created_at": "2025-12-05T10:00:00Z"
    }
  ],
  "count": 1
}
```

### Payments
**Endpoint:** `GET /v1/billing/payments/`  
**Returns:**
```json
{
  "results": [
    {
      "id": 1,
      "amount": "29.00",
      "status": "succeeded",
      "payment_method": "stripe",
      "created_at": "2025-12-05T10:00:00Z"
    }
  ],
  "count": 1
}
```

### Payment Methods
**Endpoint:** `GET /v1/billing/payment-methods/`  
**Returns:**
```json
{
  "results": [
    {
      "payment_method": "stripe",
      "display_name": "Credit/Debit Card",
      "is_enabled": true
    }
  ]
}
```

### Credit Packages
**Endpoint:** `GET /v1/billing/credit-packages/`  
**Returns:**
```json
{
  "results": [
    {
      "id": 1,
      "name": "Starter Pack",
      "credits": 500,
      "price": "9.00",
      "is_active": true
    }
  ],
  "count": 1
}
```

## ✅ WORKING ACCOUNT ENDPOINTS

### Account Settings
**Endpoint:** `GET /v1/account/settings/`  
**Returns:**
```json
{
  "id": 1,
  "name": "My Account",
  "slug": "my-account",
  "billing_address_line1": "123 Main St",
  "billing_city": "New York",
  "credit_balance": 100,
  "created_at": "2025-01-01T00:00:00Z"
}
```

### Update Account Settings
**Endpoint:** `PATCH /v1/account/settings/`  
**Body:**
```json
{
  "name": "Updated Account Name",
  "billing_address_line1": "456 New St"
}
```

### Team Members
**Endpoint:** `GET /v1/account/team/`  
**Returns:**
```json
{
  "results": [
    {
      "id": 1,
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "is_active": true,
      "is_staff": false,
      "date_joined": "2025-01-01T00:00:00Z"
    }
  ],
  "count": 1
}
```

### Usage Analytics
**Endpoint:** `GET /v1/account/usage/analytics/`  
**Query Params:** `?days=30`  
**Returns:**
```json
{
  "period_days": 30,
  "current_balance": 100,
  "usage_by_type": [
    {
      "transaction_type": "deduction",
      "total": -50,
      "count": 5
    }
  ],
  "daily_usage": [
    {
      "date": "2025-12-05",
      "usage": 10,
      "purchases": 0,
      "net": -10
    }
  ],
  "total_usage": 50,
  "total_purchases": 0
}
```

## ⚠️ CORRECT DATA STRUCTURE FOR PAGES

### AccountBillingPage.tsx
**Should use:**
- `getCreditBalance()` → `/v1/billing/credits/balance/balance/`
- `getInvoices()` → `/v1/billing/invoices/`
- `getPayments()` → `/v1/billing/payments/`

**Data fields to use:**
```typescript
creditBalance.credits  // NOT balance
creditBalance.plan_credits_per_month  // NOT monthly_credits
creditBalance.credits_used_this_month  // NEW field
```

### AccountSettingsPage.tsx
**Should use:**
- `getAccountSettings()` → `/v1/account/settings/`
- `updateAccountSettings(data)` → `PATCH /v1/account/settings/`

### TeamManagementPage.tsx
**Should use:**
- `getTeamMembers()` → `/v1/account/team/`
- `inviteTeamMember(email)` → `POST /v1/account/team/`
- `removeTeamMember(id)` → `DELETE /v1/account/team/{id}/`

### UsageAnalyticsPage.tsx
**Should use:**
- `getUsageAnalytics(days)` → `/v1/account/usage/analytics/?days=30`

**Data fields to use:**
```typescript
analytics.current_balance
analytics.usage_by_type  // Array with transaction_type, total, count
analytics.daily_usage    // Array with date, usage, purchases, net
analytics.total_usage
analytics.total_purchases
```

### PurchaseCreditsPage.tsx
**Should use:**
- `getCreditPackages()` → `/v1/billing/credit-packages/`
- `getPaymentMethods()` → `/v1/billing/payment-methods/`
- `purchaseCreditPackage(data)` → `POST /v1/billing/credit-packages/{id}/purchase/`

## 🔑 KEY POINTS

1. **Account Relationship:** All endpoints automatically filter by the logged-in user's account. The backend middleware sets `request.account` from the JWT token.

2. **Unified Response Format:** All endpoints return data in the format:
   ```json
   {
     "success": true,
     "data": { ... }
   }
   ```
   The `fetchAPI` function in `services/api.ts` automatically extracts the `data` field.

3. **Field Names:** Backend uses specific field names that MUST match in frontend:
   - `credits` (NOT `balance`)
   - `plan_credits_per_month` (NOT `monthly_credits`)
   - `credits_used_this_month` (NEW)
   - `credits_remaining` (NEW)

4. **No Fake Data:** Pages must load real data from these endpoints. NO placeholder data.

5. **Error Handling:** If endpoint returns 404, the backend route is not registered. Check `backend/igny8_core/urls.py` and restart backend container.

## 🛠️ FRONTEND FIX CHECKLIST

- [ ] Update `billing.api.ts` to use correct endpoints
- [ ] Update type interfaces to match backend response
- [ ] Fix AccountBillingPage to use `credits`, `plan_credits_per_month`, `credits_used_this_month`
- [ ] Fix UsageAnalyticsPage to use `usage_by_type`, `daily_usage` structure
- [ ] Fix PurchaseCreditsPage to call correct payment-methods endpoint
- [ ] Fix TeamManagementPage to handle optional `date_joined` field
- [ ] Fix AccountSettingsPage to load from `/v1/account/settings/`
- [ ] Remove all placeholder/fake data
- [ ] Test all pages with real backend data