Server Exports - a-scripts* store

target is always a player server id or an identifier (ESX identifier / QBCore & Qbox citizenid), so most exports also work for offline players.

Moving from vms_cityhall? With Config.Compat.vmsCityhall = true the same calls work on exports['vms_cityhall']. See Compability.

General

openCityHall

Opens the PC for a player anywhere on the map (laptop item, MDT…). That PC session skips the City Hall location check until the player closes it.

---@param playerId number
---@return boolean success
exports['aps_cityhall']:openCityHall(playerId)

giveBill

Sends a bill to a player. Uses the same data format as vms_cityhall’s giveBill; its argument order (source, type, data, giveItem, cb) is accepted too.

---@param playerId number
---@param billType string: 'invoice' | 'ticket' | 'traffic-ticket' | 'receipt'
---@param billData table
---@param cb function|nil: called with billId (nil on failure)
exports['aps_cityhall']:giveBill(playerId, billType, billData, cb)

Explanation

Type	Amount from
`ticket`, `traffic-ticket`	`amount`
`invoice`	sum of `invoiceData` rows `{ qty, unitPrice, description }`
`receipt`	sum of `receiptData` rows `{ qty, unitPrice, item }`

Common fields

issuerName (string), job (string), society (string, optional), jobLabel (string, optional)
dateToPay (number): days until overdue, -1 = no due date
comments (string, optional)
taxFromInvoice / taxFromReceipt (number, optional): percent added on top
percentageForSociety (number, optional): share paid to the society, default Config.Society.defaultPercent

Traffic tickets

violation, locationOfViolation, vehicle = { plate, model }
penaltyPointsCount (number): adds penalty points
license + licenseSuspensionTime (seconds) or licenseRevocation = true

Example:

exports['aps_cityhall']:giveBill(targetSource, 'traffic-ticket', {
    issuerName          = 'Officer Smith',
    job                 = 'police',
    amount              = 750,
    dateToPay           = 7,
    violation           = 'Speeding (45 km/h over the limit)',
    locationOfViolation = 'Great Ocean Hwy',
    vehicle             = { plate = 'ABC 123', model = 'Sultan' },
    penaltyPointsCount  = 4,
}, function(billId)
    print('bill created', billId)
end)

Licenses

getLicenses

---@return table: list of license ids, e.g. { 'car', 'boat' }
local list = exports['aps_cityhall']:getLicenses(target)

hasLicense

Returns false while the license is suspended.

---@param license string: id from config/licenses.lua
---@return boolean
local has = exports['aps_cityhall']:hasLicense(target, 'car')

addLicense

---@return boolean: false if already owned
local added = exports['aps_cityhall']:addLicense(target, 'car')

removeLicense

Revokes a license (also in the synced framework license system).

---@return boolean
local removed = exports['aps_cityhall']:removeLicense(target, 'car')

suspendLicense

---@param seconds number: 0 = until reinstated
---@param reason string
exports['aps_cityhall']:suspendLicense(target, 'car', 7 * 86400, 'Reckless driving')

reinstateLicense

exports['aps_cityhall']:reinstateLicense(target, 'car')

isLicenseSuspended

Other scripts’ license names (drive_b, practical_boat…) are translated with Config.Compat.licenseAliases.

---@return boolean suspended, number|nil untilTime
local suspended, untilTime = exports['aps_cityhall']:isLicenseSuspended(target, 'car')

getSuspendedLicenses

---@return table: active suspensions keyed by license id
local list = exports['aps_cityhall']:getSuspendedLicenses(target)

getPenaltyPoints / addPenaltyPoints / removePenaltyPoints / resetPenaltyPoints

local points = exports['aps_cityhall']:getPenaltyPoints(target)
exports['aps_cityhall']:addPenaltyPoints(target, 4, 'Speeding')
exports['aps_cityhall']:removePenaltyPoints(target, 2, fromList)
exports['aps_cityhall']:resetPenaltyPoints(target)

Documents

hasDocument

---@param docType string: id from config/documents.lua
---@return boolean valid, string|nil expiresAt
local valid, expiresAt = exports['aps_cityhall']:hasDocument(target, 'id_card')

addDocument

Adds a document or extends a valid one.

---@param days number
---@return string newExpiry
local newExpiry = exports['aps_cityhall']:addDocument(target, 'id_card', 30)

issueDocument

Issues a document item for free (e.g. from a job script). days defaults to the longest validity option of the type.

---@param source number
---@param docType string
---@param days number|nil
---@return string|nil serial
local serial = exports['aps_cityhall']:issueDocument(source, 'id_card')

getDocumentBySerial

---@return table|nil: { serial, type, name, holder, status, issued, expires, identifier }
local doc = exports['aps_cityhall']:getDocumentBySerial('ID-482913')

isDocumentValid

---@return boolean
local valid = exports['aps_cityhall']:isDocumentValid('ID-482913')

getCitizenSSN

---@return string|nil: e.g. '123-45-6789'
local ssn = exports['aps_cityhall']:getCitizenSSN(source)

GenerateSSN

Returns a new unique SSN. Same signature as vms (GenerateSSN(dob, sex)), both arguments are ignored.

local ssn = exports['aps_cityhall']:GenerateSSN()

Insurance

getHealthInsurance / addHealthInsurance

Uses the document type Config.Compat.healthInsurance.

---@return boolean insured, number|nil expiresUnix
local insured, expiresUnix = exports['aps_cityhall']:getHealthInsurance(target)
exports['aps_cityhall']:addHealthInsurance(target, 7)   -- days

getVehicleInsurance / addVehicleInsurance

Accepts a plate or a VIN. Adding extends a running policy.

---@return boolean insured, string startDate, string expiryDate
local insured, startDate, expiryDate = exports['aps_cityhall']:getVehicleInsurance('ABC 123')
exports['aps_cityhall']:addVehicleInsurance(30, 'ABC 123')   -- days, plate

Taxes & Treasury

getTaxAmount

---@return number total, number tax, number percent
local total, tax, percent = exports['aps_cityhall']:getTaxAmount(250, 'products.food')

addPlayerTaxToPay

Adds a personal tax using a rate from Config.Taxes.

---@param identifier string
---@param fromAmount number
---@param taxPath string
---@param title string
exports['aps_cityhall']:addPlayerTaxToPay(identifier, 25000, 'gains.vehicleexcise', 'Vehicle sale')

addPlayerCustomTaxToPay

exports['aps_cityhall']:addPlayerCustomTaxToPay(identifier, price, 15, 'Property purchase tax')   -- percent

addPlayerFlatTax

exports['aps_cityhall']:addPlayerFlatTax(identifier, 500, 'Parking permit', category)

getPlayerTaxes

local taxes = exports['aps_cityhall']:getPlayerTaxes(target)

addCompanyTaxAmount / addCompanyCustomTaxAmount / addCompanyFlatTaxAmount

Business income is added to the current month’s tax account.

exports['aps_cityhall']:addCompanyTaxAmount('ltd1', 250, 'products.food')   -- rate from Config.Taxes
exports['aps_cityhall']:addCompanyCustomTaxAmount('taxi', total, 8)         -- percent
exports['aps_cityhall']:addCompanyFlatTaxAmount('mechanic', 500)            -- fixed tax

registerBusinessTaxAccount

exports['aps_cityhall']:registerBusinessTaxAccount('taxi', 'Downtown Cab Co')

Prefer Config.BusinessTaxes.accounts in taxes.lua for permanent accounts.

getJobTaxes

---@return table: { ['MM:YYYY'] = { amount, earned, total, status, … } }
local taxes = exports['aps_cityhall']:getJobTaxes('taxi')

getTreasuryMoney / addTreasuryMoney / removeTreasuryMoney

local balance = exports['aps_cityhall']:getTreasuryMoney()
exports['aps_cityhall']:addTreasuryMoney(5000)
exports['aps_cityhall']:removeTreasuryMoney(5000)

Businesses

business is a business id or name.

playerHasPermit

True when the player owns or works for an active business with a valid permit.

---@return boolean ok, string|nil businessName
local ok, businessName = exports['aps_cityhall']:playerHasPermit(source, 'alcohol')

Example usage

if not exports['aps_cityhall']:playerHasPermit(source, 'alcohol') then
    return TriggerClientEvent('ox_lib:notify', source, { type = 'error', description = 'You need an alcohol license.' })
end

hasBusinessPermit

---@return boolean valid, string|nil expiresAt
local valid, expiresAt = exports['aps_cityhall']:hasBusinessPermit('Downtown Cab Co', 'transport')

isBusinessEmployee

---@return boolean, string|nil role: 'owner' | 'employee'
local isStaff, role = exports['aps_cityhall']:isBusinessEmployee(source, 12)

isBusinessVehicle

---@return boolean, number|nil businessId, string|nil businessName
local isBiz, id, name = exports['aps_cityhall']:isBusinessVehicle(GetVehicleNumberPlateText(veh))

getBusinessVehicles

---@return table: { 'ABC 123', … }
local plates = exports['aps_cityhall']:getBusinessVehicles(12)

getPlayerBusinesses

---@return table: { { id, name, category, status, role }, … }
local list = exports['aps_cityhall']:getPlayerBusinesses(source)

getBusiness

---@return table|nil: { id, name, owner, ownerName, category, status, job, permits, employees }
local biz = exports['aps_cityhall']:getBusiness('Downtown Cab Co')

VIN, Paychecks & Job Center

GenerateVIN

---@return string: 17-character VIN
local vin = exports['aps_cityhall']:GenerateVIN()

See the VIN guide for existing vehicles.

updatePaychecks

Hands a salary to City Hall instead of the bank. See the Paychecks guide.

---@param action string|nil: nil = add, 'remove' = take away
---@return boolean
exports['aps_cityhall']:updatePaychecks(source, amount)
exports['aps_cityhall']:updatePaychecks(source, amount, 'remove')

getPaycheckBalance

local waiting = exports['aps_cityhall']:getPaycheckBalance(source)

setResumeAllowed

exports['aps_cityhall']:setResumeAllowed('police', false)   -- stop taking applications

getJobResumes

---@return table: applications, pending first
local list = exports['aps_cityhall']:getJobResumes('police')

​General

​openCityHall

​giveBill

​Common fields

​Traffic tickets

​Example:

​Licenses

​getLicenses

​hasLicense

​addLicense

​removeLicense

​suspendLicense

​reinstateLicense

​isLicenseSuspended

​getSuspendedLicenses

​getPenaltyPoints / addPenaltyPoints / removePenaltyPoints / resetPenaltyPoints

​Documents

​hasDocument

​addDocument

​issueDocument

​getDocumentBySerial

​isDocumentValid

​getCitizenSSN

​GenerateSSN

​Insurance

​getHealthInsurance / addHealthInsurance

​getVehicleInsurance / addVehicleInsurance

​Taxes & Treasury

​getTaxAmount

​addPlayerTaxToPay

​addPlayerCustomTaxToPay

​addPlayerFlatTax

​getPlayerTaxes

​addCompanyTaxAmount / addCompanyCustomTaxAmount / addCompanyFlatTaxAmount

​registerBusinessTaxAccount

​getJobTaxes

​getTreasuryMoney / addTreasuryMoney / removeTreasuryMoney

​Businesses

​playerHasPermit

​hasBusinessPermit

​isBusinessEmployee

​isBusinessVehicle

​getBusinessVehicles

​getPlayerBusinesses

​getBusiness

​VIN, Paychecks & Job Center

​GenerateVIN

​updatePaychecks

​getPaycheckBalance

​setResumeAllowed

​getJobResumes

General

openCityHall

giveBill

Common fields

Traffic tickets

Example:

Licenses

getLicenses

hasLicense

addLicense

removeLicense

suspendLicense

reinstateLicense

isLicenseSuspended

getSuspendedLicenses

getPenaltyPoints / addPenaltyPoints / removePenaltyPoints / resetPenaltyPoints

Documents

hasDocument

addDocument

issueDocument

getDocumentBySerial

isDocumentValid

getCitizenSSN

GenerateSSN

Insurance

getHealthInsurance / addHealthInsurance

getVehicleInsurance / addVehicleInsurance

Taxes & Treasury

getTaxAmount

addPlayerTaxToPay

addPlayerCustomTaxToPay

addPlayerFlatTax

getPlayerTaxes

addCompanyTaxAmount / addCompanyCustomTaxAmount / addCompanyFlatTaxAmount

registerBusinessTaxAccount

getJobTaxes

getTreasuryMoney / addTreasuryMoney / removeTreasuryMoney

Businesses

playerHasPermit

hasBusinessPermit

isBusinessEmployee

isBusinessVehicle

getBusinessVehicles

getPlayerBusinesses

getBusiness

VIN, Paychecks & Job Center

GenerateVIN

updatePaychecks

getPaycheckBalance

setResumeAllowed

getJobResumes