Preskočiť na obsah
Rex, váš AI asistent: rutinu vybaví za vás, nápady ostávajú vaše 👉 Zoznámte sa s Rexom

Začíname s REST API

Vytvorte si osobný prístupový token so správnymi oprávneniami alebo zaregistrujte OAuth aplikáciu a čítajte kampane, leady a zoznamy z vlastných systémov.

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.

  1. Prejdite do Settings > API (v časti Developers).
  2. V časti Personal access tokens kliknite na Create personal access token. V dialógu sa zobrazí „Generate a token to authenticate API requests.“
  3. Zadajte Name, podľa ktorého token neskôr spoznáte, napríklad „Dátový sklad“.
  4. 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.
  5. Kliknite na Save. Zobrazí sa „Your access token has been created“.
  6. 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.
  7. 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 leadov
  • read:leads (View leads): čítanie leadov
  • write:leads (Write leads): vytváranie, úprava a mazanie leadov v zozname
  • read:placements (View placements): čítanie umiestnení
  • write:placements (Write placements): vytváranie, úprava a mazanie umiestnení
  • read:products (View products): čítanie produktov
  • write: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}/campaigns a /campaigns/{campaign}: vaše kampane
  • GET /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ódom
  • GET /accounts/{account}/lists a /lists/{list}: vaše zoznamy leadov
  • /accounts/{account}/lists/{list}/leads: leady zoznamu. GET na čítanie, POST na vytvorenie, PUT na úpravu a DELETE na zmazanie. Lead má email, phone_number a 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.

  1. Prejdite do Settings > API. V časti My apps kliknite na Create app („Register an OAuth application for the API.“).
  2. Vyplňte Application name (používatelia ho uvidia pri schvaľovaní aplikácie) a Redirect URI (kam budú používatelia po schválení presmerovaní).
  3. Kliknite na Save. Zobrazí sa „Your app has been created!“ spolu s Client ID a Client secret.
  4. 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.

Potrebujete pomôcť?

Stále potrebujete pomoc?

Skutoční ľudia sú tu, aby vám pomohli. Ak už Scratcher používate, najrýchlejšou cestou je chat priamo v platforme.

  • Napíšte nám do chatu

    Prihláste sa a kliknite na tlačidlo chatu v pravom dolnom rohu. Rex odpovie hneď a náš tím je len jedno kliknutie od vás.

  • Rezervovať stretnutie

    Bezplatný 30-minútový videohovor s naším tímom: prehliadka, nápady na kampane alebo pomoc s nastavením.

  • Napíšte nám e-mail

    Napíšte na contact@scratcher.io a ozveme sa vám.