Kom i gang med REST API'et

Med Scratchers REST API kan dine egne systemer læse dine kampagner, leads og lister, tilføje og opdatere leads og administrere produkter og placeringer. Denne artikel er til den udvikler, der sætter det op.

API'et indgår i de abonnementer, der har Webhooks og API (Basic og opefter). På andre abonnementer er knapperne til at oprette tokens og apps låst.

Opret et personligt adgangstoken

Et personligt adgangstoken er den hurtigste måde at kalde API'et på fra dine egne scripts og systemer.

1. Gå til Indstillinger > API (under Udviklere).
2. Under Personlige adgangstokens klikker du på Opret personligt adgangstoken. Dialogen siger "Generér et token til at godkende API-anmodninger."
3. Giv det et Navn, du kan genkende senere, fx "Datawarehouse".
4. Under Scopes vælger du, hvad tokenet må (se nedenfor). Vælg alle vælger alle scopes. Giv kun tokenet den adgang, det har brug for.
5. Klik på Gem. Du ser "Dit adgangstoken er oprettet".
6. Kopiér tokenet under Secret. "Gem secret ovenfor, da det er eneste gang, du kan se det." Opbevar det sikkert, fx i en adgangskodeadministrator.
7. Klik på Luk.

Et token hører til din bruger. Det kan nå alle de Scratcher-konti, du er medlem af, med de scopes, du har valgt.

Scopes

• read:campaigns (Se kampagner): vis og læs kampagner
• read:lists (Se lister): vis og læs leadlister
• read:leads (Se leads): læs leads
• write:leads (Redigér leads): opret, opdatér og slet leads på en liste
• read:placements (Se placeringer): læs placeringer
• write:placements (Redigér placeringer): opret, opdatér og slet placeringer
• read:products (Se produkter): læs produkter
• write:products (Redigér produkter): opret, opdatér og slet produkter

For at læse en kampagnes leads skal tokenet have både read:campaigns og read:leads. Oprettelse og ændring af placeringer kræver også Embed / URL i dit abonnement.

Tilbagekald et token

Klik på tokenet på listen for at åbne Vis personligt adgangstoken. Her ser du Navn og Scopes. Klik på Tilbagekald, og bekræft ("Er du sikker på, at du vil slette dette token? Det kan ikke fortrydes!"). Alt, der bruger tokenet, holder op med at virke med det samme.

Lav en forespørgsel

Basis-URL'en er https://platform.scratcher.io/api/v1/. Send tokenet i headeren Authorization, og bed om JSON:

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

De vigtigste endpoints

• GET /me: den bruger, tokenet hører til
• GET /accounts: de konti, du har adgang til. Brug kontoens id i de andre kald.
• GET /accounts/{account}/campaigns og /campaigns/{campaign}: dine kampagner
• GET /accounts/{account}/campaigns/{campaign}/leads: en kampagnes leads, nyeste først, med deres felter, accepterede samtykker og, for vindere, præmien og koden
• GET /accounts/{account}/lists og /lists/{list}: dine leadlister
• /accounts/{account}/lists/{list}/leads: en listes leads. GET for at læse, POST for at oprette, PUT for at opdatere og DELETE for at slette. Et lead har en email, et phone_number og et valgfrit custom_token.
• /accounts/{account}/products: produkter (GET, POST, PUT, DELETE)
• /accounts/{account}/placements: placeringer (GET, POST, PUT, DELETE)

Lister er opdelt i sider: tilføj ?page=2 og så videre. Du kan kun nå konti, du er medlem af; andre konto-id'er giver en fejl.

Begrænsninger

Du kan lave 60 forespørgsler i minuttet pr. bruger. Går du over, svarer API'et med status 429; vent et øjeblik, og prøv igen.

API-reference

Den fulde reference med alle felter, filtre, eksempler og en Postman-samling finder du i API-referencedokumentationen. Knappen API-reference øverst på Indstillinger > API linker også dertil.

Byg en app med OAuth

Bygger du en app, som andre Scratcher-brugere forbinder med deres egen konto, så registrér en OAuth-app i stedet for at bruge et personligt token.

1. Gå til Indstillinger > API. Under Mine apps klikker du på Opret app ("Registrér en OAuth-applikation til API'et.").
2. Udfyld Programnavn (brugerne ser det, når de godkender din app) og Omdirigerings-URI (hvor brugerne bliver sendt tilbage til, når de har godkendt).
3. Klik på Gem. Du ser "Din app er oprettet!" med Client ID og Client secret.
4. Kopiér dit client secret nu: "Gem client secret ovenfor, da det er eneste gang, du kan se det." Klik på Fortsæt.

Din app sender brugerne til https://platform.scratcher.io/oauth/authorize med dit client ID, din redirect URI og de scopes, den skal bruge. Brugeren logger ind i Scratcher og ser en Anmodning om autorisation: "Denne applikation vil kunne:" efterfulgt af dine scopes. Brugeren klikker på Autorisér eller Annullér. Din app bytter derefter koden til tokens på https://platform.scratcher.io/oauth/token.

• Adgangstokens fra OAuth holder i to måneder. Refresh tokens holder i tre måneder; brug dem til at få et nyt adgangstoken.
• Vil du ændre navnet eller redirect URI'en, så klik på appen under Mine apps, ret det, og klik på Gem ("Dine indstillinger er gemt"). "Du kan ikke se dit secret bagefter."
• Slet app fjerner appen, og alle brugeres forbindelse til den holder op med at virke: "Er du sikker på, at du vil slette denne app? Det kan ikke fortrydes!"

Apps, du har godkendt

Autoriserede apps viser de apps, du har givet adgang til din konto, fx Zapier, med de scopes, de har. Klik på Tilbagekald for at fjerne adgangen.

Hvem kan bruge API'et?

Siden API bliver vist for brugere med rollen Ejer, Admin eller Leder. Et token kan aldrig mere end den bruger, der har oprettet det.