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).
  • src must be an online player with a loaded character.
  • Every export returns a table with ok. On failure it has error (text for the player) and, when the export itself refused, code.
  • Amounts in data and in returned bills are dollars. GetInvoiceStats returns 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. CheckUnpaidInvoices needs 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.NearbyDistance metres when Config.Billing.EnforceNearby is on, unless AllowDistanceOverride is true.
  • Config.Billing.AllowCreateUI does not apply to this export.
  • The same bill (sender, receiver, amount, description) inside Config.Billing.DuplicateWindowSeconds is refused.
  • Both sides get a notification. The Hooks.Sent hook 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 amount nor full, one installment is paid.
  • The bill must be open and not waiting for an administrator's review.
  • The Hooks.Paid hook 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 (from GetInvoice).
  • Cancelling an already cancelled bill returns ok = true, duplicate = true.
  • The Hooks.Cancelled hook 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',
})
  • ids is a list of different bill ids, at most Config.Billing.MaxBulkCancel.
  • revisions has the current revision of every id, keyed by the id as a string.
  • results is { { 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) and pending, late, sentPending, sentLate (counts).
  • months: money received per month over the last 6 months, { { month = 'YYYY-MM', total }, ... }, total in 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.