Pereiti prie turinio
Rex, jūsų DI asistentas: rutiną atliks jis, idėjos – jūsų 👉 Susipažinkite su Rex

Darbo su REST API pradžia

Sukurkite asmeninį prieigos raktą su tinkamomis prieigos sritimis arba užregistruokite OAuth programėlę ir skaitykite kampanijas, potencialius klientus bei sąrašus savo sistemose.

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ų.

  1. Eikite į Settings > API (skiltyje Developers).
  2. Skiltyje Personal access tokens spustelėkite Create personal access token. Dialogo lange rašoma „Generate a token to authenticate API requests.“
  3. Suteikite jam Name, kurį vėliau atpažinsite, pavyzdžiui, „Duomenų saugykla“.
  4. Skiltyje Scopes pasirinkite, ką raktas galės daryti (žr. toliau). Select all pažymi visas sritis. Suteikite raktui tik tiek prieigos, kiek jam reikia.
  5. Spustelėkite Save. Pamatysite „Your access token has been created“.
  6. 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.
  7. 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 skaitymas
  • read:lists (View lists): potencialių klientų sąrašų pateikimas ir skaitymas
  • read:leads (View leads): potencialių klientų skaitymas
  • write:leads (Write leads): potencialių klientų kūrimas, atnaujinimas ir šalinimas sąraše
  • read:placements (View placements): talpinimo vietų skaitymas
  • write:placements (Write placements): talpinimo vietų kūrimas, atnaujinimas ir šalinimas
  • read:products (View products): produktų skaitymas
  • write: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 raktas
  • GET /accounts: paskyros, prie kurių turite prieigą. Kitose užklausose naudokite paskyros ID.
  • GET /accounts/{account}/campaigns ir /campaigns/{campaign}: jūsų kampanijos
  • GET /accounts/{account}/campaigns/{campaign}/leads: kampanijos potencialūs klientai, naujausi pirmiausia, su jų laukais, priimtais sutikimais, o laimėtojų – ir prizu bei kodu
  • GET /accounts/{account}/lists ir /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 turi email, phone_number ir 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ę.

  1. Eikite į Settings > API. Skiltyje My apps spustelėkite Create app („Register an OAuth application for the API.“).
  2. Užpildykite Application name (naudotojai jį matys tvirtindami jūsų programėlę) ir Redirect URI (kur naudotojai bus nukreipti po patvirtinimo).
  3. Spustelėkite Save. Pamatysite „Your app has been created!“ su Client ID ir Client secret.
  4. 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.

Reikia pagalbos?

Vis dar reikia pagalbos?

Tikri žmonės pasiruošę padėti. Jei jau naudojate Scratcher, greičiausias būdas – pokalbis platformoje.

  • Rašykite mums

    Prisijunkite ir spustelėkite pokalbio mygtuką apačioje dešinėje. Rex atsako iš karto, o mūsų komanda – vos per vieną spustelėjimą.

  • Užsisakyti susitikimą

    Nemokamas 30 minučių vaizdo skambutis su mūsų komanda: apžvalga, kampanijų idėjos ar pagalba nustatant.

  • Parašykite mums el. laišką

    Rašykite adresu contact@scratcher.io ir mes jums atsakysime.