Guía de la API del Proveedor: Procesamiento de Pedidos Manuales

Requisitos Previos

Antes de comenzar, asegúrate de tener:

• Una cuenta de proveedor con acceso a la API
• Tu clave API (puedes generarla desde tu panel de proveedor)
• Acceso a los endpoints de la API de Administración v2

Paso 1: Obtén Tu Clave API

1. Inicia sesión en tu panel de proveedor
2. Navega a Configuración de API (/api-settings)
3. Haz clic en "Generar Clave API" si no tienes una
4. Copia tu clave API y mantenla segura

Importante: Tu clave API debe mantenerse en secreto. Nunca la compartas públicamente ni la incluyas en control de versiones.

Paso 2: Obtener Pedidos Manuales

Usa el endpoint GET /api/admin/v2/orders para obtener pedidos manuales pendientes y en proceso.

Solicitud 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"

Parámetros de la Solicitud

• status (opcional): Filtro de estado del pedido. Admite valores separados por comas: pending,processing
• productType (requerido para pedidos manuales): Establecer a manual
• entityType (opcional): Filtrar por product o smm_service
• subCategory (opcional): Filtrar por nombre de subcategoría
• limit (opcional): Número de pedidos a devolver (máx. 500, predeterminado 50)
• offset (opcional): Desplazamiento de paginación (predeterminado 0)

Ejemplo de Respuesta

{
  "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
}

Notas Importantes

• Solo se devuelven pedidos con paymentStatus: "completed"
• Los pedidos se filtran para evitar procesamiento duplicado (intervalo de 30 minutos)
• Solo puedes ver pedidos para productos/servicios que te pertenecen como proveedor

Paso 3: Procesar Pedidos y Enviar Cuentas

Una vez que tengas los pedidos, procésalos y prepara las credenciales de las cuentas. Luego usa el endpoint POST /api/admin/v2/orders-update para enviar las cuentas y actualizar el estado del pedido.

Solicitud 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"
  }'

Parámetros del Cuerpo de la Solicitud

• order (requerido): El ID del pedido (número)
• status (opcional): Nuevo estado del pedido. Valores válidos: pending, processing, completed, partial, cancelled, error
• accounts (opcional, para pedidos de productos): Array de credenciales de cuenta en formato "username:password" o "email:password"
• supplierOrderId (opcional): Tu ID de pedido interno para seguimiento

Formato de Cuenta

Para pedidos de productos, las cuentas deben proporcionarse como un array de cadenas. Cada cadena representa una cuenta:

• Formato: "username:password" o "email:password"
• Ejemplo: ["user1:pass123", "user2:pass456"]
• Cantidad: Proporciona cuentas que coincidan con la cantidad del pedido

Ejemplo de Flujo de Trabajo Completo

Aquí hay un ejemplo completo usando JavaScript/Node.js:

const axios = require('axios');

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

// Paso 1: Obtener pedidos manuales pendientes y en proceso
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 al obtener pedidos:', error.response?.data || error.message);
    throw error;
  }
}

// Paso 2: Procesar pedido y enviar cuentas
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 al actualizar el pedido:', error.response?.data || error.message);
    throw error;
  }
}

// Flujo de trabajo principal
async function processOrders() {
  try {
    // Obtener pedidos
    const orders = await getOrders();
    console.log(`Se encontraron ${orders.length} pedidos para procesar`);
    
    // Procesar cada pedido
    for (const order of orders) {
      console.log(`Procesando pedido ${order.id}...`);
      
      // Preparar cuentas (aquí es donde obtendrías de tu sistema)
      const accounts = [
        'user1:pass1',
        'user2:pass2',
        // ... más cuentas que coincidan con order.quantity
      ];
      
      // Actualizar pedido con cuentas y marcarlo como completado
      const updatedOrder = await updateOrder(
        order.id,
        accounts,
        `SUP-${order.id}`
      );
      
      console.log(`Pedido ${order.id} completado exitosamente`);
    }
  } catch (error) {
    console.error('Error en el flujo de trabajo:', error);
  }
}

// Ejecutar el flujo de trabajo
processOrders();

Manejo de Errores

Errores Comunes

1. Clave API Inválida

   {
         "error": "INVALID_API_KEY",
         "message": "Clave API inválida"
       }

   Solución: Verifica que tu clave API sea correcta y esté activa.

2. Pedido No Encontrado

   {
         "error": "ORDER_NOT_FOUND",
         "message": "Pedido no encontrado"
       }

   Solución: Verifica que el ID del pedido exista y te pertenezca.

3. Acceso Denegado

   {
         "error": "ACCESS_DENIED",
         "message": "No tienes acceso a este pedido"
       }

   Solución: Asegúrate de que el pedido contenga productos/servicios que te pertenezcan.

4. Cuentas Inválidas

   {
         "error": "INVALID_ACCOUNTS",
         "message": "No se proporcionaron cuentas válidas después de la deduplicación"
       }

   Solución: Asegúrate de que el array de cuentas no esté vacío y contenga cadenas válidas.

Mejores Prácticas

1. Frecuencia de Consulta: No consultes con demasiada frecuencia. La API evita el procesamiento duplicado con un intervalo de 30 minutos.
2. Manejo de Errores: Implementa siempre un manejo de errores adecuado y lógica de reintento.
3. Validación de Cuentas: Valida las cuentas antes de enviarlas para asegurarte de que estén en el formato correcto.
4. Seguimiento de Pedidos: Usa supplierOrderId para rastrear pedidos en tu sistema.
5. Actualizaciones de Estado: Puedes actualizar el estado de forma incremental:
   • Primero configúralo como processing cuando empieces a trabajar en él
   • Luego configúralo como completed cuando las cuentas estén listas
6. Pedidos Parciales: Si solo puedes completar parte de un pedido, establece el estado como partial y envía las cuentas disponibles.

Resumen

El flujo de trabajo completo es:

1. Obtener Pedidos: GET /api/admin/v2/orders?status=pending,processing&productType=manual
2. Procesar Pedidos: Prepara las cuentas para cada pedido
3. Enviar Cuentas: POST /api/admin/v2/orders-update con las cuentas y status: "completed"

¡Este sencillo proceso de tres pasos te permite automatizar completamente tu flujo de trabajo de cumplimiento de pedidos!

Ambas son guías de documentación central para proveedores. Vincularlas ayuda a los proveedores a navegar desde la configuración del producto hasta el procesamiento de pedidos, creando un flujo de trabajo lógico. guía de gestión de productos.