Skip to content
Gestalt

API: Vertical — DE invoice / payment / advisor

Capability state: fixture-rehearsed. This is Gestalt’s first serious-vertical fixture, walking the full invoice → payment → advisor → bookkeeping → period-close flow as one membrane operation.

The vertical operation vertical.de.invoicePaymentAdvisor exists to demonstrate that Gestalt’s substrate can carry a buyer-legible flow end-to-end. It is the German invoice / payment / Steuerberater wedge described in workflows/open/M4-developer-integration-serious-button.md and the gap-7 fix in workflows/open/018-scaffold-vs-real-runtime-gap-audit.md.

vertical.de.invoicePaymentAdvisor

Section titled “vertical.de.invoicePaymentAdvisor”

Submit the first German invoice / payment / advisor serious vertical through the substrate membrane in one call.

POST /v1/verticals/de/invoice-payment-advisor
runtime_owner: cloud_geist
sdk_role: submit first German invoice/payment/advisor serious vertical through substrate membrane
request_record: CloudGermanInvoicePaymentAdvisorRequest
responses: atoms | signer_provenance | durable_commit | refusal | receipt

What this operation does

Section titled “What this operation does”

Internally this operation orchestrates several economy operations as one logical act:

  1. Admits an invoice atom, opening a receivable obligation and a closure surface.
  2. Admits a payment observation atom that settles the receivable (amount + currency match).
  3. Admits a bookkeeping fact atom linking invoice + payment, with advisor evidence required.
  4. Admits a period close atom for the period containing the invoice (only if the closure surface is fully resolved).

Each step is itself an atom and produces its own sub-receipt. The vertical receipt aggregates them.

Why a single vertical operation

Section titled “Why a single vertical operation”

The individual economy.* operations exist (see economy.md) and are usable independently. The vertical operation exists because:

  • A buyer-legible flow needs a single membrane crossing for the Koerper to trigger, not a four-step orchestration the Koerper has to retry on partial failure.
  • The vertical embeds the German-specific defaults (EUR, EU VAT posture, GoBD evidence requirements, Steuerberater advisor lens) so a Koerper does not have to know them.
  • It is the point at which Gestalt commits to having an opinion about how a German SMB invoice/payment/advisor flow works end-to-end.

Request

Section titled “Request”

The full request shape lives in crates/gestalt-cloud/src/lib.rs as CloudGermanInvoicePaymentAdvisorRequest. Conceptually:

tenant
invoice payload (amount_cents, currency, line items, customer)
payment observation evidence
advisor evidence (Steuerberater review)
period (e.g. "2026-04")

For the exact field set today, run:

Terminal window
cargo run -p gestalt-cli -- cloud membrane-contract

and inspect the request record.

Response

Section titled “Response”
{
  "operation": "vertical.de.invoicePaymentAdvisor",
  "outcome": "admitted",
  "body": {
    "atoms": {
      "invoice": "atom:invoice_...",
      "paymentObservation": "atom:payment_...",
      "bookkeepingFact": "atom:bookkeeping_...",
      "periodClose": "atom:period_close_..."
    },
    "signer": { "kind": "tenant_signer" },
    "durableCommit": { "status": "fixture" }
  },
  "receipt": {...}
}

If any step refuses, the whole vertical refuses and the body carries a structured refusal naming which step failed:

{
  "operation": "vertical.de.invoicePaymentAdvisor",
  "outcome": "refused",
  "body": {
    "failedStep": "bookkeepingFact",
    "failedGate": "economic_bookkeeping_evidence_incomplete",
    "missing": ["advisor_evidence"]
  },
  "receipt": {...}
}

Outcomes

Section titled “Outcomes”
admitted    all four atoms admitted; period closed for the cited period
refused     a step refused; structured failedStep + failedGate
pending     a step opened a pending action (advisor must intervene)

SDK example

Section titled “SDK example”

The TS SDK does not yet expose a typed convenience method for this vertical; call it via raw fetch using the contract:

const response = await fetch(
  "http://127.0.0.1:3011/v1/verticals/de/invoice-payment-advisor",
  {
    method: "POST",
    headers: {
      authorization: "Bearer fixture-session-token",
      "content-type": "application/json",
    },
    body: JSON.stringify({
      tenant: "tenant_node:rheinwerk_calibration",
      invoice: {
        amount_cents: 11900,
        currency: "EUR",
        // ... line items, customer ref
      },
      paymentEvidence: "evidence_bundle:payment_observation",
      advisorEvidence: "evidence_bundle:steuerberater_review",
      period: "2026-04",
    }),
  }
);

What this proves and what it does not

Section titled “What this proves and what it does not”

Proves:

  • The substrate can carry a German invoice/payment/advisor flow end-to-end as one membrane crossing.
  • The economy operations compose into a coherent vertical.
  • A Koerper can ship a single button for a serious flow without inventing orchestration.

Does not prove:

  • That the German VAT / GoBD authority package is real (it is fixture — see 022 gap report item 3, and the catalog entry in authority-packages/catalog.fixture.json).
  • That the advisor evidence is a real Steuerberater opinion atom (it is a fixture evidence bundle).
  • That the period close is durable in any production sense.

The vertical demonstrates the shape of authentic use. Authentic use itself requires the hard blockers in the gap report to land.

Section titled “Where to read next”