2.1 Общее описание

2.1.1 Адрес доступа

Тестовая среда
Рабочая среда	https://api.racent.com/

2.1.2 Аутентификация подписи интерфейса

Интерфейс использует механизм аутентификации на основе API-подписи, что обеспечивает целостность и безопасность запросов. При каждом вызове интерфейса необходимо передавать параметры подписи, сервер проверяет корректность подписи.

Общие параметры

Следующие параметры обязательно должны быть включены в Query String каждого запроса к интерфейсу:

Название параметра	Тип параметра	Описание	Пример значения
access_key	String	ID аккаунта, используется для идентификации вызывающей стороны	1000000059
signature_nonce	String	Уникальное случайное число подписи, используется для предотвращения атак повторного воспроизведения, при каждом запросе необходимо использовать разные случайные значения	2206561-6450-430e-8b0a-26980754c0de
timestamp	String	Метка времени отправки запроса (в секундах)	1673418729
signature_version	String	Версия алгоритма подписи, фиксированно 1.0	1.0
signature_method	String	Алгоритм подписи, фиксированно md5	md5
signature	String	Значение подписи данного запроса, вычисляется из других параметров и секретного ключа	85ef54421c69edeb098c7b557c6c5cd5

Примечание:

• access_key и AccessSecret (секретный ключ) можно получить после входа в систему в разделе Управление интерфейсами — Учётные данные доступа API.

• signature_nonce Рекомендуется использовать UUID или достаточно случайную строку, чтобы каждый запрос был уникальным.
• timestamp Запросы, время которых отличается от времени сервера более чем на определённый диапазон (например, 5 минут), будут отклонены. :::

---

Механизм подписи

Шаг 1. Формирование канонической строки запроса

1. Сортировка параметров

Отсортируйте все общие параметры (кроме signature) и пользовательские параметры интерфейса в лексикографическом порядке по возрастанию имён параметров.

2. Кодирование параметров

Имя и значение каждого параметра кодируются в UTF-8 и подвергаются URL-кодированию по правилам RFC3986:

• Символы, которые не кодируются: A-Z a-z 0-9 - _ . ~
• Другие символы (например, пробел, /, ?, = и т. д.) должны быть закодированы в формате %XX, например пробел кодируется как %20

3. Объединение параметров

• Соедините закодированное имя параметра и его значение знаком =
• Соедините все пары параметров знаком &, сохраняя лексикографический порядок

Полученная строка называется stringToSign.

---

Шаг 2. Формирование строки подписи и вычисление подписи

В зависимости от типа запроса подпись вычисляется следующим образом:

GET 请求

signature = md5(AccessSecret + md5( HTTPMethod + stringToSign ))

POST / PUT 请求（含 Body 参数）

signature = md5(AccessSecret + md5( HTTPMethod + stringToSign ) + md5( jsonStringToBody ))

Примечание:

• HTTPMethod должен быть в верхнем регистре, например GET, POST
• jsonStringToBody — это исходная JSON-строка тела запроса (необходимо удалить пробелы и переводы строк, а поля отсортировать)
• Знак + в формуле означает конкатенацию строк, а не арифметическое сложение

Правила кодирования параметров (RFC3986)

Тип символов	Способ обработки	Пример
A-Z, a-z, 0-9, -, _, ., ~	Не кодировать	abc123 → abc123
Пробел	Кодируется как %20	a b → a%20b
Другие символы ASCII	Кодируются как %XX (шестнадцатеричный формат)	" → %22

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

Предположим:

• access_key = "1000000059"
• AccessSecret = "19938c89c13ddf5da7636333a5aa4c0e"
• signature_nonce = "iobzx72w63"
• timestamp = "1755597512"

Шаг 1: Сформируйте stringToSign

access_key=1000000059&signature_method=md5&signature_nonce=iobzx72w63&signature_version=1.0&timestamp=1755597512

Шаг 2: Вычисление подписи

temp = md5("GET" + stringToSign)  // 结果为"9bc92e0f3e239dc628ebc416294422ba"
signature = md5(AccessSecret + temp)  // 结果为"a33bdb81ea79eb4ebbac9da043309c00"

Итоговый URL запроса:

https://api.racent.com/api/v1/domain/tld?access_key=1000000059&signature_nonce=iobzx72w63&timestamp=1755597512&signature_version=1.0&signature_method=md5&signature=a33bdb81ea79eb4ebbac9da043309c00

---

Пример POST-запроса (с телом)

Предположим, тело запроса:

{"domain":"example.com"}

Его MD5-значение: 640c69595341436be9b0d1516d3d37ac

Шаг 1: Сформируйте stringToSign

access_key=1000000059&signature_method=md5&signature_nonce=abjipo5ar5a&signature_version=1.0&timestamp=1755598851

Шаг 2: Вычислить подпись

temp = md5("POST" + stringToSign)  // 结果为 "5aba63e4af1b7a4080eaf47d0fc56efe"
signature = md5(AccessSecret + temp + "640c69595341436be9b0d1516d3d37ac")  // 结果为 "29487fd8ae5b828415d05b691caf015c"

Итоговый URL запроса:

https://api.racent.com/v1/domain/query-domain?access_key=1000000059&signature_nonce=abjipo5ar5a&timestamp=1755598851&signature_version=1.0&signature_method=md5&signature=29487fd8ae5b828415d05b691caf015c

2.1.3 Ограничение частоты запросов к интерфейсу

Правила ограничения по умолчанию: для одного и того же пользователя, обращающегося к одному и тому же интерфейсу, действуют следующие лимиты:

• 60 раз в минуту
• 500 раз в час
• 1000 раз в день

2.1.4 Параметры ответа интерфейса

Описание параметров

Название параметра	Тип параметра	Описание	Пример значения
data	Object	Бизнес-данные; если интерфейс возвращает ошибку, значение равно null
code	Int	Код ошибки: при успехе возвращается 0, при ошибке — соответствующий код ошибки	0, 1000, 1001
message	String	Сообщение об ошибке; при успешном выполнении интерфейс возвращает "Success"	over-rate-limit
errors	Object	При некоторых ошибках через это поле предоставляется более подробное описание ошибки
request_id	String	Идентификатор запроса, в основном используется для помощи при диагностике проблем	039ecdca-44d5-430f-8521-020f4953bcc5