API Documentation

Интегрируйте ReturnTrace в вашу систему

Полная документация для разработчиков с примерами запросов и ответов

Содержание

Авторизация

ReturnTrace API использует API ключи для авторизации запросов. Каждый API ключ связан с учетной записью пользователя и имеет полный доступ к данным этой учетной записи.

Как получить API ключ

  1. Авторизуйтесь в личном кабинете ReturnTrace
  2. Перейдите в раздел «Настройки»
  3. В разделе «Настройки» введите «API Ключ WB»
  4. В разделе «Настройки» найдите «API Ключ доступа»
  5. Скопируйте ключ и сохраните его в безопасном месте
⚠️ Важно: Никогда не делитесь вашим 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 коинов на счете.

Параметры запроса

Параметр
Тип
Обязательный
Описание
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 (глобальный номер товара)
sgitin
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://cdn.wbreturns.ru/photo1.jpg",
	 "c246x328": "https://cdn.wbreturns.ru/photo2.jpg",
	 "c516x688": "https://cdn.wbreturns.ru/photo3.jpg",
	 "square": "https://cdn.wbreturns.ru/photo4.jpg",
	 "tm": "https://cdn.wbreturns.ru/photo5.jpg"
	}
   ],
    "sizes": [
	{
	 techSize: "XL",
	 wbSize: "50"
	}
   ],
    "characteristics": [
	{
	 "name": "Цвет",
	 "value": "Красный"
	}
   ],
    "imei": null,
    "uin": "UIN12345678",
    "gtin": "5901234123457",
    "sgitin": "01901234512345210000",
    "expiration": null
  }
}

Коды ошибок

Код
Статус
Описание
INSUFFICIENT_COINS
402
Недостаточно коинов TRC на счете для выполнения запроса
INVALID_PHOTO
400
Неверный формат фото. Допускаются JPG и JPEG в формате Base64
PHOTO_REQUIRED
400
Параметр photo обязателен
QR_NOT_FOUND
422
QR код не найден на фотографии
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/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) на счете для выполнения операции
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 коинов в личном кабинете
  • 429 ошибка: Подождите указанное в retry_after время и повторите запрос
  • 5xx ошибки: Повторите запрос через несколько секунд (рекомендуется экспоненциальная задержка с jitter)

Нужна помощь?

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

Написать в поддержку На главную