REST API Scratcher vašim sistemom omogoča branje kampanj, leadov in seznamov, dodajanje in posodabljanje leadov ter upravljanje izdelkov in umestitev. Ta članek je namenjen razvijalcu, ki ga nastavi.
API je vključen v pakete, ki vsebujejo Webhooks & API (Basic in višje). V drugih paketih so gumbi za ustvarjanje žetonov in aplikacij zaklenjeni.
Ustvarite osebni dostopni žeton
Osebni dostopni žeton je najhitrejši način za klicanje API-ja iz lastnih skript in sistemov.
- Odprite Settings > API (pod Developers).
- Pod Personal access tokens kliknite Create personal access token. V pogovornem oknu piše »Generate a token to authenticate API requests.«
- Vnesite Name, ki ga boste pozneje prepoznali, npr. »Podatkovno skladišče«.
- Pod Scopes izberite, kaj sme žeton početi (glejte spodaj). Select all izbere vse obsege. Žetonu dodelite le dostop, ki ga potrebuje.
- Kliknite Save. Prikaže se »Your access token has been created«.
- Kopirajte žeton pod Secret. »Save the secret above, as this is the only time you will see it.« Shranite ga na varno, na primer v upravitelj gesel.
- Kliknite Close.
Žeton pripada vašemu uporabniku. Z izbranimi obsegi lahko dostopa do vseh računov Scratcher, katerih član ste.
Obsegi
read:campaigns(View campaigns): prikaz in branje kampanjread:lists(View lists): prikaz in branje seznamov leadovread:leads(View leads): branje leadovwrite:leads(Write leads): ustvarjanje, posodabljanje in brisanje leadov na seznamuread:placements(View placements): branje umestitevwrite:placements(Write placements): ustvarjanje, posodabljanje in brisanje umestitevread:products(View products): branje izdelkovwrite:products(Write products): ustvarjanje, posodabljanje in brisanje izdelkov
Za branje leadov kampanje žeton potrebuje tako read:campaigns kot read:leads. Za ustvarjanje in spreminjanje umestitev mora vaš paket vključevati tudi Embed / URL.
Prekličite žeton
Kliknite žeton na seznamu, da odprete Show personal access token. Prikazana sta Name in Scopes. Kliknite Revoke in potrdite (»Are you sure you want to delete this token? This cannot be undone!«). Vse, kar uporablja žeton, takoj preneha delovati.
Pošljite zahtevo
Osnovni URL je https://platform.scratcher.io/api/v1/. Žeton pošljite v glavi Authorization in zahtevajte JSON:
curl https://platform.scratcher.io/api/v1/accounts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" Glavne končne točke
GET /me: uporabnik, ki mu žeton pripadaGET /accounts: računi, do katerih imate dostop. ID računa uporabite v drugih klicih.GET /accounts/{account}/campaignsin/campaigns/{campaign}: vaše kampanjeGET /accounts/{account}/campaigns/{campaign}/leads: leadi kampanje, od najnovejših naprej, z njihovimi polji, sprejetimi privolitvami in pri zmagovalcih z nagrado in kodoGET /accounts/{account}/listsin/lists/{list}: vaši seznami leadov/accounts/{account}/lists/{list}/leads: leadi seznama.GETza branje,POSTza ustvarjanje,PUTza posodabljanje inDELETEza brisanje. Lead imaemail,phone_numberin neobvezencustom_token./accounts/{account}/products: izdelki (GET,POST,PUT,DELETE)/accounts/{account}/placements: umestitve (GET,POST,PUT,DELETE)
Seznami so razdeljeni na strani: dodajte ?page=2 in tako naprej. Dostopate lahko le do računov, katerih član ste; drugi ID-ji računov vrnejo napako.
Omejitve
Na uporabnika lahko pošljete 60 zahtev na minuto. Če omejitev presežete, API odgovori s statusom 429; počakajte trenutek in poskusite znova.
Referenca API
Celotna referenca z vsemi polji, filtri, primeri in zbirko Postman je na voljo v referenčni dokumentaciji API. Nanjo vodi tudi gumb API reference na vrhu strani Settings > API.
Izdelajte aplikacijo z OAuth
Če izdelujete aplikacijo, ki jo drugi uporabniki Scratcherja povežejo s svojim računom, namesto osebnega žetona registrirajte aplikacijo OAuth.
- Odprite Settings > API. Pod My apps kliknite Create app (»Register an OAuth application for the API.«).
- Izpolnite Application name (uporabniki ga vidijo, ko odobrijo vašo aplikacijo) in Redirect URI (kamor so uporabniki preusmerjeni po odobritvi).
- Kliknite Save. Prikaže se »Your app has been created!« s Client ID in Client secret.
- Skrivnost odjemalca kopirajte zdaj: »Save the client secret above, as this is the only time you will see it.« Kliknite Continue.
Vaša aplikacija uporabnike pošlje na https://platform.scratcher.io/oauth/authorize z vašim ID-jem odjemalca, URI-jem za preusmeritev in potrebnimi obsegi. Uporabnik se prijavi v Scratcher in vidi Authorization request: »This application will be able to:«, ki mu sledijo obsegi. Klikne Authorize ali Cancel. Vaša aplikacija nato kodo zamenja za žetone na https://platform.scratcher.io/oauth/token.
- Dostopni žetoni OAuth veljajo dva meseca. Žetoni za osvežitev veljajo tri mesece; z njimi pridobite nov dostopni žeton.
- Za spremembo imena ali URI-ja za preusmeritev kliknite aplikacijo pod My apps, ju spremenite in kliknite Save (»Your settings have been saved«). »You cannot view your secret afterwards.«
- Delete app odstrani aplikacijo, povezave vseh uporabnikov z njo pa prenehajo delovati: »Are you sure you want to delete this app? This cannot be undone!«
Aplikacije, ki ste jih odobrili
Authorized apps prikazuje aplikacije, ki ste jim omogočili dostop do svojega računa, na primer Zapier, skupaj z njihovimi obsegi. Kliknite Revoke, da jim odvzamete dostop.
Kdo lahko uporablja API?
Stran API je prikazana uporabnikom z vlogo Owner, Admin ali Manager. Žeton nikoli ne more storiti več kot uporabnik, ki ga je ustvaril.