FoyerDevelopers

Generated · Live registry

invoices tools

27 tools in this domain, generated from the running registry.

All tool domains

invoices.anStayNachliefern

writesconfirm

Deliver ONE stay that the invoicing system (stay/staydb) has never received — new reservations only. Refused if a confirmed delivery exists, if the staydb already has the reservation (checked live), if the stay is incomplete, or before departure (on departure day only once checked out), and for cancelled stays unless auchStorniert. One attempt, 20 s hard timeout; refused while another send of the same stay runs. Pass nurPruefen: true for a dry run. Writes channel_sync_log and the stay's audit trail, then reads back from the staydb. Requires confirmation.

Input parameters

FieldTypeRequiredNotes
stayIdstringyes
nurPruefenbooleanno
auchStorniertbooleanno

Output fields

FieldTypeRequiredNotes
artenumyesOne of: pruefung_bestanden, abgelehnt, zugestellt, zugestellt_ohne_vermerk, ausgestellt, nicht_gefunden, existiert_bereits, fehlgeschlagen
textstringyes
grundstringno
httpStatusinteger · nullableno

invoices.autopilotStand

read-only

What the invoice autopilot decided for this booking's invoices (log, one row per invoice): `senden` (send) or `gestoppt` (stopped) with the reasons (codes of the check rule); in `an` (on) mode additionally the sending sequence `geplant` (scheduled, with time), `gesendet` (claimed for sending; actually sent only once `mailAngenommenAt` is set), `abgebrochen` (cancelled), `fehler` (failed); plus only the recipient's domain. Read-only; invoices without an entry are missing.

Input parameters

FieldTypeRequiredNotes
reservationIdstringyes

Output fields

Returns array of object. Fields of each element:

FieldTypeRequiredNotes
invoiceIdstringyes
modusenumyesOne of: schatten, an
entscheidungenumyesOne of: senden, gestoppt, geplant, gesendet, abgebrochen, fehler
gruendearray of stringyes
versandGeplantAtstring · nullableyes
gesendetAtstring · nullableyes
mailAngenommenAtstring · nullableyes
empfaengerDomainstring · nullableyes
herkunftenumyesOne of: autopilot, formular
updatedAtstringyes

invoices.autopilotStoppen

writes

Stop the scheduled automatic sending of ONE invoice: the invoice autopilot then does not send it, and it waits until someone sends it manually. Only from state `geplant` (scheduled; otherwise PRECONDITION_FAILED `autopilot_nicht_geplant`); sets `abgebrochen` (cancelled) with reason `betreiber_gestoppt` and writes an audit log entry. Mutation — changes data, sends nothing.

Input parameters

FieldTypeRequiredNotes
invoiceIdstringyes

Output fields

FieldTypeRequiredNotes
invoiceIdstringyes
entscheidungliteralyesOne of: abgebrochen
gruendearray of stringyes
updatedAtstringyes

invoices.beiStayAusstellen

writesconfirm

Ask the invoicing system (stay) to ISSUE the invoice for ONE departed stay (POST /api/invoice/issue/{reservationId}?sendWebhook=false). Assigns a real, irreversible invoice number. Refused for platform 'manual'/unknown unless auchManuell, when stay already has an invoice, or when Foyer's data changed since delivery unless trotzAbweichung, for cancelled stays unless auchStorniert, between 11:55 and 12:15 Europe/Berlin (stay's own daily run), and while another issue is running (global lock). One attempt, 20 s hard timeout. 201 = issued (read back + mirrored), 404 = reservation unknown, 409 = invoice already exists. Pass nurPruefen: true for a dry run. Requires confirmation.

Input parameters

FieldTypeRequiredNotes
stayIdstringyes
nurPruefenbooleanno
auchManuellbooleanno
trotzAbweichungbooleanno
auchStorniertbooleanno

Output fields

FieldTypeRequiredNotes
artenumyesOne of: pruefung_bestanden, abgelehnt, zugestellt, zugestellt_ohne_vermerk, ausgestellt, nicht_gefunden, existiert_bereits, fehlgeschlagen
textstringyes
grundstringno
httpStatusinteger · nullableno

invoices.cancel

writesconfirm

**DESTRUCTIVE**: Mark an invoice as cancelled — only Foyer-numbered invoices. An invoice numbered by stay is rejected (`storno_nur_in_stay`): stay has no cancellation. The PDF is preserved as an audit record. Once cancelled, the invoice cannot be resent. Use `invoices.reissue` to create a corrected replacement. Requires _confirm: true.

Input parameters

FieldTypeRequiredNotes
idstringyes
reasonstringyes

Output fields

FieldTypeRequiredNotes
idstringyes
statusliteralyesOne of: cancelled
cancelledAtstringyes

invoices.create_request

writes

Mint a guest-facing invoice-request link for a reservation: creates a submission row (status pending, workflow offen) with a CSPRNG token and returns { submissionId, token, path } where path is the public form URL (/invoice-request/{token}) to send the guest. Throws 'reservation_not_found' if the reservation is not in this tenant.

Input parameters

FieldTypeRequiredNotes
reservationIdstringyes

Output fields

FieldTypeRequiredNotes
submissionIdstringyes
tokenstringyes
pathstringyes

invoices.erkannteRechnungsangaben

read-only

Company name and tax number found in the guest's messages — UNCONFIRMED, shown only in the invoice panel while no billing data is on file. Nothing is stored until the operator adopts and saves them. Booking.com often sends both without an address (2026-10-17, reservation 5995772396); `leseRechnungsadresse` then reads nothing. `quelle` is `anker` when an anchor in the text matched (company name, tax number), or `ki` when there is no anchor: then it is the AI's unconfirmed suggestion read from free text, with `strasse`, `plz`, `ort` and `land` (street, postal code, city, country) as far as they were read. Read-only query.

Input parameters

FieldTypeRequiredNotes
stayIdstringyes

Output fields

FieldTypeRequiredNotes
firmastring · nullableyes
steuerIdobject · nullableyes
steuerId.valuestringyes
steuerId.kindenumyesOne of: ust_idnr, steuernummer
quelleenumyesOne of: anker, ki
strassestring · nullableno
plzstring · nullableno
ortstring · nullableno
landstring · nullableno

invoices.get

read-only

Fetch a single Foyer-native invoice by UUID with joined reservation, address, tax-id and line-items. Throws 'invoice_not_found' if the row is missing or belongs to another tenant. Read-only.

Input parameters

FieldTypeRequiredNotes
idstringyes

Output fields

An object keyed by string. Each value is any.

invoices.list

read-only

List Foyer-native invoices (operator inbox + history). All filters are optional: status (draft|created|sent|cancelled|reissued), reservationId (UUID), from/to (YYYY-MM-DD, matched against createdAt), limit (1-500, default 100), offset (default 0). Ordered by createdAt desc. Read-only.

Input parameters

FieldTypeRequiredNotes
statusenumnoOne of: draft, created, sent, cancelled, reissued
reservationIdstringno
fromstringno
tostringno
limitintegerno
offsetintegerno

Output fields

FieldTypeRequiredNotes
invoicesarrayyes

invoices.list_requests

read-only

List invoice requests (Anfragen): every invoice-eligible booking joined with its latest submission, showing the operator workflow status (offen|in_bearbeitung|versandbereit|erledigt, default offen) and completeness badges (hasAddress / hasTaxId / hasInvoice). Optional filters: workflowStatus, needsInvoice (bookings with no invoice yet), search (guest name/email/reservation code), limit (1-200, default 100), offset. Read-only.

Input parameters

FieldTypeRequiredNotes
workflowStatusenumnoOne of: offen, in_bearbeitung, versandbereit, erledigt
needsInvoicebooleanno
searchstringno
limitintegerno
offsetintegerno

Output fields

FieldTypeRequiredNotes
requestsarrayyes

invoices.read_pdf

read-only

Read the text of an issued invoice PDF exactly as sent to the guest / tax advisor (addresses, line items, VAT, totals). Invoice id from `invoices.list` / `invoices.get`. Drafts without a PDF yet return `vorhanden: false`. Owner only. Read-only.

Input parameters

FieldTypeRequiredNotes
invoiceIdstringyes

Output fields

FieldTypeRequiredNotes
invoiceIdstringyes
dateinamestringyes
vorhandenbooleanyes
quelleenum · nullableyesOne of: lokal, stay
seiteninteger · nullableyes
textstringyes
gekuerztbooleanyes
hinweisstringno

invoices.rechnungsdatenErneutSenden

writes

Retries a failed delivery attempt to stay — the button on the red marker. Rationale at `sendeRechnungsdatenErneut`. Mutation — changes data.

Input parameters

FieldTypeRequiredNotes
reservationIdstringyes

Output fields

FieldTypeRequiredNotes
eingereihtbooleanyes

invoices.reissue

writesconfirm

**DESTRUCTIVE**: Mark an existing invoice as `reissued` and create a fresh draft for the same reservation, with a new sequential number and a `parent_invoice_id` link back to the original. The new draft starts without a PDF (placeholder file refs). Requires _confirm: true.

Input parameters

FieldTypeRequiredNotes
idstringyes

Output fields

FieldTypeRequiredNotes
wegenumyesOne of: stay, lokal
fileNamestring · nullableyes
idstring · nullableyes
numberinteger · nullableyes
parentInvoiceIdstring · nullableyes

invoices.remove_request_billing

writesconfirm

Remove billing parts from a reservation's invoice request (command-center 'Löschen'): set tax=true to soft-delete the tax-id (is_removed — none shows, survives the daily re-sync), email=true to hard-delete the billing email. Addresses have no delete. Returns the resulting billing. Mutating action — requires _confirm: true.

Input parameters

FieldTypeRequiredNotes
reservationIdstringyes
taxbooleanno
emailbooleanno

Output fields

FieldTypeRequiredNotes
addressany · nullableyes
taxIdany · nullableyes
emailstring · nullableyes
emailStandany · nullableyes

invoices.request_billing

read-only

Collected billing data for a reservation's invoice request: the latest billing address (name/company, lines, postal code, city, country, isBusiness) and tax-id (value + kind: ust_idnr|steuernummer). Both nullable when the guest hasn't provided them. On a Perk booking, perkTicketAn is the address the invoice must go to instead of email. Read-only.

Input parameters

FieldTypeRequiredNotes
reservationIdstringyes

Output fields

FieldTypeRequiredNotes
addressany · nullableyes
taxIdany · nullableyes
emailstring · nullableyes
emailStandany · nullableyes
perkTicketAnstring · nullableyes

invoices.request_stats

read-only

Invoice-request pipeline counts for the Anfragen tabs: total + per workflow status (offen, in_bearbeitung, versandbereit, erledigt) + needsInvoice (eligible bookings with no invoice yet). Read-only.

Input parameters

Returns object.

Output fields

FieldTypeRequiredNotes
totalnumberyes
offennumberyes
inBearbeitungnumberyes
versandbereitnumberyes
erledigtnumberyes
needsInvoicenumberyes

invoices.send

writesconfirm

Email the invoice to the guest. This is a real send over the configured channel. Requires confirmation.

Input parameters

FieldTypeRequiredNotes
invoiceIdstringyes
toEmailstringyes
trotzdembooleanno

Output fields

FieldTypeRequiredNotes
okliteralyesOne of: true
viaenumyesOne of: gmail, brevo, postmark
messageIdstringyes
sentAtstring · nullableyes

invoices.send_smtp

writesconfirm

**IRREVERSIBLE**: send a Foyer-native invoice PDF to the guest via email. Uses Postmark BYOK if the tenant has configured a token, else falls back to the Gmail SMTP relay. Marks the invoice as 'sent' on success. Once the remote MTA accepts the message there is no way to recall it. Refused with `stornorechnung_offen` for every cancelled stay (any channel, direct bookings included, also with total 0) and for a stay whose folio carries a cancellation fee (the invoicing route for cancellations is still open). Refused with `kuerzlich_versendet:<ISO time>` when the same invoice already went to the same address within the last 24 hours. Mutating action — requires _confirm: true.

Input parameters

FieldTypeRequiredNotes
invoiceIdstringyes
toEmailstringyes

Output fields

FieldTypeRequiredNotes
okliteralyesOne of: true
viaenumyesOne of: gmail, brevo, postmark
messageIdstringyes
sentAtstring · nullableyes

invoices.setRequestStatus

writes

Set the operator workflow status for a reservation. Lazily materializes a submission row + logs the transition. Mutation — changes data.

Input parameters

FieldTypeRequiredNotes
reservationIdstringyes
workflowStatusenumyesOne of: offen, in_bearbeitung, versandbereit, erledigt

Output fields

FieldTypeRequiredNotes
okliteralyesOne of: true
submissionIdstringyes
workflowStatusenumyesOne of: offen, in_bearbeitung, versandbereit, erledigt

invoices.stats

read-only

Counters for the operator dashboard stat-strip: total + per-status (draft, created, sent, cancelled, reissued) for the caller's tenant. Read-only.

Input parameters

Returns object.

Output fields

FieldTypeRequiredNotes
totalCountnumberyes
draftCountnumberyes
createdCountnumberyes
sentCountnumberyes
cancelledCountnumberyes
reissuedCountnumberyes

invoices.stayAbweichungen

read-only

List stays already delivered to the invoicing system (stay) whose current data no longer matches what was delivered (checksum differs, now incomplete, or no longer eligible e.g. fully refunded) — stay may invoice an outdated state. Read-only. Defaults to departures in the last 30 days; auchAeltere lifts that.

Input parameters

FieldTypeRequiredNotes
stayIdstringno
auchAelterebooleanno

Output fields

FieldTypeRequiredNotes
grenzestring · nullableyes
geprueftintegeryes
ausserhalbFensterintegeryes
abweichendarray of objectyes
abweichend.stayIdstringyes
abweichend.zimmerstringyes
abweichend.anreiseTagstring · nullableyes
abweichend.abreiseTagstring · nullableyes
abweichend.felderarray of stringno
nichtVergleichbararray of objectyes
nichtVergleichbar.stayIdstringyes
nichtVergleichbar.zimmerstringyes
nichtVergleichbar.abreiseTagstring · nullableyes
nichtVergleichbar.fehlendarray of stringyes
nichtMehrErhobenarray of objectyes
nichtMehrErhoben.stayIdstringyes
nichtMehrErhoben.zimmerstring · nullableyes
nichtMehrErhoben.abreiseTagstring · nullableyes
nichtMehrErhoben.statusstring · nullableyes

invoices.stayLage

read-only

Which stay action currently makes sense for THIS booking — the invoice request shows or hides the “Rechnungssystem (stay)” (invoicing system (stay)) section accordingly. Without a transaction: reads staydb through the tunnel (rationale at `moduleProcedureOhneTransaktion`). Read-only query.

Input parameters

FieldTypeRequiredNotes
stayIdstringyes

Output fields

FieldTypeRequiredNotes
lageenumyesOne of: vor_abreise, nachliefern, ausstellen, erledigt, storniert, unbekannt
abreiseTagstring · nullableyes

invoices.submitForm

writes

PUBLIC — no auth. Token-in-URL is the auth principal. The guest opens /invoice-request/{token} (created by the operator on the form_submissions row) and POSTs their billing address. We: 1. Look up the submission row by token via getDb() — outside RLS, since no tenant is pinned yet. Token is CSPRNG and unique. 2. Reject if the row doesn't exist (NOT_FOUND) or has already been submitted (CONFLICT — idempotent re-submit guard). 3. Enter withSystem(submission.tenantId) so all subsequent inserts… Mutation — changes data.

Input parameters

FieldTypeRequiredNotes
tokenstringyes
firstNamestringyes
lastNamestringyes
emailstringyes
isBusinessbooleannoDefault: false
companystringno
line1stringyes
line2stringno
postalCodestringyes
citystringyes
countrystringno
taxIdValuestringno
taxIdKindenumnoOne of: ust_idnr, steuernummer

Output fields

FieldTypeRequiredNotes
okliteralyesOne of: true
submitCountintegeryes

invoices.updateRequestBilling

writes

Operator edit of a reservation's billing data (address / tax-id / email) — command-center "Bearbeiten" parity. Each part optional; append-only insert. Mutation — changes data.

Input parameters

FieldTypeRequiredNotes
reservationIdstringyes
addressobject · nullableno
address.namestringyes
address.line1string · nullableno
address.line2string · nullableno
address.postalCodestring · nullableno
address.citystring · nullableno
address.countrystring · nullableno
address.isBusinessbooleanno
taxIdobject · nullableno
taxId.valuestringyes
taxId.kindenumyesOne of: ust_idnr, steuernummer
emailstring · nullableno

Output fields

FieldTypeRequiredNotes
perkTicketAnstring · nullableno
addressobject · nullableyes
address.namestringyes
address.line1string · nullableyes
address.line2string · nullableyes
address.postalCodestring · nullableyes
address.citystring · nullableyes
address.countrystring · nullableyes
address.isBusinessbooleanyes
address.legacyIdstring · nullableyes
address.anStayUebertragenAtstring · nullableyes
address.anStayFehlerstring · nullableyes
taxIdobject · nullableyes
taxId.valuestringyes
taxId.kindstringyes
taxId.legacyIdstring · nullableyes
taxId.anStayUebertragenAtstring · nullableyes
taxId.anStayFehlerstring · nullableyes
emailstring · nullableyes
emailStandobject · nullableyes
emailStand.legacyIdstring · nullableyes
emailStand.anStayUebertragenAtstring · nullableyes
emailStand.anStayFehlerstring · nullableyes

invoices.update_address

writesconfirm

Update the billing address on a Foyer-native invoice. Inserts a new invoice_addresses row (append-only — old rows stay for audit) and repoints invoices.address_id at it. Use to correct typos / fix incomplete guest submissions. Mutating action — requires _confirm: true.

Input parameters

FieldTypeRequiredNotes
invoiceIdstringyes
addressobjectyes
address.namestringyes
address.line1stringno
address.line2stringno
address.postalCodestringno
address.citystringno
address.countrystringno
address.isBusinessbooleanno

Output fields

FieldTypeRequiredNotes
idstringyes

invoices.update_email

writesconfirm

Set or replace the billing email for a reservation. Inserts a new invoice_emails row (append-only) — send-time logic resolves the latest email by reservation, so this cascades to all future invoices for that stay. Mutating action — requires _confirm: true.

Input parameters

FieldTypeRequiredNotes
reservationIdstringyes
emailstringyes

Output fields

FieldTypeRequiredNotes
idstringyes

invoices.update_tax_id

writesconfirm

Set or replace the tax ID on a Foyer-native invoice. Inserts a new invoice_tax_ids row (append-only — old rows stay for audit) and repoints invoices.tax_id_id at it. `kind` distinguishes USt-IdNr (EU VAT) from Steuernummer (DE local). Mutating action — requires _confirm: true.

Input parameters

FieldTypeRequiredNotes
invoiceIdstringyes
valuestringyes
kindenumyesOne of: ust_idnr, steuernummer

Output fields

FieldTypeRequiredNotes
idstringyes