Integration für Anbieter

1. Wie es zusammenhängt

Sie legen in Excel eine Zuordnung für Ihre Arbeitsmappe an, so wie jeder andere Nutzer auch. Als Anbieter veröffentlichen Sie anschließend eine Version dieser Zuordnung und teilen uns mit, welche Organisationen Ihre Kunden sind. Von da an sehen alle Personen in diesen Organisationen Ihre Zuordnung in ihrem modelflow-Bereich und können Ihre Arbeitsmappe damit füllen.

Ihre Kunden müssen nichts tun und zahlen nichts. Auf ihrer Seite werden keine Plätze vergeben und keine Einladungen angenommen. Sie erhalten monatlich eine Rechnung über die Personen, die Ihre Zuordnungen tatsächlich genutzt haben. Der Nachweis zeigt Ihnen, bei welchem Kunden das war, damit Sie es weiterberechnen können.

Sie müssen nichts entwickeln und nichts betreiben. Zuordnungen werden von einem Menschen angelegt, veröffentlicht und zurückgezogen: in Excel und im Anbieterportal. Die API gibt es für die zwei Aufgaben, die ein System besser erledigt als ein Mensch: Ihre Kundenliste mit Ihrem CRM abzugleichen und den monatlichen Nachweis für Ihre eigene Rechnungsstellung abzurufen. Beides geht auch von Hand im Portal.

2. Anbieter werden

Melden Sie sich unter app.trymodelflow.com mit Ihrem Geschäftskonto an und öffnen Sie das Anbieterportal. Mit der Aktivierung des Anbietermodus beginnt ein eigenes Abonnement: eine Plattformgebühr und dazu die aktiven Personen bei Ihren Kunden, monatlich im Nachhinein abgerechnet. Ihr erster API-Schlüssel wird dabei gleich erstellt.

Im Portal erstellen Sie API-Schlüssel, veröffentlichen Ihre Zuordnungen und sehen Ihre Kunden und Nachweise. Eine Firma mit zwanzig Kunden pflegt sie dort von Hand. Eine Firma mit CRM wird den Kundenabgleich weiter unten einrichten wollen.

3. Authentifizierung

Die API wird mit einem Anbieter-API-Schlüssel authentifiziert und nicht mit einer Benutzeranmeldung. So kann sie unbeaufsichtigt in Ihrem CRM oder in einem nächtlichen Job laufen. Senden Sie den Schlüssel im Header x-provider-key oder als Bearer-Token.

Ein Schlüssel wird nur einmal angezeigt, nämlich beim Erstellen. Wir speichern ausschließlich einen Hash davon und können ihn nicht erneut anzeigen. Sie können mehrere gültige Schlüssel gleichzeitig haben, und genau so tauschen Sie einen aus: neuen Schlüssel erstellen, Ihr System umstellen, alten Schlüssel widerrufen.

Die Basisadresse lautet https://app.trymodelflow.com/v1/provider. Anfragen und Antworten sind JSON. Ein Schlüssel kann drei Dinge: den Überblick lesen, Kunden hinzufügen und entfernen und Nachweise lesen. Alles andere, auch das Erstellen und Widerrufen von Schlüsseln, erledigt eine angemeldete Person im Portal. Diese Adressen nehmen keinen Schlüssel an und beantworten ihn mit 401. Pro Anbieter sind 600 Anfragen pro Minute erlaubt.

curl https://app.trymodelflow.com/v1/provider \
  -H "x-provider-key: mf_..."

4. Kunden hinzufügen

Sie benennen einen Kunden über eine Domain, mit der er sich bei Microsoft 365 anmeldet. Wir ermitteln daraus seine Microsoft-Organisation, und alle Personen in dieser Organisation dürfen Ihre veröffentlichten Zuordnungen nutzen. Mehrere Domains eines Kunden gehören in denselben Eintrag. Die Referenz gehört Ihnen, üblicherweise die CRM-Nummer, und sie steht später in jeder Zeile des Nachweises.

Sie können einen einzelnen Kunden senden oder eine ganze Liste. Einen bereits vorhandenen Kunden erneut zu senden, ändert außer seiner Referenz nichts. Sie können also jede Nacht Ihre vollständige Kundenliste übertragen, ohne selbst nachzuhalten, was sich geändert hat.

Eine fehlerhafte Domain lässt den Rest nie scheitern. Eine Domain, die wir noch nicht zuordnen können, wird gespeichert und später erneut geprüft, denn vielleicht hat der Kunde seine eigene Microsoft-365-Einrichtung noch nicht abgeschlossen. Sie steht unter warnings mit dem Grund tenant_not_resolvable und wird von selbst aktiv, sobald sie sich zuordnen lässt.

curl -X POST https://app.trymodelflow.com/v1/provider/customers \
  -H "x-provider-key: mf_..." \
  -H "content-type: application/json" \
  -d '{
    "customers": [
      { "domains": ["kunde.de", "kunde-gruppe.de"], "reference": "CRM-4417" },
      { "domains": ["other-firm.nl"], "reference": "CRM-4418" }
    ]
  }'

Die Antwort zählt, was geschehen ist:

{
  "added": 1,
  "unchanged": 1,
  "warnings": [{ "domain": "other-firm.nl", "reason": "tenant_not_resolvable" }]
}

5. Einen Kunden entfernen

Wenn Sie einen Kunden entfernen, endet sein Zugang mit dem laufenden Abrechnungszeitraum und nicht sofort. Wer mitten in einem Jahresabschluss steckt, arbeitet bis zum Monatsende weiter. Die id erhalten Sie aus dem Überblick, einem GET auf die Basisadresse, der Ihre Schlüssel, Kunden und veröffentlichten Zuordnungen auflistet.

curl -X DELETE https://app.trymodelflow.com/v1/provider/customers/{id} \
  -H "x-provider-key: mf_..."

6. Zuordnungen veröffentlichen

Veröffentlicht wird von einem Menschen im Anbieterportal, nicht über die API. Eine Zuordnung entsteht in Excel an Ihrer Arbeitsmappe, deshalb gibt es nichts, was ein Skript von sich aus veröffentlichen könnte. Im Portal steht jede Zuordnung Ihrer Organisation mit ihrer aktuellen Version und einer Schaltfläche zum Veröffentlichen.

Sie veröffentlichen eine bestimmte Version einer Zuordnung und nicht die Zuordnung als solche. Mehrere Versionen können gleichzeitig gelten, und Ihre Kunden sehen jede Version, die nicht zurückgezogen wurde. So wechseln sie auf einen neuen Stand Ihrer Arbeitsmappe, wenn es ihnen passt, und nicht an dem Tag, an dem Sie veröffentlichen.

Eine zurückgezogene Version steht für neue Befüllungen nicht mehr zur Auswahl, eine laufende Befüllung wird dadurch nie unterbrochen.

7. Abrechnungsnachweise

Pro Kalendermonat gibt es einen Nachweis. Er entsteht zusammen mit Ihrer Rechnung und enthält dieselben Zahlen. Ein GET auf /statements listet die Monate, ein GET auf /statements/{JJJJ-MM} liefert einen davon.

Jede Zeile ist ein Kunde: Ihre Referenz, die Zahl der aktiven Personen, die Zahl der Befüllungen und die genutzten Versionen. Ein ausgestellter Nachweis ist endgültig und wird nie neu berechnet.

Sie sehen ausschließlich die Nutzung Ihrer eigenen Zuordnungen. Was ein Kunde mit eigenen Zuordnungen oder mit denen eines anderen Anbieters tut, ist für Sie nicht sichtbar.

curl https://app.trymodelflow.com/v1/provider/statements/2026-08 \
  -H "x-provider-key: mf_..."

{
  "period": "2026-08",
  "issuedAt": "2026-09-01T00:04:11.000Z",
  "totalActiveUsers": 14,
  "billableUsers": 14,
  "lines": [
    {
      "customerTenantId": "6d0f...",
      "customerName": "Kunde GmbH",
      "reference": "CRM-4417",
      "activeUsers": 9,
      "runs": 61,
      "mapVersions": ["Valuation model v2"]
    }
  ]
}

8. Was als Nutzung zählt

Eine aktive Person ist jemand, der in dem Kalendermonat mindestens eine Befüllung mit einer Ihrer veröffentlichten Zuordnungen abgeschlossen hat. Wer sich nur angemeldet, aber nichts befüllt hat, zählt nicht. Wer hundert Befüllungen durchgeführt hat, zählt einmal.

Die Zählung beginnt jeden Monat bei null. Ihre Rechnung besteht aus der Plattformgebühr und den aktiven Personen des Monats, mit der in Ihrem Tarif vereinbarten Mindestzahl. Ihren Kunden stellen wir nie etwas in Rechnung.

Ist ein Kunde zugleich selbst modelflow-Kunde oder auch von einem zweiten Anbieter freigeschaltet, vermischt sich nichts: Die Nutzung wird der Zuordnung zugerechnet. Befüllungen mit Ihren Zuordnungen zählen bei Ihnen, alle anderen nicht.

9. Fehler

Fehler kommen mit einem HTTP-Status und einem Body, der einen stabilen Code nennt. 401 bedeutet, dass der Schlüssel fehlt, falsch ist oder widerrufen wurde. 403 mit account_closed bedeutet, dass Ihr Konto geschlossen ist. 404 nennt, was nicht gefunden wurde. 429 bedeutet, dass das Anfragelimit überschritten ist. Der Aufruf lässt sich dann einfach eine Minute später wiederholen.

{ "error": { "code": "customer_not_found", "message": "Customer not found" } }

10. Wenn eine Zahlung fehlschlägt

Eine fehlgeschlagene Zahlung auf Ihrer Seite sperrt Ihre Kunden nicht aus. Sie behalten den Zugang 14 Tage lang, während die Zahlung erneut versucht wird, und Sie werden sofort benachrichtigt. Erst nach Ablauf dieser Frist stehen Ihre Zuordnungen den Kunden nicht mehr zur Verfügung, und sie sind wieder da, sobald die Rechnung bezahlt ist.