Preskoči na vsebino
Rex, vaš pomočnik UI: rutinsko delo opravi on, ideje so vaše 👉 Spoznajte Rexa

Začetek dela z REST API

Ustvarite osebni dostopni žeton z ustreznimi obsegi ali registrirajte aplikacijo OAuth ter berite kampanje, leade in sezname iz svojih sistemov.

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.

  1. Odprite Settings > API (pod Developers).
  2. Pod Personal access tokens kliknite Create personal access token. V pogovornem oknu piše »Generate a token to authenticate API requests.«
  3. Vnesite Name, ki ga boste pozneje prepoznali, npr. »Podatkovno skladišče«.
  4. Pod Scopes izberite, kaj sme žeton početi (glejte spodaj). Select all izbere vse obsege. Žetonu dodelite le dostop, ki ga potrebuje.
  5. Kliknite Save. Prikaže se »Your access token has been created«.
  6. 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.
  7. 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 kampanj
  • read:lists (View lists): prikaz in branje seznamov leadov
  • read:leads (View leads): branje leadov
  • write:leads (Write leads): ustvarjanje, posodabljanje in brisanje leadov na seznamu
  • read:placements (View placements): branje umestitev
  • write:placements (Write placements): ustvarjanje, posodabljanje in brisanje umestitev
  • read:products (View products): branje izdelkov
  • write: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 pripada
  • GET /accounts: računi, do katerih imate dostop. ID računa uporabite v drugih klicih.
  • GET /accounts/{account}/campaigns in /campaigns/{campaign}: vaše kampanje
  • GET /accounts/{account}/campaigns/{campaign}/leads: leadi kampanje, od najnovejših naprej, z njihovimi polji, sprejetimi privolitvami in pri zmagovalcih z nagrado in kodo
  • GET /accounts/{account}/lists in /lists/{list}: vaši seznami leadov
  • /accounts/{account}/lists/{list}/leads: leadi seznama. GET za branje, POST za ustvarjanje, PUT za posodabljanje in DELETE za brisanje. Lead ima email, phone_number in neobvezen custom_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.

  1. Odprite Settings > API. Pod My apps kliknite Create app (»Register an OAuth application for the API.«).
  2. Izpolnite Application name (uporabniki ga vidijo, ko odobrijo vašo aplikacijo) in Redirect URI (kamor so uporabniki preusmerjeni po odobritvi).
  3. Kliknite Save. Prikaže se »Your app has been created!« s Client ID in Client secret.
  4. 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.

Potrebujete pomoč?

Še vedno potrebujete pomoč?

Pravi ljudje so tu, da vam pomagajo. Če Scratcher že uporabljate, je najhitrejša pot klepet v platformi.

  • Klepetajte z nami

    Prijavite se in kliknite gumb za klepet v spodnjem desnem kotu. Rex odgovori takoj, naša ekipa pa je le en klik stran.

  • Rezervirajte sestanek

    Brezplačen 30-minutni videoklic z našo ekipo: predstavitev, ideje za kampanje ali pomoč pri nastavitvi.

  • Pišite nam

    Pišite na contact@scratcher.io in odgovorili vam bomo.