invoices.anStayNachliefern
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
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | yes | |
nurPruefen | boolean | no | |
auchStorniert | boolean | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
art | enum | yes | One of: pruefung_bestanden, abgelehnt, zugestellt, zugestellt_ohne_vermerk, ausgestellt, nicht_gefunden, existiert_bereits, fehlgeschlagen |
text | string | yes | |
grund | string | no | |
httpStatus | integer · nullable | no |
invoices.autopilotStand
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
| Field | Type | Required | Notes |
|---|---|---|---|
reservationId | string | yes |
Output fields
Returns array of object. Fields of each element:
| Field | Type | Required | Notes |
|---|---|---|---|
invoiceId | string | yes | |
modus | enum | yes | One of: schatten, an |
entscheidung | enum | yes | One of: senden, gestoppt, geplant, gesendet, abgebrochen, fehler |
gruende | array of string | yes | |
versandGeplantAt | string · nullable | yes | |
gesendetAt | string · nullable | yes | |
mailAngenommenAt | string · nullable | yes | |
empfaengerDomain | string · nullable | yes | |
herkunft | enum | yes | One of: autopilot, formular |
updatedAt | string | yes |
invoices.autopilotStoppen
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
| Field | Type | Required | Notes |
|---|---|---|---|
invoiceId | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
invoiceId | string | yes | |
entscheidung | literal | yes | One of: abgebrochen |
gruende | array of string | yes | |
updatedAt | string | yes |
invoices.beiStayAusstellen
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
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | yes | |
nurPruefen | boolean | no | |
auchManuell | boolean | no | |
trotzAbweichung | boolean | no | |
auchStorniert | boolean | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
art | enum | yes | One of: pruefung_bestanden, abgelehnt, zugestellt, zugestellt_ohne_vermerk, ausgestellt, nicht_gefunden, existiert_bereits, fehlgeschlagen |
text | string | yes | |
grund | string | no | |
httpStatus | integer · nullable | no |
invoices.cancel
**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
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
reason | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
status | literal | yes | One of: cancelled |
cancelledAt | string | yes |
invoices.create_request
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
| Field | Type | Required | Notes |
|---|---|---|---|
reservationId | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
submissionId | string | yes | |
token | string | yes | |
path | string | yes |
invoices.erkannteRechnungsangaben
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
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
firma | string · nullable | yes | |
steuerId | object · nullable | yes | |
steuerId.value | string | yes | |
steuerId.kind | enum | yes | One of: ust_idnr, steuernummer |
quelle | enum | yes | One of: anker, ki |
strasse | string · nullable | no | |
plz | string · nullable | no | |
ort | string · nullable | no | |
land | string · nullable | no |
invoices.get
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
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes |
Output fields
An object keyed by string. Each value is any.
invoices.list
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
| Field | Type | Required | Notes |
|---|---|---|---|
status | enum | no | One of: draft, created, sent, cancelled, reissued |
reservationId | string | no | |
from | string | no | |
to | string | no | |
limit | integer | no | |
offset | integer | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
invoices | array | yes |
invoices.list_requests
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
| Field | Type | Required | Notes |
|---|---|---|---|
workflowStatus | enum | no | One of: offen, in_bearbeitung, versandbereit, erledigt |
needsInvoice | boolean | no | |
search | string | no | |
limit | integer | no | |
offset | integer | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
requests | array | yes |
invoices.read_pdf
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
| Field | Type | Required | Notes |
|---|---|---|---|
invoiceId | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
invoiceId | string | yes | |
dateiname | string | yes | |
vorhanden | boolean | yes | |
quelle | enum · nullable | yes | One of: lokal, stay |
seiten | integer · nullable | yes | |
text | string | yes | |
gekuerzt | boolean | yes | |
hinweis | string | no |
invoices.rechnungsdatenErneutSenden
Retries a failed delivery attempt to stay — the button on the red marker. Rationale at `sendeRechnungsdatenErneut`. Mutation — changes data.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
reservationId | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
eingereiht | boolean | yes |
invoices.reissue
**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
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
weg | enum | yes | One of: stay, lokal |
fileName | string · nullable | yes | |
id | string · nullable | yes | |
number | integer · nullable | yes | |
parentInvoiceId | string · nullable | yes |
invoices.remove_request_billing
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
| Field | Type | Required | Notes |
|---|---|---|---|
reservationId | string | yes | |
tax | boolean | no | |
email | boolean | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
address | any · nullable | yes | |
taxId | any · nullable | yes | |
email | string · nullable | yes | |
emailStand | any · nullable | yes |
invoices.request_billing
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
| Field | Type | Required | Notes |
|---|---|---|---|
reservationId | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
address | any · nullable | yes | |
taxId | any · nullable | yes | |
email | string · nullable | yes | |
emailStand | any · nullable | yes | |
perkTicketAn | string · nullable | yes |
invoices.request_stats
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
| Field | Type | Required | Notes |
|---|---|---|---|
total | number | yes | |
offen | number | yes | |
inBearbeitung | number | yes | |
versandbereit | number | yes | |
erledigt | number | yes | |
needsInvoice | number | yes |
invoices.send
Email the invoice to the guest. This is a real send over the configured channel. Requires confirmation.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
invoiceId | string | yes | |
toEmail | string | yes | |
trotzdem | boolean | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
ok | literal | yes | One of: true |
via | enum | yes | One of: gmail, brevo, postmark |
messageId | string | yes | |
sentAt | string · nullable | yes |
invoices.send_smtp
**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
| Field | Type | Required | Notes |
|---|---|---|---|
invoiceId | string | yes | |
toEmail | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
ok | literal | yes | One of: true |
via | enum | yes | One of: gmail, brevo, postmark |
messageId | string | yes | |
sentAt | string · nullable | yes |
invoices.setRequestStatus
Set the operator workflow status for a reservation. Lazily materializes a submission row + logs the transition. Mutation — changes data.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
reservationId | string | yes | |
workflowStatus | enum | yes | One of: offen, in_bearbeitung, versandbereit, erledigt |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
ok | literal | yes | One of: true |
submissionId | string | yes | |
workflowStatus | enum | yes | One of: offen, in_bearbeitung, versandbereit, erledigt |
invoices.stats
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
| Field | Type | Required | Notes |
|---|---|---|---|
totalCount | number | yes | |
draftCount | number | yes | |
createdCount | number | yes | |
sentCount | number | yes | |
cancelledCount | number | yes | |
reissuedCount | number | yes |
invoices.stayAbweichungen
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
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | no | |
auchAeltere | boolean | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
grenze | string · nullable | yes | |
geprueft | integer | yes | |
ausserhalbFenster | integer | yes | |
abweichend | array of object | yes | |
abweichend.stayId | string | yes | |
abweichend.zimmer | string | yes | |
abweichend.anreiseTag | string · nullable | yes | |
abweichend.abreiseTag | string · nullable | yes | |
abweichend.felder | array of string | no | |
nichtVergleichbar | array of object | yes | |
nichtVergleichbar.stayId | string | yes | |
nichtVergleichbar.zimmer | string | yes | |
nichtVergleichbar.abreiseTag | string · nullable | yes | |
nichtVergleichbar.fehlend | array of string | yes | |
nichtMehrErhoben | array of object | yes | |
nichtMehrErhoben.stayId | string | yes | |
nichtMehrErhoben.zimmer | string · nullable | yes | |
nichtMehrErhoben.abreiseTag | string · nullable | yes | |
nichtMehrErhoben.status | string · nullable | yes |
invoices.stayLage
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
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
lage | enum | yes | One of: vor_abreise, nachliefern, ausstellen, erledigt, storniert, unbekannt |
abreiseTag | string · nullable | yes |
invoices.submitForm
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
| Field | Type | Required | Notes |
|---|---|---|---|
token | string | yes | |
firstName | string | yes | |
lastName | string | yes | |
email | string | yes | |
isBusiness | boolean | no | Default: false |
company | string | no | |
line1 | string | yes | |
line2 | string | no | |
postalCode | string | yes | |
city | string | yes | |
country | string | no | |
taxIdValue | string | no | |
taxIdKind | enum | no | One of: ust_idnr, steuernummer |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
ok | literal | yes | One of: true |
submitCount | integer | yes |
invoices.updateRequestBilling
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
| Field | Type | Required | Notes |
|---|---|---|---|
reservationId | string | yes | |
address | object · nullable | no | |
address.name | string | yes | |
address.line1 | string · nullable | no | |
address.line2 | string · nullable | no | |
address.postalCode | string · nullable | no | |
address.city | string · nullable | no | |
address.country | string · nullable | no | |
address.isBusiness | boolean | no | |
taxId | object · nullable | no | |
taxId.value | string | yes | |
taxId.kind | enum | yes | One of: ust_idnr, steuernummer |
email | string · nullable | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
perkTicketAn | string · nullable | no | |
address | object · nullable | yes | |
address.name | string | yes | |
address.line1 | string · nullable | yes | |
address.line2 | string · nullable | yes | |
address.postalCode | string · nullable | yes | |
address.city | string · nullable | yes | |
address.country | string · nullable | yes | |
address.isBusiness | boolean | yes | |
address.legacyId | string · nullable | yes | |
address.anStayUebertragenAt | string · nullable | yes | |
address.anStayFehler | string · nullable | yes | |
taxId | object · nullable | yes | |
taxId.value | string | yes | |
taxId.kind | string | yes | |
taxId.legacyId | string · nullable | yes | |
taxId.anStayUebertragenAt | string · nullable | yes | |
taxId.anStayFehler | string · nullable | yes | |
email | string · nullable | yes | |
emailStand | object · nullable | yes | |
emailStand.legacyId | string · nullable | yes | |
emailStand.anStayUebertragenAt | string · nullable | yes | |
emailStand.anStayFehler | string · nullable | yes |
invoices.update_address
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
| Field | Type | Required | Notes |
|---|---|---|---|
invoiceId | string | yes | |
address | object | yes | |
address.name | string | yes | |
address.line1 | string | no | |
address.line2 | string | no | |
address.postalCode | string | no | |
address.city | string | no | |
address.country | string | no | |
address.isBusiness | boolean | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes |
invoices.update_email
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
| Field | Type | Required | Notes |
|---|---|---|---|
reservationId | string | yes | |
email | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes |
invoices.update_tax_id
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
| Field | Type | Required | Notes |
|---|---|---|---|
invoiceId | string | yes | |
value | string | yes | |
kind | enum | yes | One of: ust_idnr, steuernummer |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes |