Guia da API do Fornecedor: Processamento de Pedidos Manuais

Pré-requisitos

Antes de começar, certifique-se de ter:

• Uma conta de fornecedor com acesso à API
• Sua chave de API (você pode gerá-la no painel do fornecedor)
• Acesso aos endpoints da Admin API v2

Passo 1: Obtenha sua Chave de API

1. Faça login no painel do fornecedor
2. Navegue até Configurações de API (/api-settings)
3. Clique em "Gerar Chave de API" se você não tiver uma
4. Copie sua chave de API e mantenha-a segura

Importante: Sua chave de API deve ser mantida em segredo. Nunca a compartilhe publicamente ou a envie para o controle de versão.

Passo 2: Obtenha Pedidos Manuais

Use o endpoint GET /api/admin/v2/orders para buscar pedidos manuais pendentes e em processamento.

Solicitação da API

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

Parâmetros da Solicitação

• status (opcional): Filtro de status do pedido. Aceita valores separados por vírgula: pending,processing
• productType (obrigatório para pedidos manuais): Defina como manual
• entityType (opcional): Filtre por product ou smm_service
• subCategory (opcional): Filtre por nome da subcategoria
• limit (opcional): Número de pedidos a retornar (máx. 500, padrão 50)
• offset (opcional): Deslocamento de paginação (padrão 0)

Exemplo de Resposta

{
  "orders": [
    {
      "id": 12345,
      "order": 12345,
      "status": "pending",
      "paymentStatus": "completed",
      "quantity": 10,
      "user": {
        "id": "507f1f77bcf86cd799439011",
        "email": "cliente@exemplo.com",
        "name": "João Silva"
      },
      "items": [
        {
          "product": {
            "id": "507f1f77bcf86cd799439012",
            "name": "Seguidores Instagram",
            "type": "product"
          },
          "quantity": 10,
          "unitPrice": 5.00,
          "totalPrice": 50.00
        }
      ],
      "createdAt": "2024-01-01T10:00:00.000Z"
    }
  ],
  "count": 1,
  "total": 1
}

Notas Importantes

• Apenas pedidos com paymentStatus: "completed" são retornados
• Os pedidos são filtrados para evitar processamento duplicado (intervalo de 30 minutos)
• Você só pode ver pedidos de produtos/serviços que pertencem a você como fornecedor

Passo 3: Processe Pedidos e Envie Contas

Depois de obter os pedidos, processe-os e prepare as credenciais das contas. Em seguida, use o endpoint POST /api/admin/v2/orders-update para enviar contas e atualizar o status do pedido.

Solicitação da API

curl -X POST "https://seu-dominio.com/api/admin/v2/orders-update" \
  -H "X-Api-Key: SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "order": 12345,
    "status": "completed",
    "accounts": [
      "usuario1:senha1",
      "usuario2:senha2",
      "usuario3:senha3"
    ],
    "supplierOrderId": "SUP-PEDIDO-12345"
  }'

Parâmetros do Corpo da Solicitação

• order (obrigatório): O ID do pedido (número)
• status (opcional): Novo status do pedido. Valores válidos: pending, processing, completed, partial, cancelled, error
• accounts (opcional, para pedidos de produtos): Array de credenciais de conta no formato "usuario:senha" ou "email:senha"
• supplierOrderId (opcional): Seu ID de pedido interno para rastreamento

Formato da Conta

Para pedidos de produtos, as contas devem ser fornecidas como um array de strings. Cada string representa uma conta:

• Formato: "usuario:senha" ou "email:senha"
• Exemplo: ["user1:senha123", "user2:senha456"]
• Quantidade: Forneça contas correspondentes à quantidade do pedido

Exemplo de Fluxo de Trabalho Completo

Aqui está um exemplo completo usando JavaScript/Node.js:

const axios = require('axios');

const API_BASE_URL = 'https://seu-dominio.com/api/admin/v2';
const API_KEY = 'SUA_CHAVE_API';

// Passo 1: Obter pedidos manuais pendentes e em processamento
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('Erro ao buscar pedidos:', error.response?.data || error.message);
    throw error;
  }
}

// Passo 2: Processar pedido e enviar contas
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('Erro ao atualizar pedido:', error.response?.data || error.message);
    throw error;
  }
}

// Fluxo de trabalho principal
async function processOrders() {
  try {
    // Obter pedidos
    const orders = await getOrders();
    console.log(`Encontrados ${orders.length} pedidos para processar`);
    
    // Processar cada pedido
    for (const order of orders) {
      console.log(`Processando pedido ${order.id}...`);
      
      // Preparar contas (aqui você buscaria do seu sistema)
      const accounts = [
        'user1:senha1',
        'user2:senha2',
        // ... mais contas correspondentes a order.quantity
      ];
      
      // Atualizar pedido com contas e marcar como concluído
      const updatedOrder = await updateOrder(
        order.id,
        accounts,
        `SUP-${order.id}`
      );
      
      console.log(`Pedido ${order.id} concluído com sucesso`);
    }
  } catch (error) {
    console.error('Erro no fluxo de trabalho:', error);
  }
}

// Executar o fluxo de trabalho
processOrders();

Tratamento de Erros

Erros Comuns

1. Chave de API Inválida

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

   Solução: Verifique se sua chave de API está correta e ativa.

2. Pedido Não Encontrado

   {
         "error": "ORDER_NOT_FOUND",
         "message": "Pedido não encontrado"
       }

   Solução: Verifique se o ID do pedido existe e pertence a você.

3. Acesso Negado

   {
         "error": "ACCESS_DENIED",
         "message": "Você não tem acesso a este pedido"
       }

   Solução: Certifique-se de que o pedido contém produtos/serviços que pertencem a você.

4. Contas Inválidas

   {
         "error": "INVALID_ACCOUNTS",
         "message": "Nenhuma conta válida fornecida após deduplicação"
       }

   Solução: Certifique-se de que o array de contas não está vazio e contém strings válidas.

Melhores Práticas

1. Frequência de Consulta: Não consulte com muita frequência. A API evita processamento duplicado com um intervalo de 30 minutos.
2. Tratamento de Erros: Sempre implemente tratamento de erros adequado e lógica de repetição.
3. Validação de Contas: Valide as contas antes de enviar para garantir que estejam no formato correto.
4. Rastreamento de Pedidos: Use supplierOrderId para rastrear pedidos em seu sistema.
5. Atualizações de Status: Você pode atualizar o status incrementalmente:
   • Primeiro defina como processing quando começar a trabalhar
   • Depois defina como completed quando as contas estiverem prontas
6. Pedidos Parciais: Se você só puder atender parte de um pedido, defina o status como partial e envie as contas disponíveis.

Resumo

O fluxo de trabalho completo é:

1. Obter Pedidos: GET /api/admin/v2/orders?status=pending,processing&productType=manual
2. Processar Pedidos: Preparar contas para cada pedido
3. Enviar Contas: POST /api/admin/v2/orders-update com contas e status: "completed"

Este processo simples de três etapas permite automatizar completamente seu fluxo de trabalho de atendimento de pedidos!

Ambos são guias principais de documentação para fornecedores. Vinculá-los ajuda os fornecedores a navegar da configuração do produto ao processamento de pedidos, criando um fluxo de trabalho lógico. guia de gerenciamento de produtos.