# Spezialanbindungen neben den App-Tools

> Welche festen Schnittstellen SynCore für Website-Formulare, Shops, Partner-Apps und die Einrichtung von Rollen anbietet und wie du einen Schlüssel dafür bekommst.

Quelle: https://support.unitedsynergy.com/api/spezialanbindungen/

Fast alles, was du per API mit SynCore machst, läuft über die [App-Tools](https://support.unitedsynergy.com/api/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`.

> **Schlüssel bekommst du über United Synergy**
>
> In der Plattformadministration lassen sich nur App-Tools-Schlüssel erzeugen. Schlüssel für Spezialanbindungen stellt United Synergy aus, jeweils nur mit dem Scope, den die Anbindung braucht. Schreib uns über den [Support](https://support.unitedsynergy.com/support/), wofür du die Anbindung brauchst und welcher Benutzer als Actor-User dahinterstehen soll.

## Übersicht

| Anbindung | Endpunkt | Scope |
| --- | --- | --- |
| Newsletter-Anmeldung von deiner Website | `POST /api/newsletter/anmeldung` | `newsletter.anmeldung` |
| Kontakte aus Formularen ins CRM | `POST /api/crm/import` | `crm.import` |
| Seminarbuchung aus einem Shop | `POST /api/seminar/webhook/order` | `seminar:webhook` |
| Mails über das Postfach des Mandanten | `POST /api/mail/relay` | `mail.relay` |
| Rollen und Rechte einrichten | `POST /api/admin/roles`, `PUT /api/admin/roles/{slug}/permissions` | `iam:manage` |

## 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.

```json
{
  "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` | Was passiert | Nötiges Recht des Actor-Users |
| --- | --- | --- |
| `preview` (Standard) | Sucht mögliche Dubletten. Schreibt nichts. | Konto lesen |
| `search` | Sucht Konten per Freitext im Feld `search`. | Konto lesen |
| `commit` | Legt Konto und Kontakt an oder hängt den Kontakt an `kontoId`. | Konto anlegen |

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

> **Wenn eine Spezialanbindung scheitert**
>
> Prüf zuerst Scope und Actor-User des Schlüssels: `403` mit `API-Key fehlt Scope` heißt, dass der Schlüssel für einen anderen Zweck ausgestellt ist. Weitere Meldungen erklärt [Wenn eine API-Anfrage scheitert](https://support.unitedsynergy.com/api/fehlerbehebung/).