Zum Hauptinhalt springen

Die alfima API nutzen: Kontakte & Produktzugänge per REST-API

So verbindest du externe Tools (Zapier, n8n, Make) mit alfima: API-Key erstellen, authentifizieren und per REST-API Kontakte, Produkte, Links, Newsletter, Verkäufe und mehr verwalten.

F
Verfasst von Finn Korte

Über die alfima REST-API kannst du externe Tools wie Zapier, n8n oder Make mit alfima verbinden und automatisiert mit deinem Konto arbeiten: Kontakte anlegen, Produktzugänge vergeben, Produkte und Links pflegen, Newsletter vorbereiten, Verkäufe auslesen und mehr.

Du arbeitest mit Claude Code? Dann verbinde alfima statt über die REST-API lieber direkt über unseren MCP-Server — das ist deutlich komfortabler.

Voraussetzungen

  • Ein alfima-Account mit aktivem Abo (bzw. laufender Testphase)

  • Ein API-Key (siehe nächster Abschnitt)

  • Grundverständnis von HTTP-Requests (dein Automations-Tool übernimmt das meiste)

API-Key erstellen

  1. Logge dich bei alfima ein.

  2. Gehe zu Einstellungen → API-Keys.

  3. Klicke auf API-Key erstellen, vergib einen Namen (z. B. „Zapier Integration") und optional ein Ablaufdatum.

  4. Wähle das Zugriffslevel:

    • Full access – darf lesen und schreiben (anlegen, ändern, löschen).

    • Read-only – darf ausschließlich lesen. Jeder Schreibversuch wird mit 403 abgelehnt. Nimm das, wenn dein Tool nur Daten abholen soll.

  5. Wichtig: Der Key wird nur einmalig angezeigt. Kopiere ihn sofort und bewahre ihn sicher auf. Geht er verloren, erstelle einen neuen oder nutze „Rotieren".

Du kannst bis zu 10 Keys gleichzeitig haben. Rotieren erzeugt einen neuen Key und macht den alten sofort ungültig, Widerrufen löscht ihn.

Authentifizierung

Sende deinen API-Key bei jeder Anfrage im Authorization-Header als Bearer-Token:

Authorization: Bearer alf_dein_api_key_hier

Alle API-Keys beginnen mit dem Präfix alf_.

Base-URL

https://app.alfima.com/api/v1/

Alle Endpunkte unten sind relativ zu dieser Base-URL.

Rate-Limits

  • 300 Anfragen pro Minute pro API-Key über alle Endpunkte hinweg.

  • POST /grants: zusätzlich 20 pro Minute – jeder Grant kann eine E-Mail auslösen.

  • KI-Produktbild erzeugen: zusätzlich 10 pro Minute.

Die engeren Limits gelten zusätzlich zum allgemeinen Limit – es greift immer das strengere. Wird ein Limit überschritten, antwortet die API mit 429.

Antwortformat

Erfolgreiche Antworten enthalten immer ein data- und ein meta-Objekt:

{   "data": { … },   "meta": { "request_id": "01J8…" } }

Bei Listen kommt in meta zusätzlich die Seiteninfo dazu:

{   "data": [ … ],   "meta": {     "pagination": { "page": 1, "per_page": 50, "total": 137 },     "request_id": "01J8…"   } }

Listen liefern standardmäßig 50 Einträge; mit den Query-Parametern per_page (max. 100) und page blätterst du durch. Die request_id hilft unserem Support bei der Fehlersuche – schick sie einfach mit.

Fehlerformat

Fehler kommen im Standardformat „Problem Details" (Content-Type: application/problem+json):

{   "type": "https://app.alfima.com/problems/validation-error",   "title": "Validation failed",   "status": 422,   "detail": "One or more fields are invalid.",   "code": "VALIDATION_ERROR",   "request_id": "01J8…",   "errors": { "email": ["The email field is required."] } }

Die für dich wichtigen Felder sind code (maschinenlesbar) und detail (Klartext). errors gibt es nur bei Validierungsfehlern. Wichtig: Prüfe in deinem Tool auf detail, nicht auf ein message-Feld – ein solches gibt es nicht.

Endpunkte im Überblick

Die drei am häufigsten genutzten Endpunkte sind weiter unten ausführlich beschrieben:

  • GET /products – Produkte auflisten (um die product_id zu finden)

  • POST /contacts – Kontakt anlegen oder aktualisieren (Upsert per E-Mail)

  • POST /grants – einem Kontakt Zugang zu einem Produkt gewähren

Darüber hinaus deckt die API inzwischen fast dein ganzes Konto ab:

  • Kontakte: GET/POST /contacts sowie GET/PUT/DELETE /contacts/{id}

  • Produkte: GET/POST /products, GET/PUT /products/{id}, Produktbild setzen oder per KI erzeugen

  • Kursinhalte: Module und (Text-)Lektionen unter /products/{id}/modules anlegen, ändern, löschen

  • Links: /links – auflisten, anlegen, ändern, löschen

  • Seiten: /pages – auflisten, HTML importieren, löschen

  • Newsletter (Pro für Schreibzugriff): /newsletters – Entwürfe verwalten, senden, abbrechen

  • Automationen (Pro für Schreibzugriff): /automations – inkl. Schritte, Aktivierung und Statistiken

  • Instagram-Auto-DMs (Pro für Schreibzugriff): /instagram/auto-dms

  • Verkäufe: /transactions (nur lesend) und CSV-Exporte unter /transactions/exports

  • Analytics: /analytics/revenue, /analytics/views, /analytics/conversion

  • Termin-Verfügbarkeiten: /availability – Buchungszeiten lesen und setzen

  • Einstellungen: /tax-settings (Rechnungsadresse, Steuern) und /legal-texts (Impressum, AGB, Datenschutz)

  • Uploads: POST /uploads – Datei hochladen und die zurückgegebene file_id an einem Produkt verwenden

Alle Endpunkte folgen denselben Regeln: Bearer-Token, data/meta im Erfolgsfall, Problem-Details im Fehlerfall. Du brauchst Details zu einem Bereich, der hier nicht ausgeschrieben ist? Melde dich beim Support – wir schicken dir die passenden Felder.

Anfragen aus No-Code-Tools senden (Zapier, Make, n8n)

Alle gängigen Automations-Tools haben ein generisches „HTTP-Request"-Modul:

  • Zapier: App „Webhooks by Zapier" → Aktion „Custom Request" (benötigt einen bezahlten Zapier-Plan)

  • Make: Modul „HTTP" → „Make a request"

  • n8n: Node „HTTP Request"

Egal welches Tool – du füllst immer dieselben vier Dinge aus:

  • Methode: GET (Daten abrufen) oder POST (Daten senden) – steht bei jedem Endpunkt dabei.

  • URL: Base-URL + Endpunkt, z. B. https://app.alfima.com/api/v1/contacts

  • Header: Authorization mit dem Wert Bearer alf_dein_api_key_hier. Bei POST zusätzlich Content-Type mit dem Wert application/json (manche Tools setzen das automatisch, sobald du JSON als Body-Typ wählst).

  • Body (nur bei POST): JSON mit den Feldern des jeweiligen Endpunkts.

Tipp – dynamische Werte: Felder wie email oder product_id kannst du aus dem vorherigen Schritt deines Workflows übernehmen, statt sie fest einzutragen.

GET /products

Listet deine Produkte auf. Nützlich, um die product_id für einen Grant zu finden. Unterstützt page und per_page (Standard 50, max. 100).

Anfrage:

GET https://app.alfima.com/api/v1/products Authorization: Bearer alf_dein_api_key_hier

Antwort (200):

{   "data": [     {       "id": 123,       "name": "Mein Onlinekurs",       "price": 49.90,       "type": "course_product",       "productable_type": "course_product",       "created_at": "2026-06-20T10:00:00+00:00"     }   ],   "meta": {     "pagination": { "page": 1, "per_page": 50, "total": 1 },     "request_id": "01J8…"   } }

Ein einzelnes Produkt holst du dir mit GET /products/{id} – die Antwort enthält dann alle Details inklusive Beschreibung, Bild-URL, Ratenplänen und wiederkehrenden Preisen.

POST /contacts

Legt einen Kontakt an oder aktualisiert ihn. Der Abgleich erfolgt über die E-Mail-Adresse (Upsert). Existiert bereits ein Kontakt mit dieser E-Mail, wird er aktualisiert.

Felder (nur email ist Pflicht):

  • email – gültige E-Mail-Adresse (max. 255)

  • first_name, last_name – Vor- und Nachname (je max. 255)

  • phone_number – Telefonnummer (max. 50)

  • type – private oder business

  • company_name – Firmenname (max. 255)

  • address_line_1, address_line_2 – Adresszeilen (je max. 255)

  • address_city, address_state – Stadt / Bundesland (je max. 100)

  • address_postal_code – Postleitzahl (max. 20)

  • address_country – 2-stelliger Ländercode, z. B. DE

  • vat_number – USt-IdNr. (max. 50)

  • double_opt_in – true/false, setzt den Double-Opt-in-Zeitpunkt

  • list_ids – Array von Listen-IDs, denen der Kontakt hinzugefügt wird (müssen dir gehören)

Anfrage:

POST https://app.alfima.com/api/v1/contacts Authorization: Bearer alf_dein_api_key_hier Content-Type: application/json  {   "email": "[email protected]",   "first_name": "Max",   "last_name": "Mustermann",   "double_opt_in": true,   "list_ids": [12] }

Antwort: Statuscode 201, wenn der Kontakt neu angelegt wurde, und 200, wenn ein vorhandener aktualisiert wurde. Am Statuscode – nicht am Inhalt – erkennst du, welcher Fall eingetreten ist.

{   "data": {     "id": 456,     "email": "[email protected]",     "name": "Max Mustermann",     "type": "private",     "double_opt_in_at": "2026-06-20T10:00:00+00:00",     "created_at": "2026-06-20T10:00:00+00:00",     "updated_at": "2026-06-20T10:00:00+00:00"   } }

Hinweis: Ein als business markierter Kontakt wird nicht automatisch auf private zurückgestuft – der in alfima gespeicherte Stand bleibt führend.

POST /grants

Gewährt einem Kontakt Zugang zu einem deiner Produkte (entspricht einer manuellen, kostenlosen Freigabe). Existiert der Kontakt noch nicht, wird er anhand der E-Mail angelegt.

Felder:

  • email (Pflicht) – E-Mail des Kontakts (max. 255)

  • product_id (Pflicht) – ID eines deiner Produkte (siehe GET /products)

  • first_name, last_name – werden nur gesetzt, wenn beim Kontakt noch nichts hinterlegt ist; vorhandene Werte bleiben unangetastet

  • send_access_email – true/false, Zugangs-E-Mail an den Kontakt senden. Standard: false.

Anfrage:

POST https://app.alfima.com/api/v1/grants Authorization: Bearer alf_dein_api_key_hier Content-Type: application/json  {   "email": "[email protected]",   "product_id": 123,   "send_access_email": true }

Antwort (201):

{   "data": {     "purchase_id": 789,     "customer_id": 456,     "product_id": 123,     "access_expires_at": null,     "access_email_sent": true   },   "meta": { "request_id": "01J8…" } }

  • Hat der Kontakt bereits Zugang zu diesem Produkt, antwortet die API mit 409.

  • Gehört das Produkt nicht zu deinem Konto, antwortet die API mit 422.

  • Beachte das engere Limit von 20 Anfragen pro Minute für diesen Endpunkt.

Fehler-Codes

  • 401 · UNAUTHENTICATED – kein, ungültiger oder abgelaufener API-Key

  • 403 · FORBIDDEN – Abo inaktiv, oder du hast mit einem Read-only-Key zu schreiben versucht. Der genaue Grund steht in detail.

  • 404 · NOT_FOUND – Ressource nicht gefunden (oder sie gehört nicht zu deinem Konto)

  • 409 · CONFLICT – Konflikt, z. B. Kontakt hat bereits Produktzugang

  • 422 · VALIDATION_ERROR – Validierungsfehler, Details im errors-Objekt

  • 429 · TOO_MANY_REQUESTS – Rate-Limit überschritten, kurz warten und erneut versuchen

  • 500 · INTERNAL_ERROR – unerwarteter Fehler bei uns; schick uns die request_id

Bei Fragen oder Problemen: kontaktiere den alfima-Support – wir helfen dir gern bei der Einrichtung.

Verwandte Artikel
Hat dies deine Frage beantwortet?