REST API platformy Scratcher umožňuje vašim systémom čítať vaše kampane, leady a zoznamy, pridávať a upravovať leady a spravovať produkty a umiestnenia. Tento článok je určený vývojárovi, ktorý API nastavuje.
API je súčasťou plánov, ktoré zahŕňajú Webhooks & API (Basic a vyššie). V ostatných plánoch sú tlačidlá na vytváranie tokenov a aplikácií zamknuté.
Vytvorenie osobného prístupového tokenu
Osobný prístupový token je najrýchlejší spôsob, ako volať API z vlastných skriptov a systémov.
- Prejdite do Settings > API (v časti Developers).
- V časti Personal access tokens kliknite na Create personal access token. V dialógu sa zobrazí „Generate a token to authenticate API requests.“
- Zadajte Name, podľa ktorého token neskôr spoznáte, napríklad „Dátový sklad“.
- V časti Scopes vyberte, čo môže token robiť (pozri nižšie). Select all vyberie všetky oprávnenia. Tokenu dajte len taký prístup, aký naozaj potrebuje.
- Kliknite na Save. Zobrazí sa „Your access token has been created“.
- Skopírujte token v časti Secret. „Save the secret above, as this is the only time you will see it.“ Uložte ho na bezpečné miesto, napríklad do správcu hesiel.
- Kliknite na Close.
Token patrí vášmu používateľovi. Má prístup ku všetkým účtom Scratcher, ktorých ste členom, s oprávneniami, ktoré ste vybrali.
Oprávnenia (scopes)
read:campaigns(View campaigns): zobrazenie a čítanie kampaníread:lists(View lists): zobrazenie a čítanie zoznamov leadovread:leads(View leads): čítanie leadovwrite:leads(Write leads): vytváranie, úprava a mazanie leadov v zoznameread:placements(View placements): čítanie umiestneníwrite:placements(Write placements): vytváranie, úprava a mazanie umiestneníread:products(View products): čítanie produktovwrite:products(Write products): vytváranie, úprava a mazanie produktov
Na čítanie leadov kampane potrebuje token oprávnenia read:campaigns aj read:leads. Vytváranie a úprava umiestnení si navyše vyžaduje funkciu Embed / URL vo vašom pláne.
Zrušenie tokenu
Kliknutím na token v zozname otvoríte Show personal access token. Zobrazí sa jeho Name a Scopes. Kliknite na Revoke a potvrďte („Are you sure you want to delete this token? This cannot be undone!“). Všetko, čo token používa, okamžite prestane fungovať.
Odoslanie požiadavky
Základná URL adresa je https://platform.scratcher.io/api/v1/. Token pošlite v hlavičke Authorization a vyžiadajte si JSON:
curl https://platform.scratcher.io/api/v1/accounts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" Hlavné endpointy
GET /me: používateľ, ktorému token patríGET /accounts: účty, ku ktorým máte prístup. ID účtu použite v ostatných volaniach.GET /accounts/{account}/campaignsa/campaigns/{campaign}: vaše kampaneGET /accounts/{account}/campaigns/{campaign}/leads: leady kampane od najnovších, s ich poľami, udelenými súhlasmi a pri výhercoch aj s výhrou a kódomGET /accounts/{account}/listsa/lists/{list}: vaše zoznamy leadov/accounts/{account}/lists/{list}/leads: leady zoznamu.GETna čítanie,POSTna vytvorenie,PUTna úpravu aDELETEna zmazanie. Lead máemail,phone_numbera voliteľnýcustom_token./accounts/{account}/products: produkty (GET,POST,PUT,DELETE)/accounts/{account}/placements: umiestnenia (GET,POST,PUT,DELETE)
Zoznamy sú stránkované: pridajte ?page=2 atď. Prístup máte len k účtom, ktorých ste členom; iné ID účtov vrátia chybu.
Limity
Každý používateľ môže odoslať 60 požiadaviek za minútu. Ak limit prekročíte, API odpovie stavom 429; chvíľu počkajte a skúste to znova.
Referenčná dokumentácia API
Kompletnú referenciu so všetkými poľami, filtrami, príkladmi a kolekciou pre Postman nájdete v referenčnej dokumentácii API. Odkazuje na ňu aj tlačidlo API reference v hornej časti Settings > API.
Vytvorenie aplikácie s OAuth
Ak vytvárate aplikáciu, ktorú si ďalší používatelia Scratcher pripájajú k vlastnému účtu, namiesto osobného tokenu zaregistrujte OAuth aplikáciu.
- Prejdite do Settings > API. V časti My apps kliknite na Create app („Register an OAuth application for the API.“).
- Vyplňte Application name (používatelia ho uvidia pri schvaľovaní aplikácie) a Redirect URI (kam budú používatelia po schválení presmerovaní).
- Kliknite na Save. Zobrazí sa „Your app has been created!“ spolu s Client ID a Client secret.
- Client secret si skopírujte hneď: „Save the client secret above, as this is the only time you will see it.“ Kliknite na Continue.
Vaša aplikácia posiela používateľov na https://platform.scratcher.io/oauth/authorize s vaším client ID, redirect URI a požadovanými oprávneniami. Používateľ sa prihlási do Scratcheru a uvidí Authorization request: „This application will be able to:“ a za tým zoznam oprávnení. Klikne na Authorize alebo Cancel. Vaša aplikácia potom vymení kód za tokeny na https://platform.scratcher.io/oauth/token.
- Prístupové tokeny z OAuth platia dva mesiace. Obnovovacie (refresh) tokeny platia tri mesiace; použite ich na získanie nového prístupového tokenu.
- Ak chcete zmeniť názov alebo redirect URI, kliknite na aplikáciu v časti My apps, upravte údaje a kliknite na Save („Your settings have been saved“). „You cannot view your secret afterwards.“
- Delete app aplikáciu odstráni a pripojenia všetkých používateľov k nej prestanú fungovať: „Are you sure you want to delete this app? This cannot be undone!“
Schválené aplikácie
Authorized apps zobrazuje aplikácie, ktorým ste udelili prístup k svojmu účtu, napríklad Zapier, spolu s ich oprávneniami. Kliknutím na Revoke prístup odoberiete.
Kto môže používať API?
Stránka API sa zobrazuje používateľom s rolou Owner, Admin alebo Manager. Token nikdy nemôže urobiť viac ako používateľ, ktorý ho vytvoril.