Como usar a API do painel SMM: guia de integração da API v2 para revendedores

A API de um painel SMM é uma conexão que faz pedidos e confere o status deles automaticamente a partir de outro painel ou do seu próprio software. O 1PANEL PLUS usa a API v2 padrão de painel SMM, então, se você já tem um código conectado a outro painel, basta trocar o endereço e a chave para conectar na hora. A API e o site usam os mesmos serviços, os mesmos preços por 1,000 e o mesmo saldo.

Quem usa a API de um painel SMM?

• Revendedores: listam serviços no próprio painel e repassam os pedidos dos clientes automaticamente
• Agências: fazem pedidos para muitos canais de uma vez em horários definidos
• Desenvolvedores: criam scripts que fazem pedidos quando uma transmissão começa ou um vídeo novo é publicado
• Operadores: reúnem saldo e status dos pedidos no próprio painel de controle

Como consigo uma chave de API?

Crie uma na tela Chave de API do seu painel depois que sua primeira recarga for creditada. A chave é mostrada apenas uma vez, no momento em que você a cria, então copie-a na hora e guarde-a em um lugar seguro. Ao criar uma nova chave, a chave antiga para de funcionar imediatamente; se você achar que uma chave foi exposta, basta criar uma nova para substituí-la.

Como envio requisições à API?

Envie todas as requisições por POST para o endereço único https://1panelplus.com/api/v2. Use o formato que preferir, campos de formulário (application/x-www-form-urlencoded ou multipart) ou corpo JSON (Content-Type: application/json), e inclua key e action em todas as requisições. Todas as respostas são em JSON.

Exemplo de requisição (campos de formulário): key=YOUR_API_KEY&action=balance

Exemplo de requisição (JSON): {"key": "YOUR_API_KEY", "action": "balance"}

Como obtenho a lista de serviços com services?

Envie action=services e você recebe todos os serviços à venda em um array. Cada serviço inclui service (ID do serviço), name, type, category, rate, min, max, refill e cancel. rate é o preço por 1,000 (USD); quando type é Package, é o preço de um pacote. refill é true para serviços com período de reposição, e cancel é sempre false. category traz o nome da plataforma e a categoria juntos, então você pode recriar as categorias no seu próprio painel do jeito que estão.

Exemplo de resposta: [{"service": SERVICE_ID, "name": "Nome do serviço", "type": "Default", "category": "YouTube - Nome da categoria", "rate": "Preço por 1,000", "min": "Quantidade mínima", "max": "Quantidade máxima", "refill": true, "cancel": false}]

Preços e serviços podem mudar, então, como revendedor, é uma boa ideia buscar services de novo em um intervalo definido e manter sincronizados os preços e as quantidades mínima e máxima do seu painel.

Como faço um pedido com add?

Envie action=add com service (ID do serviço), link (link público) e quantity, e o pedido é feito e o valor é descontado do seu saldo na hora. O order na resposta é o ID do pedido; guarde-o e use-o em status e refill. Os pedidos podem ser feitos por contas cuja primeira recarga já foi creditada.

• Serviços comuns: envie service, link e quantity
• Serviços Custom Comments: envie comments em vez de quantity. Um comentário por linha, até 500 caracteres por linha, e o número de linhas é a quantidade
• Serviços Package: não é preciso enviar quantidade. O pedido é de um pacote

Exemplo de requisição: key=YOUR_API_KEY&action=add&service=SERVICE_ID&link=https://www.youtube.com/watch?v=videoid&quantity=1000

Exemplo de resposta: {"order": ORDER_ID}

Como confiro o status de um pedido com status?

Envie action=status com order (um único ID de pedido) para receber o status desse pedido, ou envie orders com IDs de pedidos separados por vírgulas para consultar até 100 de uma vez. Se você gerencia muitos pedidos, agrupá-los com orders economiza muitas requisições.

Exemplo de resposta (um pedido): {"charge": "Valor cobrado", "start_count": "Contagem inicial", "status": "In progress", "remains": "Quantidade restante", "currency": "USD"}

Exemplo de resposta (vários pedidos): {"ORDER_ID_1": {"charge": "...", "start_count": "...", "status": "Completed", "remains": "0", "currency": "USD"}, "ORDER_ID_2": {"error": "Incorrect order ID"}}

charge é o valor pago menos qualquer valor reembolsado, então, depois de um pedido parcial ou cancelado, você vê na hora o valor realmente gasto. Os status dos pedidos são atualizados automaticamente a cada minuto, aproximadamente, então consultar status em intervalos de cerca de um minuto é mais que suficiente.

Como uso refill e refill_status?

Envie action=refill com order para pedir uma reposição, e você recebe refill (o ID da reposição). Ela é aceita para pedidos concluídos ou concluídos parcialmente de serviços com período de reposição, dentro do período de reposição contado a partir do dia em que o pedido terminou, quando não há reposição em andamento e já se passaram 24 horas desde o último pedido de reposição. Envie action=refill_status com refill, e ele informa o status como Pending, In progress, Completed ou Rejected.

Exemplos de resposta: {"refill": REFILL_ID} e {"status": "Completed"}

As regras de reposição são as mesmas do site. As condições detalhadas estão em Períodos de reposição explicados.

Como confiro o meu saldo com balance?

Envie action=balance e você recebe o seu saldo atual e a moeda (USD). Como revendedor, confira o saldo antes de repassar os pedidos e configure um alerta para quando ele ficar abaixo de um valor definido, para que os seus pedidos sigam sem interrupção.

Exemplo de resposta: {"balance": "Saldo atual", "currency": "USD"}

O que significam as mensagens de erro da API?

Os erros voltam como JSON com uma frase em inglês no campo error. Cada frase tem uma causa fixa, então o seu software pode compará-la como está e tratá-la.

Os pedidos de reposição podem retornar Refill is not available for this service (o serviço não tem período de reposição), Order is not finished yet (o pedido ainda não terminou), Refill period has ended (o período de reposição já passou) ou Refill already requested, try again later (há uma reposição em andamento ou ainda não se passaram 24 horas).

Quantas requisições à API posso enviar?

Cada chave pode fazer até 300 requisições por minuto. Agrupe as consultas de status em lotes de 100 com orders e busque a lista de serviços de novo só quando precisar, e você terá folga de sobra. Por exemplo, com 1,000 pedidos em andamento, 10 requisições uma vez por minuto conferem todos eles.

Como os revendedores definem os preços de venda?

O rate que você recebe pela API é o preço por 1,000 do 1PANEL PLUS, e os revendedores definem eles mesmos o preço de venda no próprio painel. Por exemplo, se você adicionar 25% a um serviço com rate de $2.00, você vende a $2.50 por 1,000; quando um cliente pede 4,000, a sua venda é $10.00 e $8.00 é descontado no 1PANEL PLUS. Esses preços são exemplos para mostrar o cálculo.

Em que ordem devo configurar a conexão com a API?

1. 1Adicione saldo e crie uma chave de API no seu painel
2. 2Confira a chave e a conexão com balance
3. 3Busque a lista de serviços com services e liste-os no seu painel
4. 4Envie um add com a menor quantidade e receba um ID de pedido
5. 5Confirme com status que o status muda e depois ative os pedidos automáticos

Exemplos em curl, PHP, Python e Node.js e a descrição completa dos campos estão na documentação da API, e outras dúvidas estão no grupo API das Perguntas frequentes.