0
# Invoice Management
1

2
Invoice creation, management, and billing operations for the Django CRM system. Provides complete invoice lifecycle management from creation through payment with email notifications, PDF generation, and status tracking.
3

4
**Important Note**: The invoice API endpoints are fully implemented with models, serializers, and API views, but are not currently routed in the main application URLs. To enable invoice API functionality, add the invoice URLs to the main URL routing configuration.
5

6
## Capabilities
7

8
### Invoice Listing and Search
9

10
List invoices with comprehensive filtering and search capabilities.
11

12
```python { .api }
13
def list_invoices(status: str = None, name: str = None,
14
                 assigned_to: str = None, limit: int = 10, offset: int = 0) -> dict:
15
    """
16
    List invoices with filtering and search.
17

18
    Args:
19
        status (str, optional): Filter by invoice status ('Draft', 'Sent', 'Paid', 'Pending', 'Cancelled')
20
        name (str, optional): Filter by customer name (partial match)
21
        assigned_to (str, optional): Filter by assigned user UUID
22
        limit (int): Number of results per page (default: 10)
23
        offset (int): Number of results to skip (default: 0)
24

25
    Returns:
26
        dict: Paginated invoices with metadata
27

28
    Headers Required:
29
        Authorization: Bearer <access_token>
30
        organization-id: <org_uuid>
31

32
    Example:
33
        GET /api/invoices/?status=Draft&name=acme&limit=5
34

35
        Response:
36
        {
37
            "count": 25,
38
            "next": "/api/invoices/?limit=5&offset=5",
39
            "previous": null,
40
            "results": [
41
                {
42
                    "id": "invoice-uuid",
43
                    "invoice_title": "Monthly Service",
44
                    "invoice_number": "INV-001",
45
                    "status": "Draft",
46
                    "due_date": "2024-01-15",
47
                    "name": "ACME Corporation",
48
                    "email": "billing@acme.com",
49
                    "phone": "+1234567890",
50
                    "quantity": 40,
51
                    "rate": "150.00",
52
                    "total_amount": "6000.00",
53
                    "currency": "USD",
54
                    "created_on": "2024-01-01T10:00:00Z",
55
                    "assigned_to": ["user-uuid"],
56
                    "teams": ["team-uuid"]
57
                }
58
            ]
59
        }
60
    """
61
```
62

63
### Invoice Creation
64

65
Create new invoices with billing details and customer information.
66

67
```python { .api }
68
def create_invoice(invoice_data: dict) -> dict:
69
    """
70
    Create a new invoice.
71

72
    Args:
73
        invoice_data (dict): Invoice information including:
74
            - invoice_title: str
75
            - invoice_number: str (optional, auto-generated if not provided)
76
            - name: str (customer name)
77
            - email: str (customer email)
78
            - phone: str (optional)
79
            - quantity: int (hours or units)
80
            - rate: decimal (rate per unit)
81
            - currency: str (3-letter currency code)
82
            - due_date: str (YYYY-MM-DD format)
83
            - status: str (default: 'Draft')
84
            - assigned_to: list[str] (user UUIDs)
85
            - teams: list[str] (team UUIDs)
86
            - from_address: dict (billing address)
87
            - to_address: dict (customer address)
88

89
    Returns:
90
        dict: Created invoice details
91

92
    Headers Required:
93
        Authorization: Bearer <access_token>
94
        organization-id: <org_uuid>
95

96
    Example:
97
        POST /api/invoices/
98
        {
99
            "invoice_title": "Web Development Services",
100
            "name": "Tech Solutions Inc",
101
            "email": "billing@techsolutions.com",
102
            "quantity": 80,
103
            "rate": "125.00",
104
            "currency": "USD",
105
            "due_date": "2024-02-15",
106
            "assigned_to": ["user-uuid"],
107
            "teams": ["dev-team-uuid"]
108
        }
109
    """
110
```
111

112
### Invoice Details
113

114
Retrieve detailed information about a specific invoice.
115

116
```python { .api }
117
def get_invoice_details(invoice_id: str) -> dict:
118
    """
119
    Get detailed invoice information.
120

121
    Args:
122
        invoice_id (str): Invoice UUID
123

124
    Returns:
125
        dict: Complete invoice details including addresses, history, and assignments
126

127
    Headers Required:
128
        Authorization: Bearer <access_token>
129
        organization-id: <org_uuid>
130

131
    Example:
132
        GET /api/invoices/invoice-uuid/
133

134
        Response includes full invoice data, billing addresses, assigned users,
135
        teams, and invoice history
136
    """
137
```
138

139
### Invoice Updates
140

141
Update existing invoice information and details.
142

143
```python { .api }
144
def update_invoice(invoice_id: str, update_data: dict) -> dict:
145
    """
146
    Update invoice information.
147

148
    Args:
149
        invoice_id (str): Invoice UUID
150
        update_data (dict): Fields to update (same structure as create)
151

152
    Returns:
153
        dict: Updated invoice details
154

155
    Headers Required:
156
        Authorization: Bearer <access_token>
157
        organization-id: <org_uuid>
158

159
    Example:
160
        PUT /api/invoices/invoice-uuid/
161
        {
162
            "status": "Sent",
163
            "total_amount": "6500.00"
164
        }
165
    """
166
```
167

168
### Invoice Deletion
169

170
Remove invoices from the system.
171

172
```python { .api }
173
def delete_invoice(invoice_id: str) -> dict:
174
    """
175
    Delete an invoice.
176

177
    Args:
178
        invoice_id (str): Invoice UUID
179

180
    Returns:
181
        dict: Deletion confirmation
182

183
    Headers Required:
184
        Authorization: Bearer <access_token>
185
        organization-id: <org_uuid>
186

187
    Example:
188
        DELETE /api/invoices/invoice-uuid/
189
    """
190
```
191

192
### Email Operations
193

194
Send invoices via email with PDF attachments.
195

196
```python { .api }
197
def send_invoice_email(invoice_id: str, email_data: dict) -> dict:
198
    """
199
    Send invoice by email.
200

201
    Args:
202
        invoice_id (str): Invoice UUID
203
        email_data (dict): Email configuration including recipients and message
204

205
    Returns:
206
        dict: Email sending confirmation
207

208
    Headers Required:
209
        Authorization: Bearer <access_token>
210
        organization-id: <org_uuid>
211

212
    Example:
213
        POST /api/invoices/invoice-uuid/send-mail/
214
        {
215
            "recipients": ["customer@example.com"],
216
            "subject": "Invoice INV-001",
217
            "message": "Please find attached invoice"
218
        }
219
    """
220
```
221

222
### PDF Generation
223

224
Generate and download invoice PDFs.
225

226
```python { .api }
227
def download_invoice_pdf(invoice_id: str) -> bytes:
228
    """
229
    Generate and download invoice PDF.
230

231
    Args:
232
        invoice_id (str): Invoice UUID
233

234
    Returns:
235
        bytes: PDF file content
236

237
    Headers Required:
238
        Authorization: Bearer <access_token>
239
        organization-id: <org_uuid>
240

241
    Example:
242
        POST /api/invoices/invoice-uuid/download/
243

244
        Response: PDF file download
245
    """
246
```
247

248
### Status Management
249

250
Update invoice status through the billing lifecycle.
251

252
```python { .api }
253
def update_invoice_status(invoice_id: str, status_data: dict) -> dict:
254
    """
255
    Update invoice status.
256

257
    Args:
258
        invoice_id (str): Invoice UUID
259
        status_data (dict): Status information
260
            - status: str ('Draft', 'Sent', 'Paid', 'Pending', 'Cancelled')
261

262
    Returns:
263
        dict: Updated invoice with new status
264

265
    Headers Required:
266
        Authorization: Bearer <access_token>
267
        organization-id: <org_uuid>
268

269
    Example:
270
        POST /api/invoices/invoice-uuid/status/
271
        {
272
            "status": "Paid"
273
        }
274
    """
275
```
276

277
### Comment Management
278

279
Add comments and notes to invoices for collaboration and tracking.
280

281
```python { .api }
282
def add_invoice_comment(invoice_id: str, comment_data: dict) -> dict:
283
    """
284
    Add a comment to an invoice.
285

286
    Args:
287
        invoice_id (str): Invoice UUID
288
        comment_data (dict): Comment information
289
            - comment: str (comment text)
290

291
    Returns:
292
        dict: Created comment details
293

294
    Headers Required:
295
        Authorization: Bearer <access_token>
296
        organization-id: <org_uuid>
297

298
    Example:
299
        POST /api/invoices/comment/invoice-uuid/
300
        {
301
            "comment": "Customer requested payment extension"
302
        }
303
    """
304
```
305

306
### Attachment Management
307

308
Upload and manage files attached to invoices.
309

310
```python { .api }
311
def add_invoice_attachment(invoice_id: str, file_data: dict) -> dict:
312
    """
313
    Add a file attachment to an invoice.
314

315
    Args:
316
        invoice_id (str): Invoice UUID
317
        file_data (dict): File upload data
318
            - attachment: file (uploaded file)
319

320
    Returns:
321
        dict: Created attachment details
322

323
    Headers Required:
324
        Authorization: Bearer <access_token>
325
        organization-id: <org_uuid>
326
        Content-Type: multipart/form-data
327

328
    Example:
329
        POST /api/invoices/attachment/invoice-uuid/
330
        (multipart form data with file upload)
331
    """
332
```
333

334
## Data Types
335

336
```python { .api }
337
class Invoice:
338
    """Invoice model for billing operations"""
339
    id: str  # UUID
340
    invoice_title: str
341
    invoice_number: str
342
    status: str  # 'Draft', 'Sent', 'Paid', 'Pending', 'Cancelled'
343
    due_date: str  # YYYY-MM-DD format
344
    name: str  # Customer name
345
    email: str  # Customer email
346
    phone: str  # Customer phone (optional)
347
    quantity: int  # Hours or units
348
    rate: str  # Decimal rate per unit
349
    total_amount: str  # Calculated total (rate * quantity)
350
    tax: str  # Tax amount (optional)
351
    currency: str  # 3-letter currency code
352
    created_on: str  # ISO datetime
353
    created_by: User
354
    org: Organization
355
    assigned_to: list[User]  # Assigned users
356
    teams: list[Team]  # Associated teams
357
    from_address: Address  # Billing address
358
    to_address: Address  # Customer address
359

360
class InvoiceHistory:
361
    """Invoice status change tracking"""
362
    id: str  # UUID
363
    invoice: str  # Invoice UUID
364
    updated_by: User
365
    updated_on: str  # ISO datetime
366
    status_changed_from: str  # Previous status
367
    status_changed_to: str  # New status
368
```
369

370
## Usage Examples
371

372
### Complete Invoice Workflow
373

374
```python
375
import requests
376

377
headers = {
378
    'Authorization': 'Bearer your-access-token',
379
    'organization-id': 'your-org-uuid',
380
    'Content-Type': 'application/json'
381
}
382

383
# Create a new invoice
384
invoice_data = {
385
    "invoice_title": "Q1 Consulting Services",
386
    "name": "Global Tech Corp",
387
    "email": "finance@globaltech.com",
388
    "quantity": 120,
389
    "rate": "200.00",
390
    "currency": "USD",
391
    "due_date": "2024-02-28",
392
    "assigned_to": ["user-uuid"]
393
}
394

395
response = requests.post('http://your-crm.com/api/invoices/',
396
                        json=invoice_data, headers=headers)
397
invoice = response.json()
398
invoice_id = invoice['id']
399

400
# Update invoice status to sent
401
status_update = {"status": "Sent"}
402
requests.post(f'http://your-crm.com/api/invoices/{invoice_id}/status/',
403
              json=status_update, headers=headers)
404

405
# Send invoice via email
406
email_data = {
407
    "recipients": ["finance@globaltech.com"],
408
    "subject": f"Invoice {invoice['invoice_number']}",
409
    "message": "Please find your invoice attached. Payment due within 30 days."
410
}
411
requests.post(f'http://your-crm.com/api/invoices/{invoice_id}/send-mail/',
412
              json=email_data, headers=headers)
413

414
# Add payment tracking comment
415
comment_data = {"comment": "Payment reminder sent via email"}
416
requests.post(f'http://your-crm.com/api/invoices/comment/{invoice_id}/',
417
              json=comment_data, headers=headers)
418
```
419

420
## Error Handling
421

422
Common error responses include:
423

424
- `400 Bad Request`: Invalid invoice data or missing required fields
425
- `401 Unauthorized`: Missing or invalid authentication token
426
- `403 Forbidden`: Insufficient permissions for invoice operations
427
- `404 Not Found`: Invoice not found or not accessible
428
- `422 Unprocessable Entity`: Validation errors in invoice data
429

430
All error responses follow the standard format with field-specific validation details.