All-Resources/[phone]/codem-phone/docs/apps/BILLING_API.md

# Billing API Documentation

This document describes the available exports for the codem-phone billing system.

---

### SendInvoice

Send an invoice from one player to another. Simple and easy to use.

```lua
local result = exports['codem-phone']:SendInvoice(source, targetSource, amount, reason, senderType)
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source | number | Yes | Server ID of the player sending the invoice |
| targetSource | number | Yes | Server ID of the player receiving the invoice |
| amount | number | Yes | Invoice amount |
| reason | string | Yes | Description/reason for the invoice |
| senderType | string | No | 'individual', 'business', or 'admin' (default: 'business') |

**Returns:**
```lua
{
    success = true/false,
    message = "Success or error message",
    invoice_id = 123 -- Only if success
}
```

**Example:**
```lua
-- Business sends invoice to player
local result = exports['codem-phone']:SendInvoice(source, targetPlayer, 500, "Vehicle Repair", "business")
if result.success then
    print("Invoice sent! ID: " .. result.invoice_id)
end
```

---

### SendInvoiceToIdentifier

Send an invoice to a player using their identifier/citizenid (works even if player is offline).

```lua
local result = exports['codem-phone']:SendInvoiceToIdentifier(identifier, amount, reason)
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| identifier | string | Yes | Player's citizenid/identifier |
| amount | number | Yes | Invoice amount |
| reason | string | Yes | Description/reason for the invoice |

**Returns:**
```lua
{
    success = true/false,
    message = "Success or error message",
    invoice_id = 123 -- Only if success
}
```

**Example:**
```lua
-- System sends tax invoice to player
local result = exports['codem-phone']:SendInvoiceToIdentifier("ABC12345", 1000, "Property Tax")
```

---

### GetPlayerUnpaidInvoices

Get all unpaid invoices for a player.

```lua
local result = exports['codem-phone']:GetPlayerUnpaidInvoices(source)
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source | number | Yes | Player's server ID |

**Returns:**
```lua
{
    success = true/false,
    invoices = {
        {
            id = 1,
            sender_id = "ABC123",
            items = { { name = "Service", price = 100, amount = 1 } },
            due_date = "2024-01-15 12:00:00",
            status = "unpaid", -- or "overdue"
            subtotal = 100,
            tax_percent = 10,
            tax_amount = 10,
            total = 110,
            penalty_applied = 0,
            sender_type = "business",
            sender_job = "mechanic"
        },
        -- ... more invoices
    },
    message = "Error message if failed"
}
```

**Example:**
```lua
local result = exports['codem-phone']:GetPlayerUnpaidInvoices(source)
if result.success then
    for _, invoice in ipairs(result.invoices) do
        print("Invoice #" .. invoice.id .. " - Total: $" .. invoice.total)
    end
end
```

---

### GetUnpaidInvoiceCount

Get count and total amount of unpaid invoices for a player.

```lua
local result = exports['codem-phone']:GetUnpaidInvoiceCount(source)
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source | number | Yes | Player's server ID |

**Returns:**
```lua
{
    success = true/false,
    count = 5,        -- Number of unpaid invoices
    total = 1500.00,  -- Total amount (including tax)
    message = "Error message if failed"
}
```

**Example:**
```lua
local result = exports['codem-phone']:GetUnpaidInvoiceCount(source)
if result.success and result.count > 0 then
    TriggerClientEvent('chat:addMessage', source, {
        args = { "System", "You have " .. result.count .. " unpaid invoices totaling $" .. result.total }
    })
end
```

---

### HasUnpaidInvoices

Quick check if player has any unpaid invoices.

```lua
local hasUnpaid = exports['codem-phone']:HasUnpaidInvoices(source)
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source | number | Yes | Player's server ID |

**Returns:** `boolean` - true if player has unpaid invoices

**Example:**
```lua
if exports['codem-phone']:HasUnpaidInvoices(source) then
    -- Block some action until invoices are paid
    TriggerClientEvent('QBCore:Notify', source, "Pay your invoices first!", "error")
    return
end
```

---

### PayInvoice

Pay a specific invoice for a player.

```lua
local result = exports['codem-phone']:PayInvoice(source, invoiceId)
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source | number | Yes | Player's server ID |
| invoiceId | number | Yes | ID of the invoice to pay |

**Returns:**
```lua
{
    success = true/false,
    message = "Success or error message"
}
```

**Example:**
```lua
local result = exports['codem-phone']:PayInvoice(source, 123)
if result.success then
    TriggerClientEvent('QBCore:Notify', source, "Invoice paid!", "success")
else
    TriggerClientEvent('QBCore:Notify', source, result.message, "error")
end
```

---

### CreateInvoice

Advanced invoice creation with multiple items.

```lua
local result = exports['codem-phone']:CreateInvoice(source, data)
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source | number | Yes | Server ID of the player sending the invoice |
| data | table | Yes | Invoice data (see below) |

**Data Table:**
```lua
{
    receiver_id = 2,              -- Target player's server ID
    items = {
        { name = "Oil Change", price = 50, amount = 1 },
        { name = "Brake Pads", price = 150, amount = 2 },
        { name = "Labor", price = 100, amount = 1 }
    },
    due_date = "2024-01-20 12:00:00",  -- Optional, defaults to 7 days
    sender_type = "business"            -- Optional: 'individual', 'business', 'admin'
}
```

**Returns:**
```lua
{
    success = true/false,
    message = "Success or error message",
    invoice_id = 123 -- Only if success
}
```

**Example:**
```lua
local result = exports['codem-phone']:CreateInvoice(source, {
    receiver_id = targetPlayer,
    items = {
        { name = "Engine Repair", price = 500, amount = 1 },
        { name = "Spare Parts", price = 200, amount = 3 }
    },
    sender_type = "business"
})
```

---

## Quick Examples

### Mechanic Job - Bill for Repairs
```lua
RegisterNetEvent('mechanic:billPlayer', function(targetId, services)
    local total = 0
    local items = {}

    for _, service in ipairs(services) do
        table.insert(items, {
            name = service.name,
            price = service.price,
            amount = 1
        })
        total = total + service.price
    end

    local result = exports['codem-phone']:CreateInvoice(source, {
        receiver_id = targetId,
        items = items,
        sender_type = "business"
    })

    if result.success then
        TriggerClientEvent('QBCore:Notify', source, "Invoice sent for $" .. total, "success")
    end
end)
```

### Hospital - Medical Bill
```lua
function BillPatient(source, amount)
    local result = exports['codem-phone']:SendInvoice(
        source,        -- Doctor sending
        source,        -- Patient receiving (same in this case, adjust as needed)
        amount,
        "Medical Treatment",
        "business"
    )
    return result.success
end
```

### Property System - Tax Bill
```lua
function SendPropertyTax(citizenid, propertyName, taxAmount)
    return exports['codem-phone']:SendInvoiceToIdentifier(
        citizenid,
        taxAmount,
        "Property Tax - " .. propertyName
    )
end
```

### Check Before Action
```lua
RegisterNetEvent('dealership:buyVehicle', function(vehicleModel)
    -- Block purchase if player has unpaid invoices
    if exports['codem-phone']:HasUnpaidInvoices(source) then
        TriggerClientEvent('QBCore:Notify', source, "Clear your invoices before buying!", "error")
        return
    end

    -- Continue with purchase...
end)
```

---

## Notes

- Tax is automatically calculated based on `BillingConfig.DefaultTaxPercent`
- Overdue invoices (past due date) have a 2x penalty applied automatically
- Business invoices add money to the job's account via `qb-management`
- Players receive phone notifications when they get new invoices