# Server Exports

### updatePaychecks

With this export you can add or remove money in the paychecks for a specific player, they will be collectible in the cityhall menu.

```lua
---@param {src: number}: player id
---@param {amount: number}: The monetary amount to be adjusted in the player's paycheck
---@param {action: string}: Specifies the action to take — either 'add' to increase or 'remove' to decrease the paycheck amount.
exports['vms_cityhall']:updatePaychecks(src, amount, action)
```

***

### getHealthInsurance

Get information about the player's health insurance.

```lua
---@param {src: number}: player id

---@return {isInsured: boolean}
---@return {timestamp: number}: time until which it is insured 
local isInsured, timestamp = exports['vms_cityhall']:getHealthInsurance(src)
```

***

### addHealthInsurance

Add health insurance time.

```lua
---@param {src: number}: player id
---@param {daysCount: number}
exports['vms_cityhall']:addHealthInsurance(src, daysCount)
```

***

### getVehicleInsurance

Function checks the insurance status of a vehicle using its Vehicle Identification Number (VIN) or license plate. It returns a boolean indicating whether the vehicle is insured, and if insured, it also provides the start and expiry dates of the insurance policy.

```lua
---@param {value: string}: VIN Number or License Plate

---@return {insured: boolean, startDate: string | nil, expiryDate: string | nil}
local insured, startDate, expiryDate = exports['vms_cityhall']:getVehicleInsurance(value)
```

<details>

<summary>Example usage</summary>

### With VIN

```lua
local vin = 'BARHE4U85VB5095KR'

local insured, startDate, expiryDate = exports['vms_cityhall']:getVehicleInsurance(vin)
```

### With License Plate

```lua
local plate = 'IGW 0293'

local insured, startDate, expiryDate = exports['vms_cityhall']:getVehicleInsurance(plate)
```

</details>

***

### addVehicleInsurance

Allows you to assign a vehicle's insurance policy based on its VIN number or license plate for a specific number of days.

```lua
---@param {days: number}: 
---@param {value: string}: VIN Number or License Plate

---@return {insured: boolean, startDate: string | nil, expiryDate: string | nil}
exports['vms_cityhall']:addVehicleInsurance(days, value)
```

<details>

<summary>Example usage</summary>

### With VIN

```lua
local days = 10
local vin = 'BARHE4U85VB5095KR'
exports['vms_cityhall']:addVehicleInsurance(days, vin)
```

### With License Plate

```lua
local days = 10
local plate = 'IGW 0293'
exports['vms_cityhall']:addVehicleInsurance(days, plate)
```

</details>

***

### giveBill

Using the above export, you can assign a fine or invoice to a player, without the required issuance by another player or acceptance by the receiving player, an example application, for example, for speed cameras.

```lua
---@param {src: number}: player id
---@param {type: string}: 'ticket' / 'traffic-ticket' / 'invoice'
---@param {data: table}
---@param {giveItem: boolean}: do you want the player to receive an inventory mandate item?

---@return {fineId: number}: id of the document assigned in the database
exports['vms_cityhall']:giveBill(src, type, data, giveItem, function(fineId)

end)
```

<details>

<summary>Explanation</summary>

Clarification of the values required for the `data` parameter for **invoice**:

* data: `table`
  * society?: `string`
  * job?: `string`
  * jobLabel?: `string`
  * issuerName?: `string`
  * dateToPay?: `number`
  * percentageForSociety?: `number`
  * invoiceData: `table`
  * taxFromInvoice?: `number`&#x20;

Clarification of the values required for the `data` parameter for **ticket**:

* data: `table`
  * society?: `string`
  * job?: `string`
  * jobLabel?: `string`
  * issuerName?: `string`
  * dateToPay?: `number`
  * amount: `number`
  * percentageForSociety?: `number`
  * locationOfViolation?: `string`
  * violation?: `string`
  * comments?: `string`

Clarification of the values required for the `data` parameter for **traffic-ticket**:

* data: `table`
  * society?: `string`
  * job?: `string`
  * jobLabel?: `string`
  * issuerName?: `string`
  * dateToPay?: `number`
  * amount: `number`
  * percentageForSociety?: `number`
  * locationOfViolation?: `string`
  * violation?: `string`
  * comments?: `string`
  * vehicle?: `table`
    * plate?: `string`
    * make?: `string`
    * model?: `string`
    * vin?: `string`
  * license?: `string`
  * licenseRevocation?: `boolean`
  * licenseSuspensionTime?: `number`
  * penaltyPointsCount?: `number`

Clarification of the values required for the `data` parameter for **receipt**:

* data: `table`
  * society?: `string`
  * job?: `string`
  * jobLabel?: `string`
  * issuerName?: `string`
  * dateToPay?: `number`
  * percentageForSociety?: `number`
  * receiptData: `table`
  * taxFromReceipt?: `number`

### Example of Invoice

```lua
local src = 1
local giveItem = true

--[[
    The amount to be paid will be based on the data entered in invoiceData,
    if you enter as below, the final player to pay will be 45,000$,
    if we add tax, it will be 47,250$.
]]

exports['vms_cityhall']:giveBill(src, 'invoice', {
    society = 'society_ambulance',
    job = 'ambulance',
    jobLabel = 'EMS',
    issuerName = 'Medical assistance',
    dateToPay = -1, -- Instant Payment
    percentageForSociety = 20,
    invoiceData = {
        {qty = 1, unitPrice = 3000, description = "first row"},
        {qty = 5, unitPrice = 8000, description = "second row"},
        {qty = 2, unitPrice = 1000, description = "third row"},
    },
    taxFromInvoice = 5.0, 
}, giveItem, function(fineId)
    print('Player ' .. src .. ' received invoice #' .. fineId)
end)
```

### Example of Ticket

```lua
local src = 1
local giveItem = true

exports['vms_cityhall']:giveBill(src, 'ticket', {
    society = 'society_police',
    job = 'police',
    jobLabel = 'LSPD',
    issuerName = 'NPC Officer',
    dateToPay = 5, -- 5 Days
    amount = 2000,
    percentageForSociety = 20,
    locationOfViolation = "Mission Row",
    violation = "Test ticket",
    comments = "",
}, giveItem, function(fineId)
    print('Player ' .. src .. ' received ticket #' .. fineId)
end)
```

### Example of Traffic Ticket

```lua
local src = 1
local giveItem = true

local myPed = GetPlayerPed(src)
local myVehicle = GetVehiclePedIsIn(myPed, false)

exports['vms_cityhall']:giveBill(src, 'traffic-ticket', {
    society = 'society_police',
    job = 'police',
    jobLabel = 'LSPD',
    issuerName = 'Speed Camera',
    dateToPay = -1, -- Instant Payment
    amount = 5000,
    percentageForSociety = 20,
    locationOfViolation = "Mission Row",
    violation = "Exceeding the speed limit",
    comments = "The speed camera recorded the speed 143/50 MPH",
    vehicle = {
        plate = GetVehicleNumberPlateText(myVehicle),
        make = "-",
        model = "-",
        vin = "-",
    },
    license = 'drive_b',
    licenseRevocation = false,
    licenseSuspensionTime = nil, -- days or nil
    penaltyPointsCount = 2,
}, giveItem, function(fineId)
    print('Player ' .. src .. ' received traffic ticket #' .. fineId)
end)
```

### Example of Receipt

```lua
local src = 1
local giveItem = true

exports['vms_cityhall']:giveBill(src, 'receipt', {
    society = 'society_mechanic',
    job = 'mechanic',
    jobLabel = 'MECHANIC',
    issuerName = 'Character Name',
    dateToPay = -1, -- Instant Payment
    percentageForSociety = 20,
    receiptData = {
        {qty = 1, unitPrice = 2000, item = "Cleaning"},
        {qty = 3, unitPrice = 500, item = "Fix Kit"},
    },
    taxFromReceipt = 5.0,
}, giveItem, function(fineId)
    print('Player ' .. src .. ' received receipt #' .. fineId)
    -- xPlayer.addInventoryItem('fixkit', 3)
end)
```

</details>

***

### suspenseLicense

Cancellation of the license and its suspension for a specified period of time, using, for example, vms\_driveschoolv2, then the player will not be able to take the exam until the lockout ends.

```lua
---@param {src: number}: player id
---@param {licenseName: string}: license name like 'drive_b'
---@param {time: number}: The value given in seconds - for example, 7 * 24 * 60 * 60, then it will be 7 days of blocking the license
exports['vms_cityhall']:suspenseLicense(src, licenseName, time)
```

***

### reinstateLicense

Restores the ability to take exams\
\&#xNAN;**\* It does not return previously revoked licenses to the player.**

```lua
---@param {src: number}: player id
---@param {licenseName: string}: license name like 'drive_b'
exports['vms_cityhall']:reinstateLicense(src, licenseName)
```

***

### isLicenseSuspended

Checking the license information, this will return information on whether the license is suspended and if it is, it will also return the end date of the suspension.

```lua
---@param {src: number}: player id
---@param {licenseName: string}: license name like 'drive_b'

---@return {isSuspended: boolean}: true or false, you can add to your driving school the ability to take the exam
---@return {suspendedTime: number or nil}: timestamp of the date when the license suspension penalty will end
local isSuspended, suspendedTime = exports['vms_cityhall']:isLicenseSuspended(src, licenseName)
```

***

### getPenaltyPoints

Get information about a player's penalty points.

```lua
---@param {src: number}: player id

---@return {penaltyPoints: number}: number of penalty points
local penaltyPoints = exports['vms_cityhall']:getPenaltyPoints(src)
```

***

### addPenaltyPoints

Add penalty points to the player.

```lua
---@param {src: number}: player id
---@param {count: number}: number of penalty points
exports['vms_cityhall']:addPenaltyPoints(src, count)
```

***

### removePenaltyPoints

Remove penalty points for the player.

```lua
---@param {src: number}: player id
---@param {count: number}: number of penalty points
---@param {removeFromList: boolean}
exports['vms_cityhall']:removePenaltyPoints(src, count, removeFromList)
```

<details>

<summary>Explanation</summary>

#### Explanation of removeFromList

The script automatically removes after the time specified in `Config.RemovePenaltyPointsAfter` penalty points from the time they were given to the citizen, you set this parameter to true, then the points will be subtracted from the list which will result in the correct removal of penalty points automatically in the future.

</details>

***

### resetPenaltyPoints

Resets the penalty points and clears the player's list of penalty points.

```lua
---@param {src: number}: player id
exports['vms_cityhall']:resetPenaltyPoints(src)
```

***

### setResumeAllowed

Allows or prevents citizens from sending resumes to a specific job in the Job Center section of the city hall menu.

```lua
---@param {jobName: string}: job name like 'mechanic'
---@param {isAllowed: boolean}
exports['vms_cityhall']:setResumeAllowed(jobName, isAllowed)
```

***

### getJobResumes

Returns all active resumes sent by citizens for a specific job.

```lua
---@param {jobName: string}: job name like 'mechanic'

---@return {resumes: table}:
local resumes = exports['vms_cityhall']:getJobResumes(jobName)
```

<details>

<summary>Explanation</summary>

Return value is a table that has information about all received active resumes to the company, below is an explanation of the parameters and an example.

#### Parameters:

* sender: `string`
* sender\_name: `string`
* job: `string`
* date: `number`
* informations: `table`
  * phone\_number: `string`
  * photo: `string`
  * about\_me: `string`
  * work\_experience: `string`
  * skills: `table`
  * interests: `table`

***

#### Example:

```lua
{
    ['char1:11000000a0aa00a'] = {
        sender = "char1:11000000a0aa00a",
        sender_name "Character Name",
        job = "mechanic",
        date = 1729737106,
        informations = {
            phone_number = "123-5678",
            photo = "data:image/png;base64,iVBO...",
            about_me = "My example of about me!",
            work_experience = "My example of work experience!",
            skills = {"👥 Teamwork","✊ Leadership"},
            interests = {"📸 Photography","🎮 Video games"},
        }
    },
}
```

</details>

***

### getJobTaxes

Returns all the company's taxes, both paid and not yet paid

```lua
---@param {jobName: string}: job name like 'mechanic'

---@return {taxes: table}:
local taxes = exports['vms_cityhall']:getJobTaxes(jobName)
```

<details>

<summary>Explanation</summary>

Return value is a table that has information about all taxes from the company, below is an explanation of the parameters and an example.

#### Parameters:

* period: `string`
* job: `string`
* job\_label: `string`
* is\_paid: `boolean`
* paid\_date: `number`
* paid\_amount: `number`
* amount: `number`
* delayed\_amount: `number`
* late\_fee\_applied: `number`

***

#### Example:

```lua
{
    ['08:2024'] = {
        period = "08:2024",
        job = "mechanic",
        job_label = "BennyS",
        is_paid = true,
        paid_date = 1729097877
        paid_amount = 13740,
        amount = 12400,
        delayed_amount = 1340,
        late_fee_applied = 1,
    },
}
```

</details>

***

### getTaxAmount

Calculates tax information on the specified amount.

```lua
---@param {amount: number}: 
---@param {tax: number or string}: 

---@return {totalAmount: number}
---@return {taxAmount: number}
---@return {taxPercentage: number}
local totalAmount, taxAmount, taxPercentage = exports['vms_cityhall']:getTaxAmount(amount, tax)
```

<details>

<summary>Explanation</summary>

#### Example of custom tax:

```lua
local amount = 50000
local tax = 33 -- custom value given as number

local totalAmount, taxAmount, taxPercentage = exports['vms_cityhall']:getTaxAmount(amount, tax)

---@return totalAmount: 66500.0   |  (amount + tax)
---@return taxAmount: 16500.0     |  (tax value alone)
---@return taxPercentage: 33      |  (tax percentage)
```

***

#### Example of tax from Config.Taxes:

```lua
local amount = 50000
local tax = 'products.food' -- By default it's 33 %

local totalAmount, taxAmount, taxPercentage = exports['vms_cityhall']:getTaxAmount(amount, tax)

---@return totalAmount: 66500.0   |  (amount + tax)
---@return taxAmount: 16500.0     |  (tax value alone)
---@return taxPercentage: 33      |  (tax percentage)
```

</details>

***

### addPlayerTaxToPay

Add a private player tax to be paid on the specified amount using the path from `Config.Taxes`.

```lua
---@param {identifier: number or string}: player server id or player identifier
---@param {fromAmount: number}: the amount on which tax is to be charged
---@param {taxPath: string}: example: 'products.food'
---@param {title: string}: reason for imposing the tax
exports['vms_cityhall']:addPlayerTaxToPay(identifier, fromAmount, taxPath, title)
```

***

### addPlayerCustomTaxToPay

Add a private player custom tax to be paid on the specified amount.

```lua
---@param {identifier: number or string}: player server id or player identifier
---@param {fromAmount: number}: the amount on which tax is to be charged
---@param {percentage: number}: percentage to be charged on the amount
---@param {title: string}: reason for imposing the tax
exports['vms_cityhall']:addPlayerCustomTaxToPay(identifier, fromAmount, percentage, title)
```

***

### addCompanyTaxAmount

Add the company's tax to be paid on the specified amount using the path from `Config.Taxes`.

```lua
---@param {job: string}: job name like 'mechanic'
---@param {fromAmount: number}: the amount on which tax is to be charged
---@param {taxPath: string}: example: 'products.food'
exports['vms_cityhall']:addCompanyTaxAmount(job, fromAmount, taxPath)
```

***

### addCompanyCustomTaxAmount

Add custom company tax to be paid on the amount specified.

```lua
---@param {job: string}: job name like 'mechanic'
---@param {fromAmount: number}: the amount on which tax is to be charged
---@param {percentage: number}: percentage to be charged on the amount
exports['vms_cityhall']:addCompanyCustomTaxAmount(job, fromAmount, percentage)
```

***

### addCompanyFlatTaxAmount

Add to the company the amount of tax to be paid.

```lua
---@param {job: string}: job name like 'mechanic'
---@param {amount: number}: static number that will be added to the charge in company taxes
exports['vms_cityhall']:addCompanyFlatTaxAmount(job, amount)
```

***

### registerBusinessTaxAccount

Register the company as a tax business.

{% hint style="warning" %}
You don't have to use this export, you can enter the company data in the `Config.TaxBusinessAccounts` which is located in **vms\_cityhall/config/config.taxes.lua**
{% endhint %}

```lua
---@param {jobName: string}: job name like 'mechanic'
---@param {jobLabel: string}: job label like 'BennyS'

---@return {period: string}: 'MM:YYYY'
exports['vms_cityhall']:registerBusinessTaxAccount(jobName, jobLabel, function(period)

end)
```

***

### getCompanyMoney

Get information about the current balance of cityhall.

```lua
---@return {amount: number}
local amount = exports['vms_cityhall']:getCompanyMoney()
```

***

### addCompanyMoney

Add money to cityhall balance.

```lua
---@param {amount: number}
---@param {addToTotalEarned: boolean}: are they to be added to the Total Earned section
exports['vms_cityhall']:addCompanyMoney(amount, addToTotalEarned)
```

***

### removeCompanyMoney

Take money from the balance of cityhall.

```lua
---@param {amount: number}
exports['vms_cityhall']:removeCompanyMoney(amount)
```

***

### GenerateSSN

{% hint style="info" %}
In the section [generate-ssn-for-players](https://docs.vames-store.com/assets/vms_cityhall/guides/generate-ssn-for-players "mention") there is a tutorial on how to generate  SSNs for current players who do not have one.

Read also section [add-ssn-generation](https://docs.vames-store.com/assets/vms_cityhall/guides/add-ssn-generation "mention") to implement in your framework the automatic generation of the SSN for players.
{% endhint %}

```lua
---@param {dateOfBirth: string}
---@param {gender: string or number} 
local ssn = exports['vms_cityhall']:GenerateSSN(dateOfBirth, gender)
```

***

### GenerateVIN

{% hint style="info" %}
In the section [generate-vin-for-vehicles](https://docs.vames-store.com/assets/vms_cityhall/guides/generate-vin-for-vehicles "mention") there is a tutorial on how to generate VINs for current vehicles who do not have one.

Read also section [add-vin-generation](https://docs.vames-store.com/assets/vms_cityhall/guides/add-vin-generation "mention") to implement in your vehicleshop the automatic generation of the VIN.
{% endhint %}

```lua
local vin = exports['vms_cityhall']:GenerateVIN()
```