Server exports
Bills
Server exports that write, pay, cancel and read bills in Hesap Defteri on behalf of an online player, and check for overdue bills.
These exports drive the Billing app (Hesap Defteri) from another resource. Each one acts as the player you pass in src: the same permissions, signal and distance rules apply as when that player uses the app. They are in apps/billing/server/exports.lua.
#Before you call them
- Allow your resource in
apps/billing/config_server.lua. An empty list allows no resource.
luaAPI = { AllowedResources = { ['my-saloon'] = true }, AllowDistanceOverride = false,
MaxRequests = 30, WindowSeconds = 10, MaxPayloadBytes = 16384 },
| Key | Default | What it does |
|---|---|---|
AllowedResources |
{} |
Resources that may call. Empty: none. |
AllowDistanceOverride |
false |
true lets CreateInvoice skip the distance check between the two players. |
MaxRequests |
30 |
Calls per player per calling resource in one window (1 to 120). |
WindowSeconds |
10 |
Length of that window (1 to 60). |
MaxPayloadBytes |
16384 |
Largest data table, as JSON (1024 to 65536). |
srcmust be an online player with a loaded character.- Every export returns a table with
ok. On failure it haserror(text for the player) and, when the export itself refused,code. - Amounts in
dataand in returned bills are dollars.GetInvoiceStatsreturns cents. - One call per player and calling resource runs at a time.
- Writing exports (
CreateInvoice,PayInvoice,CancelInvoice,CancelInvoices) need the player's signal for sending; reading exports need signal for receiving.CheckUnpaidInvoicesneeds none.
code |
When |
|---|---|
forbidden |
The calling resource is not on AllowedResources |
invalid_arguments |
src is not a player id or data is not a table |
character_unavailable |
The player has no loaded character |
busy |
A call for this player from your resource is still running |
rate_limited |
Too many calls; retryAfterMs says how long to wait |
invalid_payload |
data is too large or too deep |
disabled |
Config.Billing.Enabled is false |
signal_unavailable |
CreateInvoice without signal |
unavailable |
The billing action is not loaded |
context_changed |
The player's character, the integration or company access changed during the call. maybeCommitted = true on writing exports: check before you retry. |
storage_unavailable |
The database failed. maybeCommitted = true on writing exports. |
Writing exports take a nonce: a string of 16 to 64 letters, numbers or -, unique per operation. Sending the same nonce again returns the first result with duplicate = true instead of doing it twice. Keep the nonce when you retry after a timeout.
#CreateInvoice
Writes a bill from src to another online player. Also available as SendInvoice.
lua---@param src integer the player who writes the bill
---@param data table
---@return table result { ok, id?, duplicate?, error?, code? }
exports['fx-pocketbook']:CreateInvoice(src, data)
lualocal result = exports['fx-pocketbook']:CreateInvoice(source, {
target = customerId,
account = 'company',
amount = 12.50,
description = 'Room and bath, two nights',
nonce = ('saloon-%d-%d'):format(source, os.time()),
})
if result.ok then print('bill #' .. result.id) end
| Field | Default | What it does |
|---|---|---|
target |
Required. Server id of the player who receives the bill. Must be online and on the same framework. | |
account |
'personal' |
Who sends it: 'personal' or 'company' (the player's job company). Personal bills need Config.Billing.AllowPersonalSend; company bills need the job's send permission. |
recipientType |
'personal' |
Who receives it: 'personal' or 'company'. |
amount |
Required. Dollars, above 0, at most Config.Billing.MaxAmount, two decimals at most. |
|
description |
Required. Config.Billing.MinDescription to MaxDescription characters, with at least one letter. |
|
details |
'' |
Up to Config.Billing.MaxDetails characters. |
installments |
1 |
1 to Config.Billing.MaxInstallments. |
periodDays |
7 |
Days until it is due, 1 to Config.Billing.MaxPeriodDays. |
recurringDays |
0 |
Repeat the bill this many days after it is paid. 0 does not repeat. |
attachments |
List of https:// image links, at most Config.Billing.MaxAttachments, on a host in Config.Billing.ImageHosts when that list is set. |
|
nonce |
Required. See above. |
- The players must stand within
Config.Billing.NearbyDistancemetres whenConfig.Billing.EnforceNearbyis on, unlessAllowDistanceOverrideistrue. Config.Billing.AllowCreateUIdoes not apply to this export.- The same bill (sender, receiver, amount, description) inside
Config.Billing.DuplicateWindowSecondsis refused. - Both sides get a notification. The
Hooks.Senthook runs. See Server hooks.
#PayInvoice
Pays a bill that src received.
lua---@param src integer the player who pays
---@param data table { id, nonce, account?, amount?, full? }
---@return table result { ok, duplicate?, error?, code? }
exports['fx-pocketbook']:PayInvoice(src, data)
luaexports['fx-pocketbook']:PayInvoice(source, { id = 31, full = true, nonce = myNonce })
| Field | Default | What it does |
|---|---|---|
id |
Required. Bill id. | |
nonce |
Required. | |
account |
'personal' |
'personal' pays from the player's money (Config.MoneyAccount); 'company' pays from the job company's funds and needs that permission. |
amount |
Dollars to pay, at most what is left. | |
full |
true pays everything that is left. |
- With neither
amountnorfull, one installment is paid. - The bill must be open and not waiting for an administrator's review.
- The
Hooks.Paidhook runs.
#CancelInvoice
Cancels the rest of a bill that src sent.
lua---@param src integer
---@param data table { id, account?, revision? }
---@return table result { ok, duplicate?, error?, code? }
exports['fx-pocketbook']:CancelInvoice(src, data)
luaexports['fx-pocketbook']:CancelInvoice(source, { id = 31, account = 'company' })
- Only open or scheduled bills can be cancelled. A paid bill cannot.
revision: when given, the bill must still be at that revision (fromGetInvoice).- Cancelling an already cancelled bill returns
ok = true, duplicate = true. - The
Hooks.Cancelledhook runs.
#CancelInvoices
Cancels several bills that src sent.
lua---@param src integer
---@param data table { ids, revisions, account? }
---@return table result { ok, results, cancelled, failed }
exports['fx-pocketbook']:CancelInvoices(src, data)
luaexports['fx-pocketbook']:CancelInvoices(source, {
ids = { 31, 32 },
revisions = { ['31'] = 1, ['32'] = 2 },
account = 'company',
})
idsis a list of different bill ids, at mostConfig.Billing.MaxBulkCancel.revisionshas the current revision of every id, keyed by the id as a string.resultsis{ { id, ok, duplicate, error }, ... }.
#GetInvoices
Returns one page of the bills src received or sent.
lua---@param src integer
---@param data? table filters
---@return table result { ok, invoices, hasMore, canCancel }
exports['fx-pocketbook']:GetInvoices(src, data)
lualocal result = exports['fx-pocketbook']:GetInvoices(source, { folder = 'received', state = 'open' })
| Field | Default | What it does |
|---|---|---|
account |
'personal' |
'personal' or 'company' |
folder |
'received' |
'received' or 'sent' |
state |
'all' |
'all', 'open', 'paid', 'cancelled' or 'scheduled' |
page |
1 |
Page number; a page holds Config.Billing.PageSize bills |
search |
'' |
Text in the description or the sender or receiver name, up to 80 characters |
dateFrom, dateTo |
'YYYY-MM-DD' |
|
amountMin, amountMax |
Dollars |
Each bill in invoices: id, description, details, sender, recipient, issuer, amount, paid, penalty, remaining (dollars), state, revision, installments, periodDays, recurringDays, dueAt, createdAt.
#GetInvoice
Returns one bill of src with its payments and history.
lua---@param src integer
---@param data table { id, account? }
---@return table result { ok, invoice }
exports['fx-pocketbook']:GetInvoice(src, data)
lualocal result = exports['fx-pocketbook']:GetInvoice(source, { id = 31 })
invoice has the fields of a GetInvoices row plus attachments, payments (up to 100), events (up to 100), canPay, canCancel, review (a payment is waiting for review), senderAvatar and recipientAvatar. On a bill the player sent it also has commissionBps and issuedByMe.
#GetInvoiceStats
Returns totals of the bills of src.
lua---@param src integer
---@param data? table { account? }
---@return table result { ok, totals, months }
exports['fx-pocketbook']:GetInvoiceStats(src, data)
lualocal stats = exports['fx-pocketbook']:GetInvoiceStats(source, { account = 'company' })
totals:debt,receivable,paid,received,penalties(cents) andpending,late,sentPending,sentLate(counts).months: money received per month over the last 6 months,{ { month = 'YYYY-MM', total }, ... },totalin cents.
#CheckUnpaidInvoices
Returns whether src has personal bills that are still open after Config.Billing.Enforcement.GraceMinutes. Use it to block a service (a stable, a wagon) until the player pays.
lua---@param src integer
---@return table result { ok, blocked, count, amount, characterId, enforcementEnabled }
exports['fx-pocketbook']:CheckUnpaidInvoices(src)
lualocal check = exports['fx-pocketbook']:CheckUnpaidInvoices(source)
if check.ok and check.blocked then
return Notify(source, ('You owe $%.2f in %d bills.'):format(check.amount, check.count))
end
| Field | What it is |
|---|---|
blocked |
true when Config.Billing.Enforcement.Enabled is on and count is above 0 |
count |
Number of such bills |
amount |
What is left on them, in dollars |
characterId |
The player's character id |
enforcementEnabled |
The value of Config.Billing.Enforcement.Enabled |
- It works without signal, so losing the line cannot be used to skip the check.