A Scratcher REST API segítségével saját rendszerei kiolvashatják kampányait, leadjeit és listáit, leadeket adhatnak hozzá és frissíthetnek, valamint termékeket és elhelyezéseket kezelhetnek. Ez a cikk a beállítást végző fejlesztőknek szól.
Az API azon csomagok része, amelyek tartalmazzák a Webhooks & API funkciót (Basic csomagtól felfelé). Más csomagokban a tokenek és alkalmazások létrehozására szolgáló gombok zárolva vannak.
Személyes hozzáférési token létrehozása
A személyes hozzáférési token a leggyorsabb módja annak, hogy saját szkriptjeiből és rendszereiből hívja az API-t.
- Lépjen a Settings > API menüpontra (a Developers alatt).
- A Personal access tokens részben kattintson a Create personal access token gombra. A párbeszédablakban ez áll: „Generate a token to authenticate API requests.”
- Adjon neki egy később is felismerhető Name (nevet), például „Adattárház”.
- A Scopes alatt válassza ki, mire használható a token (lásd lent). A Select all az összes jogosultsági kört kijelöli. Csak annyi hozzáférést adjon a tokennek, amennyire szüksége van.
- Kattintson a Save gombra. Megjelenik a „Your access token has been created” üzenet.
- Másolja ki a tokent a Secret alól. „Save the secret above, as this is the only time you will see it.” – vagyis most látja utoljára. Tárolja biztonságos helyen, például jelszókezelőben.
- Kattintson a Close gombra.
A token az Ön felhasználójához tartozik. A kiválasztott jogosultsági körökkel minden olyan Scratcher-fiókot elér, amelynek Ön tagja.
Jogosultsági körök
read:campaigns(View campaigns): kampányok listázása és olvasásaread:lists(View lists): leadlisták listázása és olvasásaread:leads(View leads): leadek olvasásawrite:leads(Write leads): leadek létrehozása, frissítése és törlése egy listábanread:placements(View placements): elhelyezések olvasásawrite:placements(Write placements): elhelyezések létrehozása, frissítése és törléseread:products(View products): termékek olvasásawrite:products(Write products): termékek létrehozása, frissítése és törlése
Egy kampány leadjeinek olvasásához a tokennek a read:campaigns és a read:leads jogosultságra is szüksége van. Elhelyezések létrehozásához és módosításához csomagjának az Embed / URL funkciót is tartalmaznia kell.
Token visszavonása
Kattintson a tokenre a listában a Show personal access token megnyitásához. Itt látható a Name és a Scopes. Kattintson a Revoke gombra, és erősítse meg („Are you sure you want to delete this token? This cannot be undone!”). Minden, ami a tokent használja, azonnal leáll.
Kérés küldése
Az alap URL: https://platform.scratcher.io/api/v1/. A tokent az Authorization fejlécben küldje, és JSON-választ kérjen:
curl https://platform.scratcher.io/api/v1/accounts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" Fő végpontok
GET /me: a felhasználó, akihez a token tartozikGET /accounts: azok a fiókok, amelyekhez hozzáfér. A többi hívásban a fiókazonosítót használja.GET /accounts/{account}/campaignsés/campaigns/{campaign}: az Ön kampányaiGET /accounts/{account}/campaigns/{campaign}/leads: egy kampány leadjei a legújabbtól kezdve, a mezőikkel, az elfogadott hozzájárulásokkal, nyertesek esetén pedig a nyereménnyel és a kóddalGET /accounts/{account}/listsés/lists/{list}: az Ön leadlistái/accounts/{account}/lists/{list}/leads: egy lista leadjei.GETaz olvasáshoz,POSTa létrehozáshoz,PUTa frissítéshez ésDELETEa törléshez. Egy lead rendelkezikemail,phone_numberés opcionáliscustom_tokenmezővel./accounts/{account}/products: termékek (GET,POST,PUT,DELETE)/accounts/{account}/placements: elhelyezések (GET,POST,PUT,DELETE)
A listák lapozottak: adja hozzá a ?page=2 paramétert és így tovább. Csak azokat a fiókokat érheti el, amelyeknek tagja; más fiókazonosítók hibát adnak vissza.
Korlátok
Felhasználónként percenként 60 kérést küldhet. Ha túllépi, az API 429-es állapotkóddal válaszol; várjon egy kicsit, és próbálja újra.
API-referencia
A teljes referencia az összes mezővel, szűrővel, példával és egy Postman-gyűjteménnyel az API-referenciadokumentációban található. A Settings > API oldal tetején lévő API reference gomb is erre mutat.
Alkalmazás készítése OAuth-tal
Ha olyan alkalmazást fejleszt, amelyet más Scratcher-felhasználók a saját fiókjukhoz kapcsolnak, személyes token helyett regisztráljon OAuth-alkalmazást.
- Lépjen a Settings > API menüpontra. A My apps alatt kattintson a Create app gombra („Register an OAuth application for the API.”).
- Töltse ki az Application name mezőt (a felhasználók ezt látják, amikor jóváhagyják az alkalmazást) és a Redirect URI mezőt (ide kerülnek vissza a felhasználók a jóváhagyás után).
- Kattintson a Save gombra. Megjelenik a „Your app has been created!” üzenet a Client ID és a Client secret adatokkal.
- Most másolja ki a kliens titkos kulcsát: „Save the client secret above, as this is the only time you will see it.” Kattintson a Continue gombra.
Az alkalmazás a felhasználókat a https://platform.scratcher.io/oauth/authorize címre irányítja a kliensazonosítóval, az átirányítási URI-val és a szükséges jogosultsági körökkel. A felhasználó bejelentkezik a Scratcherbe, és egy Authorization request ablakot lát: „This application will be able to:”, majd a jogosultsági körök listáját. Ezután az Authorize vagy a Cancel gombra kattint. Az alkalmazás ezt követően a https://platform.scratcher.io/oauth/token címen tokenekre cseréli a kódot.
- Az OAuth-hozzáférési tokenek két hónapig érvényesek. A frissítési tokenek három hónapig érvényesek; ezekkel kérhet új hozzáférési tokent.
- A név vagy az átirányítási URI módosításához kattintson az alkalmazásra a My apps alatt, módosítsa, majd kattintson a Save gombra („Your settings have been saved”). „You cannot view your secret afterwards.” – a titkos kulcs később már nem tekinthető meg.
- A Delete app eltávolítja az alkalmazást, és az összes felhasználó kapcsolata megszűnik vele: „Are you sure you want to delete this app? This cannot be undone!”
Jóváhagyott alkalmazások
Az Authorized apps azokat az alkalmazásokat sorolja fel – például a Zapiert –, amelyeknek hozzáférést adott fiókjához, a jogosultsági köreikkel együtt. A hozzáférés megvonásához kattintson a Revoke gombra.
Ki használhatja az API-t?
Az API oldal az Owner, Admin vagy Manager szerepkörű felhasználók számára látható. Egy token soha nem tehet többet, mint az a felhasználó, aki létrehozta.