Erste Schritte mit der REST-API

Mit der REST-API von Scratcher können Ihre eigenen Systeme Ihre Kampagnen, Leads und Listen auslesen, Leads hinzufügen und aktualisieren sowie Produkte und Platzierungen verwalten. Dieser Artikel richtet sich an die Person, die die Anbindung technisch einrichtet.

Die API ist in den Plänen mit Webhooks & API enthalten (ab Basic). In anderen Plänen sind die Buttons zum Erstellen von Tokens und Apps gesperrt.

Ein persönliches Zugriffstoken erstellen

Ein persönliches Zugriffstoken ist der schnellste Weg, die API aus Ihren eigenen Skripten und Systemen aufzurufen.

1. Gehen Sie zu Einstellungen > API (unter Entwickler).
2. Klicken Sie unter Persönliche Zugriffstokens auf Persönliches Zugriffstoken erstellen. Im Dialog steht „Generieren Sie ein Token, um API-Anfragen zu authentifizieren.“
3. Geben Sie unter Name einen Namen ein, den Sie später wiedererkennen, etwa „Data Warehouse“.
4. Wählen Sie unter Berechtigungen, was das Token darf (siehe unten). Alle auswählen wählt alle Berechtigungen. Geben Sie dem Token nur den Zugriff, den es wirklich braucht.
5. Klicken Sie auf Speichern. Sie sehen „Ihr Zugriffstoken wurde erstellt“.
6. Kopieren Sie das Token unter Secret. „Speichern Sie das obige Secret, da Sie es nur dieses eine Mal sehen.“ Bewahren Sie es sicher auf, zum Beispiel in einem Passwortmanager.
7. Klicken Sie auf Schließen.

Ein Token gehört zu Ihrem Benutzer. Es kann mit den gewählten Berechtigungen auf jedes Scratcher-Konto zugreifen, in dem Sie Mitglied sind.

Berechtigungen (Scopes)

• read:campaigns (Kampagnen anzeigen): Kampagnen auflisten und lesen
• read:lists (Listen anzeigen): Lead-Listen auflisten und lesen
• read:leads (Leads anzeigen): Leads lesen
• write:leads (Leads bearbeiten): Leads in einer Liste erstellen, aktualisieren und löschen
• read:placements (Platzierungen anzeigen): Platzierungen lesen
• write:placements (Platzierungen bearbeiten): Platzierungen erstellen, aktualisieren und löschen
• read:products (Produkte anzeigen): Produkte lesen
• write:products (Produkte bearbeiten): Produkte erstellen, aktualisieren und löschen

Um die Leads einer Kampagne zu lesen, braucht das Token sowohl read:campaigns als auch read:leads. Zum Erstellen und Ändern von Platzierungen muss Ihr Plan außerdem Einbettung / URL enthalten.

Ein Token widerrufen

Klicken Sie in der Liste auf das Token, um Persönliches Zugriffstoken anzeigen zu öffnen. Dort sehen Sie Name und Berechtigungen. Klicken Sie auf Widerrufen und bestätigen Sie („Möchten Sie dieses Token wirklich löschen? Dies kann nicht rückgängig gemacht werden!“). Alles, was das Token nutzt, funktioniert sofort nicht mehr.

Eine Anfrage senden

Die Basis-URL lautet https://platform.scratcher.io/api/v1/. Senden Sie das Token im Header Authorization und fordern Sie JSON an:

curl https://platform.scratcher.io/api/v1/accounts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" 

Die wichtigsten Endpunkte

• GET /me: der Benutzer, zu dem das Token gehört
• GET /accounts: die Konten, auf die Sie Zugriff haben. Nutzen Sie die Konto-ID in den anderen Aufrufen.
• GET /accounts/{account}/campaigns und /campaigns/{campaign}: Ihre Kampagnen
• GET /accounts/{account}/campaigns/{campaign}/leads: die Leads einer Kampagne, die neuesten zuerst, mit ihren Feldern, erteilten Einwilligungen und bei Gewinnern mit Gewinn und Code
• GET /accounts/{account}/lists und /lists/{list}: Ihre Lead-Listen
• /accounts/{account}/lists/{list}/leads: die Leads einer Liste. GET zum Lesen, POST zum Erstellen, PUT zum Aktualisieren und DELETE zum Löschen. Ein Lead hat eine email, eine phone_number und optional ein custom_token.
• /accounts/{account}/products: Produkte (GET, POST, PUT, DELETE)
• /accounts/{account}/placements: Platzierungen (GET, POST, PUT, DELETE)

Listen sind in Seiten aufgeteilt: Hängen Sie ?page=2 usw. an. Sie erreichen nur Konten, in denen Sie Mitglied sind; andere Konto-IDs liefern einen Fehler.

Limits

Sie können 60 Anfragen pro Minute und Benutzer senden. Darüber antwortet die API mit dem Status 429; warten Sie einen Moment und versuchen Sie es erneut.

API-Referenz

Die vollständige Referenz mit allen Feldern, Filtern, Beispielen und einer Postman-Collection finden Sie in der API-Referenzdokumentation. Auch der Button API-Referenz oben unter Einstellungen > API verlinkt darauf.

Eine App mit OAuth bauen

Wenn Sie eine App bauen, die andere Scratcher-Nutzer mit ihrem eigenen Konto verbinden, registrieren Sie eine OAuth-App, statt ein persönliches Token zu verwenden.

1. Gehen Sie zu Einstellungen > API. Klicken Sie unter Meine Apps auf App erstellen („Registrieren Sie eine OAuth-Anwendung für die API.“).
2. Füllen Sie Name der Anwendung aus (Nutzer sehen ihn, wenn sie Ihre App genehmigen) sowie die Weiterleitungs-URI (wohin Nutzer nach der Genehmigung zurückgeleitet werden).
3. Klicken Sie auf Speichern. Sie sehen „Ihre App wurde erstellt!“ mit Client-ID und Client-Secret.
4. Kopieren Sie das Client-Secret jetzt: „Speichern Sie das obige Client-Secret, da Sie es nur dieses eine Mal sehen.“ Klicken Sie auf Weiter.

Ihre App leitet Nutzer mit Ihrer Client-ID, der Weiterleitungs-URI und den benötigten Berechtigungen an https://platform.scratcher.io/oauth/authorize weiter. Der Nutzer meldet sich bei Scratcher an und sieht eine Autorisierungsanfrage: „Diese Anwendung kann:“, gefolgt von den Berechtigungen. Er klickt auf Autorisieren oder Abbrechen. Ihre App tauscht den Code dann unter https://platform.scratcher.io/oauth/token gegen Tokens.

• Zugriffstokens aus OAuth gelten zwei Monate. Refresh-Tokens gelten drei Monate; mit ihnen holen Sie ein neues Zugriffstoken.
• Um den Namen oder die Weiterleitungs-URI zu ändern, klicken Sie unter Meine Apps auf die App, ändern Sie die Angaben und klicken Sie auf Speichern („Ihre Einstellungen wurden gespeichert“). „Sie können Ihr Secret danach nicht mehr einsehen.“
• App löschen entfernt die App, und die Verbindung aller Nutzer zu ihr funktioniert nicht mehr: „Möchten Sie diese App wirklich löschen? Dies kann nicht rückgängig gemacht werden!“

Apps, die Sie genehmigt haben

Autorisierte Apps zeigt die Apps, denen Sie Zugriff auf Ihr Konto gegeben haben, etwa Zapier, mit ihren Berechtigungen. Klicken Sie auf Widerrufen, um den Zugriff zu entziehen.

Wer kann die API nutzen?

Die Seite API sehen Benutzer mit der Rolle Inhaber, Admin oder Manager. Ein Token kann nie mehr als der Benutzer, der es erstellt hat.