Scratcher REST API omogućuje vašim sustavima da čitaju vaše kampanje, leadove i popise, dodaju i ažuriraju leadove te upravljaju proizvodima i položajima. Ovaj je članak namijenjen developeru koji ga postavlja.
API je dio paketa koji uključuju Webhooks & API (Basic i viši). Na ostalim paketima gumbi za izradu tokena i aplikacija su zaključani.
Izradite osobni pristupni token
Osobni pristupni token najbrži je način za pozivanje API-ja iz vlastitih skripti i sustava.
- Idite na Settings > API (pod Developers).
- Pod Personal access tokens kliknite Create personal access token. U dijaloškom okviru piše „Generate a token to authenticate API requests.”
- Dodijelite mu Name po kojem ćete ga kasnije prepoznati, npr. „Data warehouse”.
- Pod Scopes odaberite što token smije raditi (vidi niže). Select all odabire sve opsege. Tokenu dajte samo onaj pristup koji mu je potreban.
- Kliknite Save. Prikazat će se poruka „Your access token has been created”.
- Kopirajte token pod Secret. „Save the secret above, as this is the only time you will see it.” Pohranite ga na sigurno mjesto, primjerice u upravitelj lozinki.
- Kliknite Close.
Token pripada vašem korisniku. Može pristupiti svakom Scratcher računu čiji ste član, uz opsege koje ste odabrali.
Opsezi
read:campaigns(View campaigns): popis i čitanje kampanjaread:lists(View lists): popis i čitanje popisa leadovaread:leads(View leads): čitanje leadovawrite:leads(Write leads): izrada, ažuriranje i brisanje leadova na popisuread:placements(View placements): čitanje položajawrite:placements(Write placements): izrada, ažuriranje i brisanje položajaread:products(View products): čitanje proizvodawrite:products(Write products): izrada, ažuriranje i brisanje proizvoda
Za čitanje leadova kampanje token treba i read:campaigns i read:leads. Za izradu i izmjenu položaja vaš paket mora uključivati i Embed / URL.
Opozovite token
Kliknite token na popisu kako biste otvorili Show personal access token. Prikazuju se Name i Scopes. Kliknite Revoke i potvrdite („Are you sure you want to delete this token? This cannot be undone!”). Sve što koristi taj token odmah prestaje raditi.
Pošaljite zahtjev
Osnovni URL je https://platform.scratcher.io/api/v1/. Token pošaljite u zaglavlju Authorization i zatražite JSON:
curl https://platform.scratcher.io/api/v1/accounts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" Glavne krajnje točke
GET /me: korisnik kojem token pripadaGET /accounts: računi kojima imate pristup. ID računa koristite u ostalim pozivima.GET /accounts/{account}/campaignsi/campaigns/{campaign}: vaše kampanjeGET /accounts/{account}/campaigns/{campaign}/leads: leadovi kampanje, od najnovijih, s njihovim poljima, prihvaćenim privolama te, za dobitnike, nagradom i kodomGET /accounts/{account}/listsi/lists/{list}: vaši popisi leadova/accounts/{account}/lists/{list}/leads: leadovi popisa.GETza čitanje,POSTza izradu,PUTza ažuriranje iDELETEza brisanje. Lead imaemail,phone_numberi neobaveznicustom_token./accounts/{account}/products: proizvodi (GET,POST,PUT,DELETE)/accounts/{account}/placements: položaji (GET,POST,PUT,DELETE)
Popisi su podijeljeni na stranice: dodajte ?page=2 i tako dalje. Možete pristupiti samo računima čiji ste član; ostali ID-jevi računa vraćaju pogrešku.
Ograničenja
Možete poslati 60 zahtjeva u minuti po korisniku. Ako prekoračite ograničenje, API odgovara statusom 429; pričekajte trenutak i pokušajte ponovno.
API referenca
Potpunu referencu sa svim poljima, filtrima, primjerima i Postman kolekcijom pronaći ćete u dokumentaciji API reference. Na nju vodi i gumb API reference na vrhu stranice Settings > API.
Izradite aplikaciju s OAuthom
Ako izrađujete aplikaciju koju drugi korisnici Scratchera povezuju sa svojim računom, umjesto osobnog tokena registrirajte OAuth aplikaciju.
- Idite na Settings > API. Pod My apps kliknite Create app („Register an OAuth application for the API.”).
- Ispunite Application name (korisnici ga vide kada odobravaju vašu aplikaciju) i Redirect URI (kamo se korisnici vraćaju nakon odobrenja).
- Kliknite Save. Prikazat će se poruka „Your app has been created!” s Client ID i Client secret.
- Odmah kopirajte tajni ključ klijenta: „Save the client secret above, as this is the only time you will see it.” Kliknite Continue.
Vaša aplikacija šalje korisnike na https://platform.scratcher.io/oauth/authorize s vašim ID-jem klijenta, URI-jem za preusmjeravanje i potrebnim opsezima. Korisnik se prijavljuje u Scratcher i vidi Authorization request: „This application will be able to:”, a zatim popis opsega. Klikne Authorize ili Cancel. Vaša aplikacija zatim kod zamjenjuje za tokene na https://platform.scratcher.io/oauth/token.
- Pristupni tokeni dobiveni putem OAutha vrijede dva mjeseca. Tokeni za osvježavanje vrijede tri mjeseca; njima dobivate novi pristupni token.
- Za promjenu naziva ili URI-ja za preusmjeravanje kliknite aplikaciju pod My apps, unesite izmjene i kliknite Save („Your settings have been saved”). „You cannot view your secret afterwards.”
- Delete app uklanja aplikaciju, a veza svakog korisnika s njom prestaje raditi: „Are you sure you want to delete this app? This cannot be undone!”
Aplikacije koje ste odobrili
Authorized apps prikazuje aplikacije kojima ste dali pristup svom računu, poput Zapiera, zajedno s njihovim opsezima. Kliknite Revoke kako biste ukinuli pristup.
Tko može koristiti API?
Stranica API prikazuje se korisnicima s ulogom Owner, Admin ili Manager. Token nikada ne može učiniti više od korisnika koji ga je izradio.