API Documentation
Интегрируйте ReturnTrace в вашу систему
Полная документация для разработчиков с примерами запросов и ответов
Авторизация
ReturnTrace API использует API ключи для авторизации запросов. Каждый API ключ связан с учетной записью пользователя и имеет полный доступ к данным этой учетной записи.
Как получить API ключ
- Авторизуйтесь в личном кабинете ReturnTrace
- Перейдите в раздел «Настройки»
- В разделе «Настройки» введите «API Ключ WB»
- В разделе «Настройки» найдите «API Ключ доступа»
- Скопируйте ключ и сохраните его в безопасном месте
⚠️ Важно: Никогда не делитесь вашим API ключом и не публикуйте его в открытых репозиториях. Если ключ скомпрометирован, немедленно сгенерируйте новый в личном кабинете.
Способ передачи ключа
API ключ должен быть передан в заголовке Authorization каждого запроса:
HTTP Header
Authorization: Bearer YOUR_API_KEY
Пример с curl:
BASH
curl -X GET https://api.wbreturns.ru/request/info/balance \ -H "Authorization: Bearer YOUR_API_KEY"
Ограничения по запросам
Для обеспечения стабильности сервиса и справедливого распределения ресурсов, на API установлены ограничения по количеству запросов.
Лимит запросов
300
запросов в минуту
Период
60
секунд
Обработка
3-5
секунд на запрос
Проверка оставшихся запросов
Информацию о количестве оставшихся запросов можно получить из заголовков ответа:
Response Headers
X-RateLimit-Limit: 300 X-RateLimit-Remaining: 287 X-RateLimit-Reset: 1609459260
X-RateLimit-Limit- максимальное количество запросов в минутуX-RateLimit-Remaining- количество оставшихся запросов в текущей минутеX-RateLimit-Reset- время (Unix timestamp) сброса счетчика
Превышение лимита
При превышении лимита запросов API вернет ошибку 429 Too Many Requests:
JSON
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Превышено количество запросов. Максимум 300 запросов в минуту.",
"retry_after": 15
}
}
В поле retry_after указано количество секунд, через которое можно повторить запрос.
Получение информации о возврате WB
POST
https://api.wbreturns.ru/request/info/returns
Метод позволяет отправить фотографию этикетки возврата (в формате Base64) и получить подробную информацию о товаре и заказе из базы данных Wildberries.
ℹ️ Примечание: Обработка фото занимает 3-5 секунд. Метод требует авторизации и наличие TRC коинов на счете.
ℹ️ Примечание: В разделе «Настройки» личного кабинета введите «API Ключ WB»
Параметры запроса
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| photo | string (base64) | Да | Фотография этикетки возврата в формате Base64 (JPG или JPEG) |
Пример запроса
curl
curl -X POST https://api.wbreturns.ru/request/info/returns \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"photo": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}'
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| orderId | integer | Номер заказа отгрузки |
| barcode_sku | string | Штрихкод товара |
| vendorCode | string | Артикул товара |
| brand | string | Бренд товара |
| title | string | Наименование товара |
| photos | array of objects | Массив фото товара (URL) |
| sizes | array of objects | Размер товара |
| characteristics | array of objects | Характеристики товара |
| imei | string | IMEI код устройства (если применимо) |
| uin | string | УИН (уникальный идентификационный номер) |
| gtin | string | GTIN (глобальный номер товара) |
| sgtin | string | КМ-КИЗ (код маркировки) |
| expiration | date (dd.mm.yyyy) | Срок годности товара |
Пример успешного ответа (200 OK)
JSON
{
"success": true,
"data": {
"orderId": 123456789,
"barcode_sku": "2000012345678",
"vendorCode": "ABC123",
"brand": "Nike",
"title": "Кроссовки спортивные",
"photos": [
{
"big": "https://...",
"c246x328": "https://...",
"c516x688": "https://...",
"square": "https://...",
"tm": "https://..."
}
],
"sizes": [
{
"techSize": "XL",
"wbSize": "50"
}
],
"characteristics": [
{
"name": "Цвет",
"value": "Красный"
}
],
"imei": null,
"uin": "UIN12345678",
"gtin": "5901234123457",
"sgtin": "01901234512345210000",
"expiration": null
}
}
Коды ошибок
| Код | Статус | Описание |
|---|---|---|
| INSUFFICIENT_COINS | 402 | Недостаточно коинов TRC на счете для выполнения запроса |
| WB_API_NOT_FOUND | 402 | Не указан WB API key в личном кабинете |
| INVALID_PHOTO | 400 | Неверный формат фото. Допускаются JPG и JPEG в формате Base64 |
| PHOTO_REQUIRED | 400 | Параметр photo обязателен |
| QR_NOT_FOUND | 422 | QR код или метка WB не найдены на фотографии |
| WB_DATA_NOT_FOUND | 404 | Товар или заказ не найдены в базе Wildberries |
| PROCESSING_ERROR | 500 | Внутренняя ошибка при обработке фото. Повторите запрос позже |
Примеры ошибок
Ошибка: Недостаточно коинов
JSON
{
"success": false,
"error": {
"code": "INSUFFICIENT_COINS",
"message": "Недостаточно коинов TRC. Требуется минимум 1 TRC"
}
}
Ошибка: Неверный формат фото
JSON
{
"success": false,
"error": {
"code": "INVALID_PHOTO",
"message": "Неверный формат фото. Допускаются JPG и JPEG в формате Base64"
}
}
Получение истории идентификаций
GET
https://api.wbreturns.ru/request/info/history
Метод возвращает историю операций идентификации возвратов за указанный период (максимум 60 дней).
Параметры запроса
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| dateFrom | string (date) | Да | Начальная дата (YYYY-MM-DD) |
| dateTo | string (date) | Да | Конечная дата (YYYY-MM-DD) |
Пример запроса
curl
curl -X GET "https://api.wbreturns.ru/request/info/history?dateFrom=2026-01-13&dateTo=2026-01-27" \ -H "Authorization: Bearer YOUR_API_KEY"
Пример успешного ответа (200 OK)
JSON
{
"success": true,
"data": [
{
"status": "success",
"created_at": "2026-01-26T12:00:00+03:00",
"orderId": 123456789,
"barcode_sku": "2000012345678",
"vendorCode": "ABC123",
"brand": "Nike",
"title": "Кроссовки спортивные",
"photos": [
{
"big": "https://...",
"c246x328": "https://...",
"c516x688": "https://...",
"square": "https://...",
"tm": "https://..."
}
],
"sizes": [
{
"techSize": "XL",
"wbSize": "50"
}
],
"characteristics": [
{
"name": "Цвет",
"value": "Красный"
}
],
"imei": null,
"uin": "UIN12345678",
"gtin": "5901234123457",
"sgtin": "01901234512345210000",
"expiration": null
}
]
}
Получение информации о балансе
GET
https://api.wbreturns.ru/request/info/balance
Метод возвращает информацию о текущем балансе TRC коинов на счете пользователя. Используется для проверки возможности выполнения операций, требующих коинов.
ℹ️ Примечание: Метод требует авторизации через API ключ.
Параметры запроса
Метод не требует параметров в теле запроса. Авторизация передается через заголовок Authorization.
Пример запроса
curl
curl -X GET https://api.wbreturns.ru/request/info/balance \ -H "Authorization: Bearer YOUR_API_KEY"
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| trc_coins | integer | Количество доступных TRC коинов на счете |
Пример успешного ответа (200 OK)
JSON
{
"success": true,
"data": {
"trc_coins": 1500
}
}
Примеры ответов
Баланс больше нуля (успешно)
JSON
{
"success": true,
"data": {
"trc_coins": 500
}
}
Баланс равен нулю
JSON
{
"success": true,
"data": {
"trc_coins": 0
}
}
⚠️ Внимание: Если баланс равен 0, то вызов метода "Получение информации о возврате WB" вернет ошибку
INSUFFICIENT_COINS с сообщением "Недостаточно коинов TRC".
Коды ошибок
| Код | Статус | Описание |
|---|---|---|
| UNAUTHORIZED | 401 | Неверный или отсутствующий API ключ |
| FORBIDDEN | 403 | Доступ запрещен. Проверьте права доступа ключа |
Примеры ошибок
Ошибка: Неверный API ключ
JSON
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Неверный или отсутствующий API ключ"
}
}
Коды ошибок
Все ошибки API возвращаются в стандартном формате JSON с указанием кода ошибки и описания проблемы.
Общие коды ошибок
| Код | HTTP | Описание |
|---|---|---|
| BAD_REQUEST | 400 | Неверный формат запроса или отсутствуют обязательные параметры |
| UNAUTHORIZED | 401 | Отсутствует или неверен API ключ в заголовке Authorization |
| PAYMENT_REQUIRED | 402 | Недостаточно средств (коинов TRC) на счете для выполнения операции |
| WB_API_NOT_FOUND | 402 | Не указан WB API key в личном кабинете |
| FORBIDDEN | 403 | Доступ запрещен. Ключ не имеет прав для данной операции |
| NOT_FOUND | 404 | Запрошенный ресурс не найден |
| UNPROCESSABLE_ENTITY | 422 | Ошибка валидации данных или невозможность обработать запрос |
| RATE_LIMIT_EXCEEDED | 429 | Превышен лимит запросов (300 в минуту) |
| INTERNAL_ERROR | 500 | Внутренняя ошибка сервера. Повторите запрос позже |
| SERVICE_UNAVAILABLE | 503 | Сервис недоступен. Повторите запрос позже |
Формат ошибки
Все ошибки возвращаются в следующем формате:
JSON
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Описание ошибки на русском языке"
}
}
Рекомендации по обработке ошибок
- 400, 422 ошибки: Проверьте формат и корректность переданных параметров
- 401 ошибка: Убедитесь, что API ключ передан в заголовке
Authorization: Bearer YOUR_KEY - 402 ошибка: Пополните баланс TRC коинов в личном кабинете или укажите WB API key
- 429 ошибка: Подождите указанное в
retry_afterвремя и повторите запрос - 5xx ошибки: Повторите запрос через несколько секунд (рекомендуется экспоненциальная задержка с jitter)
Нужна помощь?
Если у вас возникли проблемы с интеграцией или у вас есть вопросы по API, свяжитесь с нашей службой поддержки.