Avito ApplicationAccess API
Для работы с API приложений от лица пользователя есть возможность получить токен через Authorization Code механизм протокола OAuth2. Для этого в первую очередь нужно зарегистрировать приложение на https://developers.avito.ru/applications. После успешной регистрации ваше приложение получит возможность работать с API Авито от лица пользователя (если последний выдаст на это разрешение). Подробнее об Authorization Code флоу протокола OAuth2 можно почитать [в статье](https://www.digitalocean.com/community/tutorials/oauth-2-ru). Процесс работы с этим флоу в API Авито отличается только незначительными деталями – ниже по шагам описан процесс интеграции. ### Шаг 1: Регистрация приложения Регистрируем приложение через https://developers.avito.ru/application. Для регистрации нужно указать: * Имя приложения, которое будет выводиться пользователям в форме подтверждения прав * Redirect URI - адрес, на который сайт Авито средиректит пользователя после подтверждения прав * Скоупы, которые необходимы вашему приложению (подробнее о доступных скоупах ниже) * Описание приложения - для каких целей вы планируете использовать доступ к данным В данный момент мы регистрируем только доверенные приложения от наших партнеров. Скоупы определяют права, на которые ваше приложение сможет рассчитывать после подверждения авторизации пользователем. Доступные скоупы: * messenger:read: Чтение сообщений в мессенджере Авито * messenger:write: Модифицирование сообщений в мессенджере Авито * user_balance:read: Получение баланса пользователя * job:write: Изменение объявлений вертикали Работа * job:cv: Получение информации резюме * job:vacancy: Работа с вакансиями * job:applications: Получение информации об откликах на вакансии * user_operations:read: Получение истории операций пользователя * user:read: Получение информации о пользователе * autoload:reports: Получение отчетов Автозагрузки * items:info: Получение информации об объявлениях * items:apply_vas: Применение дополнительных услуг * short_term_rent:read: Получение информации об объявлениях краткосрочной аренды * short_term_rent:write: Изменение объявлений краткосрочной аренды * stats:read: Получение статистики объявлений ### Шаг 2: Ссылка с кодом авторизации Сначала пользователю предоставляется ссылка следующего вида: ``` https://avito.ru/oauth?response_type=code&pro_users_flow=true&client_id=&scope=messenger:read,messenger:write ``` ### Шаг 3: Пользователь авторизует приложение Пользователь переходит по ссылке на Авито, аутентифицируется при необходимости, затем подтверждает выдачу необходимых прав вашему приложению. ### Шаг 4: Приложение получает код авторизации Если пользователь выбирает "Авторизовать приложение", Авито перенаправляет пользовательский агент (браузер) по URI перенаправления (Redirect URI), который был задан на этапе регистрации приложения и добавляет в него параметр `code`. Например, если при регистрации в качестве Redirect URI был указан адрес `https://example.com/callback/avito`, то мы перенаправим пользователя на: ``` https://example.com/callback/avito?code= ``` ### Шаг 5: Приложение запрашивает токен доступа Приложение запрашивает токен доступа у API Авито путём отправки авторизационного кода и аутентификационной информации (включая секрет приложения). Ниже представлен пример POST-запроса для получения access token: ``` curl -L -X POST 'https://api.avito.ru/token/' \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode 'client_id=' \ --data-urlencode 'client_secret=' \ --data-urlencode 'code=' ``` ### Шаг 6: Приложение получает токен доступа Если авторизация прошла успешно, API возвращает токен доступа (а также токен для обновления токена доступа - refresh token). Весь ответ сервера может выглядеть следующим образом: ``` { "access_token": "", "expires_in": 86400, "refresh_token": "", "scope": "messenger:read,messenger:write", "token_type": "Bearer" } ``` Приложение сохраняет access_token и refresh_token. ### Шаг 7: Приложение делает запросы к API c токеном доступа Далее приложение может выполнять запросы к API с заголовком `Authorization: Bearer ` ### Шаг 8: Приложение обновляет access_token Время действия access token ограничено - 24 часа с момента его получения. После этого вам необходимо получить новый токен. После истечения срока действия токена доступа все запросы к API с его использованием будут возвращать код ошибки 403. Сохраненный refresh token может быть использован для получения нового токена доступа от авторизационного сервера. Ниже представлен пример POST-запроса, использующего refresh token для обновления токена доступа: ``` curl -L -X POST 'https://api.avito.ru/token/' \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=refresh_token' \ --data-urlencode 'client_id=' \ --data-urlencode 'client_secret=' \ --data-urlencode 'refresh_token=' ``` В ответ приложение получит точно такой же JSON, как и при обмене code на access token. При этом будет получен не только новый access_token, но и новый refresh_token. Обновите оба значения в своей базе данных. ### Дополнительный параметр state Для того чтобы защитить данные пользователей мы крайне рекомендуем использовать параметр state. Этот параметр позволяет защититься от CSRF-атак и восстановить состояние вашего приложения на момент начала авторизации. Подробнее, зачем нужен параметр state, можно прочитать [тут](https://auth0.com/docs/protocols/oauth2/oauth-state). Для того, чтобы использовать state – просто включите его в начальный URL: ``` https://avito.ru/oauth?response_type=code&pro_users_flow=true&client_id=&scope=messenger:read,messenger:write&state= ``` В итоге state будет содержаться в финальном Redirect URI, на который Авито перенаправляет пользователя после подтверждения прав доступа. Например, если при регистрации в качестве Redirect URI был указан адрес `https://example.com/callback/avito`, то мы перенаправим пользователя на: ``` https://example.com/callback/avito?code=&state= ``` Не передавайте чувствительные данные в открытом виде в этом параметре. Генерируйте уникальное временное значение state в вашем приложении.