Die Kostenübernahme des Softwarehauses nutzen — oder bewusst nicht

Eine Werkstatt nutzt die tapinomahub-Funktionen über ihre Werkstattsoftware. Der Hersteller der Software hat angeboten, die Fahrzeugabfragen zu übernehmen. Die Werkstatt hat aber auch eigenes Guthaben und eigene Konditionen — und will nicht erst auf der Rechnung sehen, welche Abfrage wer bezahlt hat.

Die Kostenübernahme ist im Hub eine ausdrückliche Beziehung mit zwei Seiten: Der Sponsor erteilt sie und kann die Wahl der Konditionen freigeben, der Begünstigte sieht sie und entscheidet. Nichts davon geschieht stillschweigend — unter Partnerkonditionen auch nicht, wenn eine Abfrage ausserhalb der Übernahme liegt.

Was dieser Fall voraussetzt

• Eine erteilte Kostenübernahme. Sie entsteht beim Sponsor; der Begünstigte kann sie nicht selbst anlegen.
• Die Freigabe der Partnerkonditionen, wenn diese gewählt werden sollen. Ohne partnerTermsAllowed antwortet die Wahl von partner mit 403.
• Ein Blick auf die abgedeckten Endpunkte. endpointKeys sagt, wofür die Übernahme gilt — nicht jede Abfrage ist enthalten.
• Eine Entscheidung für den Fall ausserhalb der Übernahme. Unter partner wird eine nicht abgedeckte Abfrage abgewiesen, nicht aus dem eigenen Guthaben bezahlt.

Der Ablauf

Die Tabelle nennt je Stufe den zuständigen Aufruf und das, was danach vorliegt. Die Begründung, warum die Stufe nicht übersprungen werden kann, steht darunter.

Warum jede Stufe nötig ist

1. Die Übernahmen ansehen. GET /client/sponsorship-grants/received listet je Übernahme reference, sponsor, endpointKeys, startsAt, endsAt, active, partnerTermsAllowed und partnerTermsChosen. Hier steht, was abgedeckt ist und ob die Wahl überhaupt offen ist.
2. Die Konditionen wählen. PUT /client/sponsorship-grants/received/{grantReference}/billing-mode nimmt mode mit own oder partner. Unter partner bleibt das eigene Guthaben unberührt; ohne Freigabe des Sponsors antwortet der Aufruf mit 403. Nimmt der Sponsor die Freigabe zurück, fällt die Wahl mit ihr.
3. Das Guthaben lesen. GET /client/credits liefert balanceCents, creditLimitCents und availableCents. Arbeitet der Betrieb zu Partnerkonditionen, ist billingMode partner und die Beträge sind null — sein Guthaben wird nicht belastet und deshalb auch nicht ausgewiesen.
4. Die Nutzung lesen. GET /client/usage nennt den Zeitraum, je Plan used, includedMonthlyQuantity und remaining und je Endpunkt used und chargedCents. Damit lässt sich prüfen, ob die Abfragen dort gelandet sind, wo die Wahl sie hinschicken sollte.

curl -X PUT \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"mode":"partner"}' \
  'https://api.tapinomahub.com/client/sponsorship-grants/received/<grantReference>/billing-mode'

Was am Ende vorliegt

Am Ende weiss der Betrieb zu jeder Abfrage, wer sie bezahlt: unter Partnerkonditionen der Sponsor für die abgedeckten Endpunkte; unter eigenen Konditionen wird zuerst aus dem eigenen Plan und Guthaben abgerechnet, und der Sponsor springt nur im Rückfall ein. Und unter Partnerkonditionen wird eine Abfrage ausserhalb der Übernahme sichtbar abgewiesen, statt unbemerkt Guthaben zu kosten.

Wo das in der Dokumentation steht

Die verbindlichen Feldlisten, Fehlercodes und Beispielantworten stehen im OpenAPI-Vertrag dieser Fläche unter docs.tapinomahub.com (tapinoma-hub). Alle Anwendungsfälle nach Fläche und Rolle geordnet: Übersicht der Anwendungsfälle.