REST API на Scratcher позволява на вашите собствени системи да четат кампаниите, лийдовете и списъците ви, да добавят и актуализират лийдове, както и да управляват продукти и позиции за вграждане. Тази статия е предназначена за разработчика, който го настройва.
API е включен в плановете с Webhooks & API (Basic и по-високи). При другите планове бутоните за създаване на токени и приложения са заключени.
Създаване на личен токен за достъп
Личният токен за достъп е най-бързият начин да извиквате API от собствените си скриптове и системи.
- Отидете в Settings > API (в раздел Developers).
- В Personal access tokens щракнете върху Create personal access token. В прозореца пише „Generate a token to authenticate API requests.“
- Дайте му Name, което ще разпознаете по-късно, например „Data warehouse“.
- В Scopes изберете какво може да прави токенът (вижте по-долу). Select all избира всички обхвати. Давайте на токена само достъпа, от който наистина се нуждае.
- Щракнете върху Save. Ще видите „Your access token has been created“.
- Копирайте токена от Secret. „Save the secret above, as this is the only time you will see it.“ Съхранете го на сигурно място, например в мениджър на пароли.
- Щракнете върху Close.
Токенът принадлежи на вашия потребител. С него имате достъп до всеки акаунт в Scratcher, в който членувате, в рамките на избраните обхвати.
Обхвати
read:campaigns(View campaigns): извеждане и четене на кампанииread:lists(View lists): извеждане и четене на списъци с лийдовеread:leads(View leads): четене на лийдовеwrite:leads(Write leads): създаване, актуализиране и изтриване на лийдове в списъкread:placements(View placements): четене на позиции за вгражданеwrite:placements(Write placements): създаване, актуализиране и изтриване на позиции за вгражданеread:products(View products): четене на продуктиwrite:products(Write products): създаване, актуализиране и изтриване на продукти
За да чете лийдовете на дадена кампания, токенът се нуждае както от read:campaigns, така и от read:leads. Създаването и промяната на позиции за вграждане изисква и Embed / URL във вашия план.
Отнемане на токен
Щракнете върху токена в списъка, за да отворите Show personal access token. Там се виждат Name и Scopes. Щракнете върху Revoke и потвърдете („Are you sure you want to delete this token? This cannot be undone!“). Всичко, което използва токена, спира да работи веднага.
Изпращане на заявка
Базовият URL адрес е https://platform.scratcher.io/api/v1/. Изпратете токена в заглавката Authorization и поискайте JSON:
curl https://platform.scratcher.io/api/v1/accounts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" Основни крайни точки
GET /me: потребителят, на когото принадлежи токенътGET /accounts: акаунтите, до които имате достъп. Използвайте id на акаунта в останалите извиквания.GET /accounts/{account}/campaignsи/campaigns/{campaign}: вашите кампанииGET /accounts/{account}/campaigns/{campaign}/leads: лийдовете на дадена кампания, като най-новите са първи, с техните полета, приетите съгласия, а за победителите – наградата и кодаGET /accounts/{account}/listsи/lists/{list}: вашите списъци с лийдове/accounts/{account}/lists/{list}/leads: лийдовете в даден списък.GETза четене,POSTза създаване,PUTза актуализиране иDELETEза изтриване. Лийдът имаemail,phone_numberи незадължителенcustom_token./accounts/{account}/products: продукти (GET,POST,PUT,DELETE)/accounts/{account}/placements: позиции за вграждане (GET,POST,PUT,DELETE)
Списъците се връщат на страници: добавете ?page=2 и т.н. Имате достъп само до акаунти, в които членувате; другите id на акаунти връщат грешка.
Ограничения
Можете да изпращате 60 заявки на минута на потребител. Ако надвишите лимита, API отговаря със статус 429; изчакайте малко и опитайте отново.
Справочник за API
Пълният справочник с всички полета, филтри, примери и колекция за Postman е в документацията на API. Бутонът API reference в горната част на Settings > API също води към него.
Създаване на приложение с OAuth
Ако създавате приложение, което други потребители на Scratcher свързват със собствения си акаунт, регистрирайте OAuth приложение вместо да използвате личен токен.
- Отидете в Settings > API. В My apps щракнете върху Create app („Register an OAuth application for the API.“).
- Попълнете Application name (потребителите го виждат, когато одобряват приложението ви) и Redirect URI (къде се връщат потребителите след одобрение).
- Щракнете върху Save. Ще видите „Your app has been created!“ заедно с Client ID и Client secret.
- Копирайте клиентската тайна веднага: „Save the client secret above, as this is the only time you will see it.“ Щракнете върху Continue.
Вашето приложение пренасочва потребителите към https://platform.scratcher.io/oauth/authorize с вашия client ID, redirect URI и нужните обхвати. Потребителят влиза в Scratcher и вижда Authorization request: „This application will be able to:“, последвано от обхватите. Той щраква върху Authorize или Cancel. След това приложението ви обменя кода за токени на https://platform.scratcher.io/oauth/token.
- Токените за достъп от OAuth са валидни два месеца. Токените за опресняване са валидни три месеца; използвайте ги, за да получите нов токен за достъп.
- За да промените името или redirect URI, щракнете върху приложението в My apps, направете промяната и щракнете върху Save („Your settings have been saved“). „You cannot view your secret afterwards.“
- Delete app премахва приложението и връзката на всеки потребител с него спира да работи: „Are you sure you want to delete this app? This cannot be undone!“
Одобрени от вас приложения
Authorized apps показва приложенията, на които сте дали достъп до акаунта си, например Zapier, заедно с техните обхвати. Щракнете върху Revoke, за да отнемете достъпа.
Кой може да използва API?
Страницата API се показва на потребители с роля Owner, Admin или Manager. Токенът никога не може да прави повече от потребителя, който го е създал.