Scratcheri REST API võimaldab teie enda süsteemidel lugeda teie kampaaniaid, leade ja loendeid, lisada ja uuendada leade ning hallata tooteid ja paigutusi. See artikkel on mõeldud arendajale, kes API seadistab.
API kuulub pakettidesse, mis sisaldavad funktsiooni Webhooks & API (Basic ja kõrgemad). Teistes pakettides on lubade ja rakenduste loomise nupud lukus.
Isikliku juurdepääsuloa loomine
Isiklik juurdepääsuluba on kiireim viis API kasutamiseks oma skriptidest ja süsteemidest.
- Avage Settings > API (jaotises Developers).
- Klõpsake jaotises Personal access tokens nuppu Create personal access token. Dialoogis on kirjas „Generate a token to authenticate API requests.“
- Andke sellele Name, mille hiljem ära tunnete, näiteks „Andmeladu“.
- Valige jaotises Scopes, mida luba teha tohib (vt allpool). Select all valib kõik õigused. Andke loale ainult vajalik juurdepääs.
- Klõpsake Save. Kuvatakse teade „Your access token has been created“.
- Kopeerige luba väljalt Secret. „Save the secret above, as this is the only time you will see it.“ Hoidke seda turvaliselt, näiteks paroolihalduris.
- Klõpsake Close.
Luba kuulub teie kasutajale. Sellega pääseb ligi kõigile Scratcheri kontodele, mille liige te olete, valitud õiguste ulatuses.
Õigused (scopes)
read:campaigns(View campaigns): kampaaniate loetlemine ja lugemineread:lists(View lists): leadide loendite loetlemine ja lugemineread:leads(View leads): leadide lugeminewrite:leads(Write leads): leadide loomine, uuendamine ja kustutamine loendisread:placements(View placements): paigutuste lugeminewrite:placements(Write placements): paigutuste loomine, uuendamine ja kustutamineread:products(View products): toodete lugeminewrite:products(Write products): toodete loomine, uuendamine ja kustutamine
Kampaania leadide lugemiseks vajab luba nii õigust read:campaigns kui ka read:leads. Paigutuste loomiseks ja muutmiseks peab teie paketis olema ka Embed / URL.
Loa tühistamine
Klõpsake loendis loal, et avada Show personal access token. Seal on näha Name ja Scopes. Klõpsake Revoke ja kinnitage („Are you sure you want to delete this token? This cannot be undone!“). Kõik, mis luba kasutab, lakkab kohe töötamast.
Päringu tegemine
Baas-URL on https://platform.scratcher.io/api/v1/. Saatke luba päises Authorization ja küsige vastust JSON-vormingus:
curl https://platform.scratcher.io/api/v1/accounts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" Peamised lõpp-punktid
GET /me: kasutaja, kellele luba kuulubGET /accounts: kontod, millele teil on juurdepääs. Kasutage konto ID-d teistes päringutes.GET /accounts/{account}/campaignsja/campaigns/{campaign}: teie kampaaniadGET /accounts/{account}/campaigns/{campaign}/leads: kampaania leadid, uusimad eespool, koos nende väljade, aktsepteeritud nõusolekute ning võitjate puhul auhinna ja koodigaGET /accounts/{account}/listsja/lists/{list}: teie leadide loendid/accounts/{account}/lists/{list}/leads: loendi leadid.GETlugemiseks,POSTloomiseks,PUTuuendamiseks jaDELETEkustutamiseks. Leadil onemail,phone_numberja valikulinecustom_token./accounts/{account}/products: tooted (GET,POST,PUT,DELETE)/accounts/{account}/placements: paigutused (GET,POST,PUT,DELETE)
Loendid on lehekülgedeks jaotatud: lisage ?page=2 jne. Pääsete ligi ainult kontodele, mille liige te olete; teiste kontode ID-d tagastavad vea.
Piirangud
Iga kasutaja saab teha 60 päringut minutis. Piirangu ületamisel vastab API olekukoodiga 429; oodake hetk ja proovige uuesti.
API dokumentatsioon
Täielik dokumentatsioon kõigi väljade, filtrite, näidete ja Postmani kollektsiooniga on saadaval API dokumentatsioonis. Sellele viitab ka nupp API reference lehe Settings > API ülaosas.
Rakenduse loomine OAuthiga
Kui loote rakenduse, mille teised Scratcheri kasutajad oma kontoga ühendavad, registreerige isikliku loa asemel OAuth-rakendus.
- Avage Settings > API. Klõpsake jaotises My apps nuppu Create app („Register an OAuth application for the API.“).
- Täitke väljad Application name (kasutajad näevad seda teie rakendust kinnitades) ja Redirect URI (kuhu kasutajad pärast kinnitamist tagasi suunatakse).
- Klõpsake Save. Kuvatakse teade „Your app has been created!“ koos väärtustega Client ID ja Client secret.
- Kopeerige kliendisaladus kohe: „Save the client secret above, as this is the only time you will see it.“ Klõpsake Continue.
Teie rakendus suunab kasutajad aadressile https://platform.scratcher.io/oauth/authorize koos teie kliendi ID, ümbersuunamis-URI ja vajalike õigustega. Kasutaja logib Scratcherisse sisse ja näeb vaadet Authorization request: „This application will be able to:“, millele järgnevad õigused. Ta klõpsab Authorize või Cancel. Seejärel vahetab teie rakendus koodi lubade vastu aadressil https://platform.scratcher.io/oauth/token.
- OAuthi juurdepääsuload kehtivad kaks kuud. Värskendusload kehtivad kolm kuud; nendega saab uue juurdepääsuloa.
- Nime või ümbersuunamis-URI muutmiseks klõpsake rakendusel jaotises My apps, tehke muudatus ja klõpsake Save („Your settings have been saved“). „You cannot view your secret afterwards.“
- Delete app eemaldab rakenduse ja kõigi kasutajate ühendus sellega lakkab töötamast: „Are you sure you want to delete this app? This cannot be undone!“
Teie kinnitatud rakendused
Authorized apps loetleb rakendused, millele olete andnud juurdepääsu oma kontole, näiteks Zapier, koos nende õigustega. Juurdepääsu äravõtmiseks klõpsake Revoke.
Kes saavad API-t kasutada?
Lehte API näidatakse kasutajatele, kelle roll on Owner, Admin või Manager. Luba ei saa kunagi teha rohkem kui selle loonud kasutaja.