Zum Inhalt springen

colly startet bald. Wir legen gerade letzte Hand an – schau dich gern schon um. Registrierung und Anmeldung für Creator und Marken öffnen in Kürze.

Suche wird geladen …

    API-Schlüssel

    Schlüssel erstellen, die einmalige Anzeige richtig nutzen, Schlüssel widerrufen und die Unterschiede zwischen Advertiser und Creator.

    Ein API-Schlüssel ist der Ausweis deines Systems bei colly. Er besteht aus zwei Teilen: der öffentlichen Key-ID (pk_…) und dem geheimen Secret (sk_…). Beide zusammen, durch einen Punkt verbunden, ergeben das API-Token. Mit dem Token greift dein System auf die REST-API zu, also die Programmierschnittstelle von colly.

    Schlüssel gehören immer zu deiner Organisation, nicht zu einer Person. Du findest sie unter Integration: als Advertiser im Reiter Postback & API, als Creator direkt oben auf der Seite.

    Unterschied zwischen Advertiser und Creator

    MerkmalAdvertiserCreator (Affiliate)
    WofürREST-API und signierte Postbacks, also auch die Plugins für WooCommerce und ShopwareNur REST-API
    Was die API erlaubtEigene Angebote, Conversions und PartnerAngebote, Trackinglinks, Conversions, Guthaben und Statistiken
    Einmalige AnzeigeAPI-Token (REST-API) und unter Für signierte Postbacks auch Key-ID und SecretNur API-Token (REST-API)
    Postback sendenJaNein, Antwort key_not_allowed
    Rest der SeiteAlle ReiterNur API-Schlüssel und REST-API, keine Reiter
    Seite Integration aus Sicht eines Creators ohne Schlüssel
    So sieht die Seite für einen Creator aus: kein Reiter und kein Protokoll. Ohne Schlüssel steht in der Liste Noch keine Schlüssel.
    1. Markierung 1: Bezeichnung: ein Name für den Schlüssel, zum Beispiel der Server, der ihn nutzt.
    2. Markierung 2: Schlüssel erstellen legt den Schlüssel an und öffnet einmalig das Fenster mit dem API-Token.

    In einem Team dürfen nur Eigentümer:in und Admin Schlüssel erstellen und widerrufen. Andere sehen die Liste, erhalten beim Absenden aber die Meldung: Deine Team-Rolle erlaubt diese Aktion nicht. Wende dich an die Admins deines Teams.

    Schlüssel erstellen

    Abschnitt API-Schlüssel eines Advertisers mit einem aktiven Schlüssel
    1. Markierung 1: Bezeichnung: Pflichtfeld mit 2 bis 60 Zeichen. Sie hilft dir später, den Schlüssel wiederzuerkennen.
    2. Markierung 2: Schlüssel erstellen legt sofort einen aktiven Schlüssel an und öffnet das Fenster Neuer Schlüssel.
    3. Markierung 3: Widerrufen öffnet eine Sicherheitsabfrage. Siehe Schlüssel widerrufen.

    1. Schritt 1: Bezeichnung eingeben und erstellen

      Gib eine Bezeichnung ein und klicke auf Schlüssel erstellen. Es erscheint Schlüssel erstellt.

    2. Schritt 2: Fenster Neuer Schlüssel: Daten sichern

      Das Fenster Neuer Schlüssel zeigt deine Zugangsdaten mit je einem Knopf zum Kopieren. Speichere sie an einem sicheren Ort, zum Beispiel in den Umgebungsvariablen deines Servers oder einem Passwortmanager.

      • API-Token (REST-API): für den Header Authorization: Bearer ….
      • Key-ID und Secret: nur als Advertiser, unter Für signierte Postbacks. Diese Werte trägst du auch in die Plugins ein.
      Fenster Neuer Schlüssel mit API-Token, Key-ID und Secret
      Im Bild sind die Werte gekürzt. Bei dir stehen sie vollständig da.
      1. Markierung 1: API-Token (REST-API): Key-ID und Secret, durch einen Punkt verbunden.
      2. Markierung 2: Key-ID: der öffentliche Teil.
      3. Markierung 3: Secret: der geheime Teil. Er wird nie wieder angezeigt.
      4. Markierung 4: Ich habe das Secret gespeichert schließt das Fenster.

    3. Schritt 3: Fenster schließen

      Klicke auf Ich habe das Secret gespeichert. Danach siehst du in der Liste nur noch die Key-ID.

    Die Liste der Schlüssel

    SpalteBedeutung
    BezeichnungDer Name, den du vergeben hast. Er lässt sich nicht ändern.
    Key-IDDer öffentliche Teil. Er steht auch in der Testkonsole.
    StatusAktiv oder Deaktiviert (widerrufen).
    ErstelltDatum und Uhrzeit der Erstellung.
    Zuletzt genutztLetzte Nutzung durch einen Postback oder die REST-API. Bei der REST-API aktualisiert colly das höchstens einmal pro Minute. „–“ heißt: noch nie genutzt.
    Letzte SpalteKnopf Widerrufen. Bei widerrufenen Schlüsseln steht hier stattdessen das Datum des Widerrufs.

    Ein Klick auf eine Spaltenüberschrift mit Pfeilen sortiert die Liste. Widerrufene Schlüssel bleiben sichtbar. Es gibt kein Ablaufdatum: Ein Schlüssel gilt, bis du ihn widerrufst.

    Schlüssel widerrufen

    Sicherheitsabfrage beim Widerrufen
    1. Markierung 1: Widerrufen sperrt den Schlüssel sofort. Abbrechen schließt nur das Fenster.
    Liste der Schlüssel mit einem frisch widerrufenen Schlüssel
    Nach dem Bestätigen lädt die Liste neu, und kurz erscheint eine Bestätigung.
    1. Markierung 1: Der Status wechselt auf Deaktiviert.
    2. Markierung 2: Statt des Knopfs steht hier jetzt das Datum des Widerrufs.
    • API-Aufrufe und Postbacks mit diesem Schlüssel werden sofort abgelehnt. Bei Postbacks lautet der Code unknown_key.
    • Das lässt sich nicht rückgängig machen. Der Eintrag bleibt mit dem Status Deaktiviert in der Liste.
    • In der Testkonsole steht ein widerrufener Schlüssel nicht mehr zur Wahl.
    • Webhooks von Shopify und Zahlungsanbietern betrifft das nicht. Sie haben eigene Schlüssel in ihrer Anbindung.

    Die REST-API nutzen

    Sende das API-Token im Header Authorization: Bearer …. Der Schlüssel sieht genau die Daten deiner Organisation, mit denselben Rechten wie im Dashboard. Schreibende Aufrufe werden im Audit-Log mit dem Schlüssel protokolliert.

    Abschnitt REST-API mit Links und erster Anfrage
    1. Markierung 1: Vollständige API-Dokumentation öffnet die Entwicklerseite.
    2. Markierung 2: OpenAPI-Beschreibung (JSON) öffnet die Beschreibung der Schnittstelle zum Einlesen in Werkzeuge.

    Erste Anfrage zeigt ein Beispiel, das du mit Kopieren übernimmst. Das Limit liegt bei 600 Anfragen pro 60 Sekunden je Schlüssel. Als Creator sieht das Beispiel etwas anders aus, weil es Trackinglinks statt Conversions abruft:

    Abschnitt REST-API aus Sicht eines Creators
    1. Markierung 1: Vollständige API-Dokumentation öffnet die Entwicklerseite. Dort steht, welche Endpunkte dein Schlüsseltyp nutzen darf.

    Häufige Probleme

    Was du siehstUrsacheLösung
    Secret verlorenEs wird nur einmal angezeigt.Neuen Schlüssel erstellen, alten widerrufen.
    invalid_signature bei PostbacksSecret falsch oder nicht zum gesendeten Text passend signiert.Exakt den gesendeten Text signieren. Siehe Signierter Postback.
    key_not_allowed bei PostbacksDer Schlüssel gehört zu einem Creator-Konto.Schlüssel im Advertiser-Konto erstellen.
    Zuletzt genutzt bleibt leerNoch keine gültige Anfrage kam an.Key-ID, Secret und Adresse prüfen.