Spezialanbindungen neben den App-Tools

Fast alles, was du per API mit SynCore machst, läuft über die App-Tools. Für einige feste Aufgaben gibt es zusätzlich eigene Endpunkte, zum Beispiel für ein Anmeldeformular auf deiner Website oder für Bestellungen aus einem Shop. Jeder davon verlangt einen eigenen Scope.

Was für alle Spezialanbindungen gilt

• Du authentifizierst dich mit dem Header X-API-KEY. Eine Anmeldung im Browser zählt hier nicht.
• Der Schlüssel bestimmt den Mandanten. Kein Feld in der Anfrage kann ihn ändern.
• Jeder Endpunkt prüft seinen eigenen Scope. Ein App-Tools-Schlüssel öffnet keine Spezialanbindung, und ein Schlüssel für eine Spezialanbindung öffnet keine App-Tools.
• Fehlt der Schlüssel oder ist er ungültig, antwortet SynCore mit 401. Fehlt der Scope, kommt 403 mit der Meldung API-Key fehlt Scope: ….
• Pro Schlüssel sind 1.200 Anfragen pro Minute erlaubt. Endpunkte, die Mails auslösen, zählen strenger und pro IP-Adresse: 30 pro Minute für den Mailversand, 10 pro Minute für die Newsletter-Anmeldung. Darüber kommt 429 mit dem Header Retry-After.

Übersicht

Newsletter-Anmeldung von deiner Website

Dein Formular schickt die Anmeldung an deinen eigenen Server, und der ruft SynCore mit dem Schlüssel auf. Der Schlüssel gehört nie in den Browser.

{
  "email": "anna@example.com",
  "name": "Anna Beispiel",
  "company": "Beispiel GmbH",
  "quelle": "Website Fußzeile"
}

• Pflicht ist nur email. name, company und quelle sind freiwillig.
• SynCore verschickt eine Bestätigungsmail (Double-Opt-in). Pro Adresse geht höchstens eine Bestätigungsmail in 24 Stunden raus.
• Ist die Adresse noch nicht im CRM, legt SynCore Konto und Kontakt erst an, wenn die Person den Link in der Bestätigungsmail anklickt. Unbestätigte Adressen speichert SynCore nicht.
• Die Antwort ist immer { "ok": true }, auch wenn die Adresse schon bekannt ist. So kann niemand über das Formular herausfinden, wer im CRM steht.
• Schickst du das Feld website mit einem Wert mit, behandelt SynCore die Anfrage als Bot und speichert nichts. Das Feld eignet sich als unsichtbare Falle in deinem Formular.

Kontakte aus Formularen ins CRM

Der Endpunkt legt Konto und Kontakt an oder hängt einen Kontakt an ein bestehendes Konto. Er arbeitet in drei Schritten, die du über mode wählst:

{
  "mode": "commit",
  "konto": { "name": "Beispiel GmbH", "email": "info@beispiel.de" },
  "kontakt": { "vorname": "Anna", "nachname": "Beispiel", "email": "anna@beispiel.de" },
  "nachricht": "Bitte um Rückruf wegen einer Demo.",
  "source": "Kontaktformular",
  "tags": ["website-lead"]
}

• Prüf vor dem Anlegen mit preview, ob es das Konto schon gibt. Gibt es einen Treffer, schickst du beim commit dessen kontoId mit.
• nachricht landet als Eintrag im Verlauf des Kontos. Mit tags gibst du einem neu angelegten Konto bis zu fünf Schlagworte mit.
• Legt SynCore ein neues Konto an, antwortet es mit 201, sonst mit 200. Die Antwort enthält kontoId, kontaktId und created.

Seminarbuchung aus einem Shop

Nach einer abgeschlossenen Bestellung meldet dein Shop die Buchung an SynCore.

{
  "veranstaltungId": "<ID der Veranstaltung>",
  "teilnehmer": { "personId": "<ID der Person>", "organisationId": "<ID des Kontos>", "gebuehrNetto": 490 },
  "belegErzeugen": true
}

• Pflicht ist veranstaltungId. Die Buchung bekommt den Teilnehmerstatus „angemeldet“.
• Mit belegErzeugen: true legt SynCore gleich den Beleg zur Anmeldung an.
• Die Antwort enthält buchungId und, falls erzeugt, belegId.

Mails über das Postfach des Mandanten

Für Partner-Apps, die im Namen des Mandanten Mails verschicken, zum Beispiel die Rettungsheft-App. SynCore verschickt über das Mailkonto, das im Mandanten eingerichtet ist.

{
  "to": "empfaenger@example.com",
  "toName": "Max Beispiel",
  "subject": "Deine Anmeldung",
  "text": "Hallo Max, deine Anmeldung ist eingegangen."
}

• Pflicht sind to, subject und entweder text oder html.
• Den Absender bestimmt immer SynCore. Ein Absenderfeld gibt es nicht, damit der Endpunkt kein offenes Mail-Relay wird.
• Jeder Versand steht im Mail-Protokoll und im Audit-Log.

Rollen und Rechte einrichten

Für Partner, die einen neuen Mandanten automatisch einrichten. Mit POST /api/admin/roles legst du eine Rolle an (label ist Pflicht, slug und description sind freiwillig). Mit PUT /api/admin/roles/{slug}/permissions setzt du ihre Rechte:

• { "seed": "defaults" } übernimmt die Standardrechte der Apps.
• { "grants": [{ "permissionKey": "…", "scope": "…" }] } setzt die Rechte ausdrücklich.

Administratorrollen und Administratorrechte lassen sich über diesen Weg nicht ändern.

Anbindungen, die United Synergy einrichtet

• Rettungsheft-App: Nachweise, Stundenplan, Anwesenheit per QR-Code und Kurse laufen über eigene Endpunkte. United Synergy richtet sie beim Einrichten der App ein, du musst dafür nichts programmieren.
• Externe Lern- und Praxisplattformen: Rückmeldungen von Lernergebnissen und Praxisdurchgängen richtet United Synergy mit dem jeweiligen Anbieter ein.
• Betrieb der Plattform: Schnittstellen für Updates, Lizenzen und Sicherheitsmeldungen nutzt nur United Synergy. Sie stehen deshalb nicht in dieser Hilfe.