API Руководство по интеграции

В этом руководстве объясняется весь процесс интеграции API, от регистрации до получения токенов и выполнения аутентифицированных запросов API.

1. Процесс адаптации

Что такое онбординг?

Регистрация — это однократный процесс настройки для получения учетных данных API:

• username
• password
• consumer_key
• consumer_secret

Чтобы начать этот процесс, вам понадобится токен регистрации, предоставленный Paylov.

Рекомендации по безопасности

После завершения регистрации ваши username и password устанавливаются вами, а consumer_key и consumer_secret выдаются Paylov.

Сохраняйте все четыре учетных данных строго конфиденциальными. Относитесь к ним как к паролям — никогда не передавайте их, никогда не раскрывайте их в клиентском коде или общедоступных репозиториях и храните их в безопасном диспетчере секретов или в переменных среды.

Если ваш consumer_secret утек или стал доступен неавторизованной стороне, немедленно сообщите об этом в службу поддержки Paylov — учетные данные будут немедленно отозваны.

Шаг 1. Проверьте токен регистрации

Сначала убедитесь, что ваш токен регистрации действителен.

Конечная точка

GET {BASE_URL}/merchant/onboarding/?token=YOUR_TOKEN

Параметры

• Требуется token — токен регистрации

Пример запроса

# PROD
curl -X GET "https://{BASE_URL}/merchant/onboarding/?token=YOUR_TOKEN"

Успешный ответ 200 OK

{
  "status": "ok"
}

Ответ об ошибке 400 Bad Request

{
  "error": "invalid_or_expired"
}

Шаг 2. Установите имя пользователя и пароль.

После проверки токена создайте свое имя пользователя и пароль. Взамен вы получите свои consumer_key и consumer_secret.

Требования к паролю

Ваш пароль должен:

• быть длиной не менее 8 символов
• содержать хотя бы одну строчную букву a-z
• содержать хотя бы одну заглавную букву A-Z
• содержать хотя бы одну цифру 0-9
• содержать хотя бы один специальный символ, например !@#$%^&*

Примеры действительных паролей

• Secure@Pass123!
• MyP@s3W0rd
• Tr0pic@lLh!eze

Примеры неверных паролей

• password123 — без заглавных букв и специальных символов.
• Pass123 — слишком коротко
• PASSWORD123! — нет строчной буквы

Конечная точка

POST {BASE_URL}/merchant/onboarding/?token=YOUR_TOKEN

Заголовки запросов

Content-Type: application/json

Тело запроса

{
  "username": "...",
  "password": "..."
}

Пример запроса

curl -X POST "https://{BASE_URL}/merchant/onboarding/?token=YOUR_TOKEN"   
-H "accept: */*"   
-H "Content-Type: application/json"   
-d '{
    "username": "...",
    "password": "..."
  }'

Успешный ответ 200 OK

{
  "consumer_key": "app_a1b2c3d4e5f6g7h8i9j0k1",
  "consumer_secret": "Ks8Lp90q0Rr1Ss2Tt3Uu4Vv5Ww6Xx7Yy8Zz9Aa0Bb1Cc2Dd3Ee",
  "username": "my_username"
}

Важные примечания

• consumer_key и consumer_secret — ваши учетные данные API. Храните их надежно.
• consumer_secret отображается только один раз. Если вы потеряете его, вам необходимо создать новые учетные данные.
• Регистрационный токен можно использовать только один раз.
• Храните свое имя пользователя и пароль в безопасности.

---

2. Получение токена доступа

Что такое токен доступа?

Токен доступа необходим для аутентифицированных запросов API. Включайте его в каждый вызов API.

Процесс запроса токена

Конечная точка

POST {BASE_URL}/merchant/oauth2/token/

Аутентификация

Используйте базовую аутентификацию, закодировав consumer_key и consumer_secret в формате base64.

Заголовки запросов

Authorization: Basic base64(consumer_key:consumer_secret) # YycX3bGtsMnJfWH...
Content-Type: application/json

Тело запроса

{
    "grant_type": "password",
    "username": "some-username",
    "password": "strong-password"
}

Шаг 1. Подготовьте базовую авторизацию

Объедините свой потребительский ключ и потребительский секрет в следующем формате:

consumer_key:consumer_secret

Затем закодируйте это значение в base64.

Шаг 2. Отправьте запрос токена

Пример запроса

curl -X POST "https://{BASE_URL}/merchant/oauth2/token/"   
-H "Authorization: Basic <BASE64_CONSUMER_KEY_AND_SECRET>"   
-H "Content-Type: application/json"   
-d "grant_type=password&username=my_username&password=secure_password_123"

Успешный ответ 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "refresh_abc123def456ghi789jkl012mno345pqr",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 604800
}

Объяснение ответа

• access_token — токен для запросов API, действителен 1 час.
• refresh_token — токен, используемый для получения нового токена доступа, действителен в течение 7 дней.
• expires_in — время жизни токена доступа в секундах
• refresh_expires_in — обновить время жизни токена в секундах

Ответ об ошибке 401 Unauthorized

{
  "error": "invalid_grant",
  "error_description": "Invalid credentials or this account not activated"
}

---

3. Выполнение запросов API с токеном доступа

Использование токена доступа

Включите токен доступа в заголовок Authorization каждого запроса API.

Формат заголовка

Authorization: Bearer YOUR_ACCESS_TOKEN

Пример запроса

curl -X GET "https://{BASE_URL}/merchant/status/"   # example endpoint
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

---

4. Обновление токена доступа

Когда срок действия вашего токена доступа истечет, используйте токен обновления, чтобы получить новый. Вам не нужно повторно отправлять имя пользователя и пароль.

Конечная точка

POST {BASE_URL}/merchant/oauth2/token/

Заголовки запросов

Authorization: Basic base64(consumer_key:consumer_secret)
Content-Type: application/json

Тело запроса

{
"grant_type": refresh_token,
"refresh_token": "refresh_abc123def456ghi789jkl012mno345pqr"
}

Пример запроса

curl -X POST "https://{BASE_URL}/merchant/oauth2/token/"   
-H "Authorization: Basic <BASE64_CONSUMER_KEY_AND_SECRET>"   
-H "Content-Type: application/json"   
-d "grant_type=refresh_token&refresh_token=refresh_abc123def456ghi789jkl012mno345pqr"

Успешный ответ

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "refresh_xyz789abc123def456ghi789jkl012mno",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 604800
}

---

5. Отзыв токенов

Вы можете отозвать токен, чтобы предотвратить его дальнейшее использование.

Конечная точка

POST {BASE_URL}/merchant/oauth2/revoke/

Заголовки запросов

Content-Type: application/json

Тело запроса

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Пример запроса

curl -X POST "https://{BASE_URL}/merchant/oauth2/revoke/"   
  -H "Content-Type: application/json"   
  -d '{
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Успешный ответ 200 OK

{
  "status": "success"
}

---

6. Обработка ошибок

400 Bad Request

{
  "error": "invalid_request",
  "error_description": "Basic authorization header required"
}

Причина:

Заголовок авторизации отсутствует или имеет неверный формат.

401 Unauthorized

{
  "error": "invalid_grant",
  "error_description": "Invalid credentials"
}

Причина:

Имя пользователя, пароль, потребительский ключ или потребительский секрет неверны.

400 Invalid or Expired Token

{
  "error": "invalid_or_expired"
}

Причина:

Срок действия токена истек или он недействителен. Получите новый токен.

---

7. Краткий справочник

API конечные точки

Метод	Конечная точка	Цель
GET	/merchant/onboard	Проверить токен регистрации
POST	/merchant/onboard	Полная адаптация
POST	/merchant/oauth2/token/	Получить или обновить токен доступа
POST	/merchant/oauth2/revoke/	Отозвать токен

Коды ошибок

Ошибка	Описание
invalid_request	Запрос имеет неверный формат
invalid_client	Потребительский ключ недействителен
invalid_grant	Учетные данные недействительны
unsupported_grant_type	Тип гранта не поддерживается
invalid_or_expired	Токен недействителен или срок его действия истек
token_required	Параметр токена отсутствует