Руководство по API поставщика: Обработка ручных заказов

Предварительные требования

Перед началом убедитесь, что у вас есть:

• Аккаунт поставщика с доступом к API
• Ваш API-ключ (его можно сгенерировать в панели поставщика)
• Доступ к конечным точкам Admin API v2

Шаг 1: Получите свой API-ключ

1. Войдите в панель поставщика
2. Перейдите в раздел "Настройки API" (/api-settings)
3. Нажмите "Сгенерировать API-ключ", если у вас его нет
4. Скопируйте API-ключ и храните его в безопасности

Важно: Ваш API-ключ должен храниться в секрете. Никогда не публикуйте его открыто и не помещайте в систему контроля версий.

Шаг 2: Получите ручные заказы

Используйте конечную точку GET /api/admin/v2/orders для получения ожидающих и обрабатываемых ручных заказов.

API-запрос

curl -X GET "https://your-domain.com/api/admin/v2/orders?status=pending,processing&productType=manual&limit=50&offset=0" \
  -H "X-Api-Key: YOUR_API_KEY"

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

• status (необязательно): Фильтр статуса заказа. Поддерживает значения, разделенные запятыми: pending,processing
• productType (обязательно для ручных заказов): Установите значение manual
• entityType (необязательно): Фильтр по product или smm_service
• subCategory (необязательно): Фильтр по названию подкатегории
• limit (необязательно): Количество возвращаемых заказов (макс. 500, по умолчанию 50)
• offset (необязательно): Смещение пагинации (по умолчанию 0)

Пример ответа

{
  "orders": [
    {
      "id": 12345,
      "order": 12345,
      "status": "pending",
      "paymentStatus": "completed",
      "quantity": 10,
      "user": {
        "id": "507f1f77bcf86cd799439011",
        "email": "customer@example.com",
        "name": "John Doe"
      },
      "items": [
        {
          "product": {
            "id": "507f1f77bcf86cd799439012",
            "name": "Instagram Followers",
            "type": "product"
          },
          "quantity": 10,
          "unitPrice": 5.00,
          "totalPrice": 50.00
        }
      ],
      "createdAt": "2024-01-01T10:00:00.000Z"
    }
  ],
  "count": 1,
  "total": 1
}

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

• Возвращаются только заказы с paymentStatus: "completed"
• Заказы фильтруются для предотвращения повторной обработки (интервал 30 минут)
• Вы можете видеть только заказы на товары/услуги, которые принадлежат вам как поставщику

Шаг 3: Обработайте заказы и отправьте аккаунты

После получения заказов обработайте их и подготовьте учетные данные аккаунтов. Затем используйте конечную точку POST /api/admin/v2/orders-update для отправки аккаунтов и обновления статуса заказа.

API-запрос

curl -X POST "https://your-domain.com/api/admin/v2/orders-update" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order": 12345,
    "status": "completed",
    "accounts": [
      "username1:password1",
      "username2:password2",
      "username3:password3"
    ],
    "supplierOrderId": "SUP-ORDER-12345"
  }'

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

• order (обязательно): ID заказа (число)
• status (необязательно): Новый статус заказа. Допустимые значения: pending, processing, completed, partial, cancelled, error
• accounts (необязательно, для заказов товаров): Массив учетных данных аккаунтов в формате "username:password" или "email:password"
• supplierOrderId (необязательно): Ваш внутренний ID заказа для отслеживания

Формат аккаунта

Для заказов товаров аккаунты должны быть предоставлены в виде массива строк. Каждая строка представляет один аккаунт:

• Формат: "username:password" или "email:password"
• Пример: ["user1:pass123", "user2:pass456"]
• Количество: Предоставьте аккаунты, соответствующие количеству заказа

Полный пример рабочего процесса

Вот полный пример с использованием JavaScript/Node.js:

const axios = require('axios');

const API_BASE_URL = 'https://your-domain.com/api/admin/v2';
const API_KEY = 'YOUR_API_KEY';

// Шаг 1: Получить ожидающие и обрабатываемые ручные заказы
async function getOrders() {
  try {
    const response = await axios.get(`${API_BASE_URL}/orders`, {
      params: {
        status: 'pending,processing',
        productType: 'manual',
        limit: 50,
        offset: 0
      },
      headers: {
        'X-Api-Key': API_KEY
      }
    });
    
    return response.data.orders;
  } catch (error) {
    console.error('Ошибка получения заказов:', error.response?.data || error.message);
    throw error;
  }
}

// Шаг 2: Обработать заказ и отправить аккаунты
async function updateOrder(orderId, accounts, supplierOrderId) {
  try {
    const response = await axios.post(
      `${API_BASE_URL}/orders-update`,
      {
        order: orderId,
        status: 'completed',
        accounts: accounts,
        supplierOrderId: supplierOrderId
      },
      {
        headers: {
          'X-Api-Key': API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Ошибка обновления заказа:', error.response?.data || error.message);
    throw error;
  }
}

// Основной рабочий процесс
async function processOrders() {
  try {
    // Получить заказы
    const orders = await getOrders();
    console.log(`Найдено ${orders.length} заказов для обработки`);
    
    // Обработать каждый заказ
    for (const order of orders) {
      console.log(`Обработка заказа ${order.id}...`);
      
      // Подготовить аккаунты (здесь вы должны получить их из своей системы)
      const accounts = [
        'user1:pass1',
        'user2:pass2',
        // ... больше аккаунтов, соответствующих order.quantity
      ];
      
      // Обновить заказ с аккаунтами и отметить как выполненный
      const updatedOrder = await updateOrder(
        order.id,
        accounts,
        `SUP-${order.id}`
      );
      
      console.log(`Заказ ${order.id} успешно выполнен`);
    }
  } catch (error) {
    console.error('Ошибка в рабочем процессе:', error);
  }
}

// Запустить рабочий процесс
processOrders();

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

Распространенные ошибки

1. Неверный API-ключ

   {
         "error": "INVALID_API_KEY",
         "message": "Invalid API key"
       }

   Решение: Проверьте, что ваш API-ключ корректен и активен.

2. Заказ не найден

   {
         "error": "ORDER_NOT_FOUND",
         "message": "Order not found"
       }

   Решение: Убедитесь, что ID заказа существует и принадлежит вам.

3. Доступ запрещен

   {
         "error": "ACCESS_DENIED",
         "message": "You do not have access to this order"
       }

   Решение: Убедитесь, что заказ содержит товары/услуги, которые принадлежат вам.

4. Неверные аккаунты

   {
         "error": "INVALID_ACCOUNTS",
         "message": "No valid accounts provided after deduplication"
       }

   Решение: Убедитесь, что массив аккаунтов не пуст и содержит корректные строки.

Лучшие практики

1. Частота опроса: Не опрашивайте слишком часто. API предотвращает дублирование обработки с интервалом в 30 минут.
2. Обработка ошибок: Всегда реализуйте правильную обработку ошибок и логику повторных попыток.
3. Проверка аккаунтов: Проверяйте аккаунты перед отправкой, чтобы убедиться, что они в правильном формате.
4. Отслеживание заказов: Используйте supplierOrderId для отслеживания заказов в вашей системе.
5. Обновление статусов: Вы можете обновлять статус поэтапно:
   • Сначала установите processing, когда начинаете работу над заказом
   • Затем установите completed, когда аккаунты готовы
6. Частичные заказы: Если вы можете выполнить только часть заказа, установите статус partial и отправьте доступные аккаунты.

Резюме

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

1. Получение заказов: GET /api/admin/v2/orders?status=pending,processing&productType=manual
2. Обработка заказов: Подготовка аккаунтов для каждого заказа
3. Отправка аккаунтов: POST /api/admin/v2/orders-update с аккаунтами и status: "completed"

Этот простой трехэтапный процесс позволяет полностью автоматизировать рабочий процесс выполнения заказов!

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