Ugrás a tartalomhoz
Rex, az Ön MI-asszisztense: a robotmunkát elvégzi, az ötletek az Önéi 👉 Ismerje meg Rexet

Első lépések a REST API-val

Hozzon létre személyes hozzáférési tokent a megfelelő jogosultsági körökkel, vagy regisztráljon OAuth-alkalmazást, és olvassa ki a kampányokat, leadeket és listákat saját rendszereiből.

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.

  1. Lépjen a Settings > API menüpontra (a Developers alatt).
  2. 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.”
  3. Adjon neki egy később is felismerhető Name (nevet), például „Adattárház”.
  4. 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.
  5. Kattintson a Save gombra. Megjelenik a „Your access token has been created” üzenet.
  6. 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.
  7. 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ása
  • read:lists (View lists): leadlisták listázása és olvasása
  • read:leads (View leads): leadek olvasása
  • write:leads (Write leads): leadek létrehozása, frissítése és törlése egy listában
  • read:placements (View placements): elhelyezések olvasása
  • write:placements (Write placements): elhelyezések létrehozása, frissítése és törlése
  • read:products (View products): termékek olvasása
  • write: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 tartozik
  • GET /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ányai
  • GET /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óddal
  • GET /accounts/{account}/lists és /lists/{list}: az Ön leadlistái
  • /accounts/{account}/lists/{list}/leads: egy lista leadjei. GET az olvasáshoz, POST a létrehozáshoz, PUT a frissítéshez és DELETE a törléshez. Egy lead rendelkezik email, phone_number és opcionális custom_token mező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.

  1. Lépjen a Settings > API menüpontra. A My apps alatt kattintson a Create app gombra („Register an OAuth application for the API.”).
  2. 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).
  3. Kattintson a Save gombra. Megjelenik a „Your app has been created!” üzenet a Client ID és a Client secret adatokkal.
  4. 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.

Segítségre van szüksége?

Még mindig segítségre van szüksége?

Valódi emberek segítenek. Ha már használja a Scratchert, a leggyorsabb út a platformon belüli csevegés.

  • Csevegjen velünk

    Jelentkezzen be, és kattintson a jobb alsó sarokban lévő csevegés gombra. Rex azonnal válaszol, csapatunk pedig egy kattintásnyira van.

  • Megbeszélés foglalása

    Ingyenes, 30 perces videóhívás csapatunkkal: bemutató, kampányötletek vagy segítség a beállításban.

  • Írjon nekünk e-mailt

    Írjon a contact@scratcher.io címre, és hamarosan válaszolunk.