Scratcher REST API leidžia jūsų sistemoms skaityti jūsų kampanijas, potencialius klientus ir sąrašus, pridėti bei atnaujinti potencialius klientus, taip pat valdyti produktus ir talpinimo vietas. Šis straipsnis skirtas programuotojui, kuris jį diegia.
API įtraukta į planus, kuriuose yra Webhooks & API (nuo Basic ir aukštesnių). Kituose planuose raktų ir programėlių kūrimo mygtukai užrakinti.
Asmeninio prieigos rakto sukūrimas
Asmeninis prieigos raktas – greičiausias būdas kreiptis į API iš savo scenarijų ir sistemų.
- Eikite į Settings > API (skiltyje Developers).
- Skiltyje Personal access tokens spustelėkite Create personal access token. Dialogo lange rašoma „Generate a token to authenticate API requests.“
- Suteikite jam Name, kurį vėliau atpažinsite, pavyzdžiui, „Duomenų saugykla“.
- Skiltyje Scopes pasirinkite, ką raktas galės daryti (žr. toliau). Select all pažymi visas sritis. Suteikite raktui tik tiek prieigos, kiek jam reikia.
- Spustelėkite Save. Pamatysite „Your access token has been created“.
- Nukopijuokite raktą, esantį po Secret. „Save the secret above, as this is the only time you will see it.“ Laikykite jį saugiai, pavyzdžiui, slaptažodžių tvarkyklėje.
- Spustelėkite Close.
Raktas priklauso jūsų naudotojui. Su pasirinktomis sritimis juo galima pasiekti visas Scratcher paskyras, kurių narys esate.
Prieigos sritys
read:campaigns(View campaigns): kampanijų sąrašas ir skaitymasread:lists(View lists): potencialių klientų sąrašų pateikimas ir skaitymasread:leads(View leads): potencialių klientų skaitymaswrite:leads(Write leads): potencialių klientų kūrimas, atnaujinimas ir šalinimas sąrašeread:placements(View placements): talpinimo vietų skaitymaswrite:placements(Write placements): talpinimo vietų kūrimas, atnaujinimas ir šalinimasread:products(View products): produktų skaitymaswrite:products(Write products): produktų kūrimas, atnaujinimas ir šalinimas
Norint skaityti kampanijos potencialius klientus, raktui reikia ir read:campaigns, ir read:leads. Talpinimo vietoms kurti ir keisti jūsų plane taip pat turi būti Embed / URL.
Rakto atšaukimas
Spustelėkite raktą sąraše, kad atidarytumėte Show personal access token. Ten matysite Name ir Scopes. Spustelėkite Revoke ir patvirtinkite („Are you sure you want to delete this token? This cannot be undone!“). Viskas, kas naudoja šį raktą, iškart nustoja veikti.
Užklausos siuntimas
Bazinis URL yra https://platform.scratcher.io/api/v1/. Siųskite raktą antraštėje Authorization ir prašykite JSON formato:
curl https://platform.scratcher.io/api/v1/accounts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" Pagrindiniai galiniai taškai
GET /me: naudotojas, kuriam priklauso raktasGET /accounts: paskyros, prie kurių turite prieigą. Kitose užklausose naudokite paskyros ID.GET /accounts/{account}/campaignsir/campaigns/{campaign}: jūsų kampanijosGET /accounts/{account}/campaigns/{campaign}/leads: kampanijos potencialūs klientai, naujausi pirmiausia, su jų laukais, priimtais sutikimais, o laimėtojų – ir prizu bei koduGET /accounts/{account}/listsir/lists/{list}: jūsų potencialių klientų sąrašai/accounts/{account}/lists/{list}/leads: sąrašo potencialūs klientai.GET– skaityti,POST– kurti,PUT– atnaujinti,DELETE– šalinti. Potencialus klientas turiemail,phone_numberir neprivalomącustom_token./accounts/{account}/products: produktai (GET,POST,PUT,DELETE)/accounts/{account}/placements: talpinimo vietos (GET,POST,PUT,DELETE)
Sąrašai skaidomi puslapiais: pridėkite ?page=2 ir t. t. Galite pasiekti tik tas paskyras, kurių narys esate; kitų paskyrų ID grąžina klaidą.
Apribojimai
Vienas naudotojas gali pateikti 60 užklausų per minutę. Viršijus ribą, API grąžina būseną 429 – palaukite akimirką ir bandykite dar kartą.
API žinynas
Išsamus žinynas su visais laukais, filtrais, pavyzdžiais ir Postman kolekcija pateiktas API žinyno dokumentacijoje. Į jį veda ir mygtukas API reference, esantis Settings > API viršuje.
Programėlės kūrimas su OAuth
Jei kuriate programėlę, kurią kiti Scratcher naudotojai prijungs prie savo paskyrų, vietoj asmeninio rakto užregistruokite OAuth programėlę.
- Eikite į Settings > API. Skiltyje My apps spustelėkite Create app („Register an OAuth application for the API.“).
- Užpildykite Application name (naudotojai jį matys tvirtindami jūsų programėlę) ir Redirect URI (kur naudotojai bus nukreipti po patvirtinimo).
- Spustelėkite Save. Pamatysite „Your app has been created!“ su Client ID ir Client secret.
- Nukopijuokite kliento slaptąjį raktą dabar: „Save the client secret above, as this is the only time you will see it.“ Spustelėkite Continue.
Jūsų programėlė nukreipia naudotojus į https://platform.scratcher.io/oauth/authorize su jūsų kliento ID, nukreipimo URI ir reikiamomis sritimis. Naudotojas prisijungia prie Scratcher ir mato Authorization request: „This application will be able to:“, o po to – sričių sąrašą. Jis spusteli Authorize arba Cancel. Tada jūsų programėlė iškeičia kodą į raktus adresu https://platform.scratcher.io/oauth/token.
- OAuth prieigos raktai galioja du mėnesius. Atnaujinimo raktai galioja tris mėnesius – naudokite juos naujam prieigos raktui gauti.
- Norėdami pakeisti pavadinimą ar nukreipimo URI, spustelėkite programėlę skiltyje My apps, atlikite pakeitimus ir spustelėkite Save („Your settings have been saved“). „You cannot view your secret afterwards.“
- Delete app pašalina programėlę, ir visų naudotojų ryšys su ja nustoja veikti: „Are you sure you want to delete this app? This cannot be undone!“
Jūsų patvirtintos programėlės
Skiltyje Authorized apps pateikiamos programėlės, kurioms suteikėte prieigą prie savo paskyros, pavyzdžiui, Zapier, kartu su jų prieigos sritimis. Spustelėkite Revoke, kad atšauktumėte prieigą.
Kas gali naudoti API?
Puslapis API rodomas naudotojams, turintiems Owner, Admin arba Manager vaidmenį. Raktas niekada negali daryti daugiau nei jį sukūręs naudotojas.