Scratcher REST API ļauj jūsu sistēmām nolasīt jūsu kampaņas, potenciālos klientus un sarakstus, pievienot un atjaunināt potenciālos klientus, kā arī pārvaldīt produktus un izvietojumus. Šis raksts paredzēts izstrādātājam, kurš to iestata.
API ir pieejams plānos, kas ietver Webhooks & API (no Basic un augstāk). Citos plānos pogas pilnvaru un lietotņu izveidei ir bloķētas.
Personīgās piekļuves pilnvaras izveide
Personīgās piekļuves pilnvara ir ātrākais veids, kā izsaukt API no saviem skriptiem un sistēmām.
- Atveriet Settings > API (sadaļā Developers).
- Sadaļā Personal access tokens noklikšķiniet uz Create personal access token. Dialoglodziņā redzams teksts „Generate a token to authenticate API requests.”
- Piešķiriet tai Name, ko vēlāk atpazīsiet, piemēram, „Datu noliktava”.
- Sadaļā Scopes izvēlieties, ko pilnvara drīkst darīt (skatiet tālāk). Select all atlasa visas tiesības. Piešķiriet pilnvarai tikai nepieciešamo piekļuvi.
- Noklikšķiniet uz Save. Redzēsiet paziņojumu „Your access token has been created”.
- Nokopējiet pilnvaru zem Secret. „Save the secret above, as this is the only time you will see it.” Glabājiet to drošā vietā, piemēram, paroļu pārvaldniekā.
- Noklikšķiniet uz Close.
Pilnvara pieder jūsu lietotājam. Ar izvēlētajām tiesībām tā var piekļūt visiem Scratcher kontiem, kuros esat dalībnieks.
Tiesības
read:campaigns(View campaigns): kampaņu saraksta skatīšana un nolasīšanaread:lists(View lists): potenciālo klientu sarakstu skatīšana un nolasīšanaread:leads(View leads): potenciālo klientu nolasīšanawrite:leads(Write leads): potenciālo klientu izveide, atjaunināšana un dzēšana sarakstāread:placements(View placements): izvietojumu nolasīšanawrite:placements(Write placements): izvietojumu izveide, atjaunināšana un dzēšanaread:products(View products): produktu nolasīšanawrite:products(Write products): produktu izveide, atjaunināšana un dzēšana
Lai nolasītu kampaņas potenciālos klientus, pilnvarai nepieciešamas gan read:campaigns, gan read:leads tiesības. Izvietojumu izveidei un mainīšanai jūsu plānā nepieciešama arī funkcija Embed / URL.
Pilnvaras atsaukšana
Noklikšķiniet uz pilnvaras sarakstā, lai atvērtu Show personal access token. Tur redzams Name un Scopes. Noklikšķiniet uz Revoke un apstipriniet („Are you sure you want to delete this token? This cannot be undone!”). Viss, kas izmanto šo pilnvaru, nekavējoties pārstāj darboties.
Pieprasījuma veikšana
Bāzes URL ir https://platform.scratcher.io/api/v1/. Nosūtiet pilnvaru galvenē Authorization un pieprasiet JSON:
curl https://platform.scratcher.io/api/v1/accounts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" Galvenie galapunkti
GET /me: lietotājs, kuram pieder pilnvaraGET /accounts: konti, kuriem jums ir piekļuve. Citos izsaukumos izmantojiet konta id.GET /accounts/{account}/campaignsun/campaigns/{campaign}: jūsu kampaņasGET /accounts/{account}/campaigns/{campaign}/leads: kampaņas potenciālie klienti, sākot ar jaunākajiem, ar to laukiem, pieņemtajām piekrišanām un, uzvarētājiem, balvu un koduGET /accounts/{account}/listsun/lists/{list}: jūsu potenciālo klientu saraksti/accounts/{account}/lists/{list}/leads: saraksta potenciālie klienti.GETnolasīšanai,POSTizveidei,PUTatjaunināšanai unDELETEdzēšanai. Potenciālajam klientam iremail,phone_numberun neobligātscustom_token./accounts/{account}/products: produkti (GET,POST,PUT,DELETE)/accounts/{account}/placements: izvietojumi (GET,POST,PUT,DELETE)
Saraksti tiek dalīti lapās: pievienojiet ?page=2 un tā tālāk. Varat piekļūt tikai tiem kontiem, kuros esat dalībnieks; citu kontu id atgriež kļūdu.
Ierobežojumi
Vienam lietotājam var veikt 60 pieprasījumus minūtē. Ja ierobežojums tiek pārsniegts, API atbild ar statusu 429; nedaudz uzgaidiet un mēģiniet vēlreiz.
API dokumentācija
Pilna dokumentācija ar visiem laukiem, filtriem, piemēriem un Postman kolekciju pieejama API dokumentācijā. Uz to ved arī poga API reference lapas Settings > API augšdaļā.
Lietotnes izveide ar OAuth
Ja veidojat lietotni, ko citi Scratcher lietotāji savieno ar saviem kontiem, personīgās pilnvaras vietā reģistrējiet OAuth lietotni.
- Atveriet Settings > API. Sadaļā My apps noklikšķiniet uz Create app („Register an OAuth application for the API.”).
- Aizpildiet Application name (lietotāji to redz, apstiprinot jūsu lietotni) un Redirect URI (kur lietotāji tiek novirzīti pēc apstiprināšanas).
- Noklikšķiniet uz Save. Redzēsiet paziņojumu „Your app has been created!” ar Client ID un Client secret.
- Nokopējiet klienta noslēpumu tagad: „Save the client secret above, as this is the only time you will see it.” Noklikšķiniet uz Continue.
Jūsu lietotne novirza lietotājus uz https://platform.scratcher.io/oauth/authorize ar jūsu klienta ID, novirzīšanas URI un nepieciešamajām tiesībām. Lietotājs piesakās Scratcher un redz Authorization request: „This application will be able to:”, kam seko tiesību saraksts. Lietotājs noklikšķina uz Authorize vai Cancel. Pēc tam jūsu lietotne apmaina kodu pret pilnvarām adresē https://platform.scratcher.io/oauth/token.
- OAuth piekļuves pilnvaras ir derīgas divus mēnešus. Atsvaidzināšanas pilnvaras ir derīgas trīs mēnešus; izmantojiet tās, lai iegūtu jaunu piekļuves pilnvaru.
- Lai mainītu nosaukumu vai novirzīšanas URI, noklikšķiniet uz lietotnes sadaļā My apps, veiciet izmaiņas un noklikšķiniet uz Save („Your settings have been saved”). „You cannot view your secret afterwards.”
- Delete app izdzēš lietotni, un visu lietotāju savienojumi ar to pārstāj darboties: „Are you sure you want to delete this app? This cannot be undone!”
Jūsu apstiprinātās lietotnes
Sadaļā Authorized apps redzamas lietotnes, kurām esat piešķīris piekļuvi savam kontam, piemēram, Zapier, kopā ar to tiesībām. Noklikšķiniet uz Revoke, lai piekļuvi atsauktu.
Kas var izmantot API?
Lapa API tiek rādīta lietotājiem ar lomu Owner, Admin vai Manager. Pilnvara nekad nevar darīt vairāk nekā lietotājs, kurš to izveidojis.