ZenPanel API v2
Documentação de referência — controle completo de usuários via REST.
Introdução
A API do ZenPanel oferece controle completo da tabela de usuários, pensada para integração com bots de cobrança, sistemas de venda automática e outros painéis.
Autenticação
Todas as requisições devem enviar o token no header HTTP:
Authorization: Bearer SUA_API_KEY_AQUI
403 Forbidden.
Endpoint
Todas as actions são enviadas para o mesmo endpoint. O campo action no corpo JSON determina a operação.
criar Cria um novo usuário
vencimento, data ou data_vencimento — todos funcionam (YYYY-MM-DD).Lista: se não enviar
lista_id, a API associa automaticamente a primeira lista vinculada ao seu usuário.
| Campo | Tipo | Req. | Descrição |
|---|---|---|---|
login_usuario | string | ✱ obrigatório | Login único (mín. 3 chars) |
senha_usuario | string | ✱ obrigatório | Senha (mín. 4 chars) |
vencimento | date | padrão: +30 dias | Data de vencimento YYYY-MM-DD |
lista_id | int | opcional | ID da lista. Use listar_listas para ver disponíveis |
conectado | int | padrão: 1 | Conexões simultâneas |
nome_completo | string | opcional | Nome completo |
email | string | opcional | |
whatsapp | string | opcional | |
estado_usuario | int | padrão: 1 | 1=ativo, 0=inativo |
tipo | string | padrão: usuario | admin | revendedor | usuario |
modalidade_revenda | string | padrão: prepago | prepago | mensalista |
creditos | float | padrão: 0 | Créditos iniciais |
limite_credito | float | padrão: 0 | Limite de crédito |
xui_server_id | int | opcional | ID do servidor XUI |
xui_bouquet_ids | array | opcional | Array de IDs de bouquets para XUI |
pode_revender | int | padrão: 0 | 1=pode criar sub-revendas |
margem_revenda | float | padrão: 0 | Margem de lucro permitida (%) |
Requisição — cliente padrão
{
"action": "criar",
"login_usuario": "cliente123",
"senha_usuario": "senha1234",
"nome_completo": "João Silva",
"whatsapp": "11999990000",
"conectado": 2,
"vencimento": "2026-04-23",
"lista_id": 1
}
Requisição — cliente XUI
{
"action": "criar",
"login_usuario": "cliente123",
"senha_usuario": "senha1234",
"conectado": 2,
"vencimento": "2026-04-23",
"xui_server_id": 1,
"xui_bouquet_ids": [3, 7, 12]
}
Resposta (201)
{
"success": true,
"mensagem": "Usuário criado com sucesso",
"dados": {
"id_usuario": 47,
"login_usuario": "cliente123",
"data_vencimento": "2026-04-23",
"conexoes": 2,
"xui_user_id": null,
"custo_debitado": null
}
}
listar_listas Retorna as listas disponíveis
Use para descobrir os id_lista disponíveis antes de criar um usuário.
{ "action": "listar_listas" }
Resposta
{
"success": true,
"dados": {
"total": 2,
"listas": [
{ "id_lista": 1, "nome_lista": "COMPLETO COM ADULTOS" },
{ "id_lista": 2, "nome_lista": "FAMÍLIA" }
]
}
}
listar Lista usuários com filtros
| Campo | Tipo | Req. | Descrição |
|---|---|---|---|
estado_usuario | int | opcional | 1=ativo / 0=inativo |
tipo | string | opcional | admin | revendedor | usuario |
modalidade_revenda | string | opcional | prepago | mensalista |
login_like | string | opcional | Busca parcial no login |
xui_server_id | int | opcional | Filtrar por servidor XUI |
limit | int | padrão: 100 / máx: 500 | Registros por página |
offset | int | padrão: 0 | Paginação |
{
"action": "listar",
"estado_usuario": 1,
"limit": 50,
"offset": 0
}
buscar Retorna um único usuário
| Campo | Tipo | Req. | Descrição |
|---|---|---|---|
id_usuario | int | um dos dois | ID numérico |
login_usuario | string | um dos dois | Login exato |
{
"action": "buscar",
"login_usuario": "cliente123"
}
editar Atualiza qualquer campo permitido
Envie apenas os campos que deseja alterar. Campos não enviados não são tocados.
{
"action": "editar",
"id_usuario": 47,
"conectado": 4,
"whatsapp": "11988887777"
}
deletar Remove permanentemente o usuário
{
"action": "deletar",
"id_usuario": 47
}
bloquear / desbloquear
{
"action": "bloquear", // ou "desbloquear"
"id_usuario": 47
}
bloquear_massa Bloqueia/desbloqueia array de IDs
| Campo | Tipo | Req. | Descrição |
|---|---|---|---|
ids | array | ✱ obrigatório | Array de id_usuario |
estado_usuario | int | ✱ obrigatório | 0=bloquear, 1=desbloquear |
{
"action": "bloquear_massa",
"ids": [10, 11, 47, 88],
"estado_usuario": 0
}
Resposta
{ "success": true, "dados": { "afetados": 4 } }
creditar / debitar
credito_utilizado.Creditar
{
"action": "creditar",
"id_usuario": 47,
"valor": 50.00
}
Debitar
{
"action": "debitar",
"id_usuario": 47,
"valor": 25.00
}
Resposta
{
"success": true,
"dados": { "id_usuario": 47, "creditado": 50, "saldo_atual": 150 }
}
set_credito / set_limite Define valor exato
{
"action": "set_credito",
"id_usuario": 47,
"valor": 200.00
}
{
"action": "set_limite",
"id_usuario": 47,
"valor": 500.00
}
set_vencimento Define data de vencimento exata
{
"action": "set_vencimento",
"id_usuario": 47,
"data_pagamento_revenda": "2025-04-30" // YYYY-MM-DD
}
renovar Estende vencimento por dias ou meses
estado_usuario = 1).Por dias
{
"action": "renovar",
"id_usuario": 47,
"dias": 30
}
Por meses
{
"action": "renovar",
"id_usuario": 47,
"meses": 3
}
Resposta
{
"success": true,
"dados": { "id_usuario": 47, "novo_vencimento": "2025-05-24" }
}
set_xui Atualiza dados de vinculação XUI
| Campo | Tipo | Req. | Descrição |
|---|---|---|---|
id_usuario | int | ✱ obrigatório | ID do usuário |
xui_server_id | int | opcional | ID do servidor XUI |
xui_user_id | int | opcional | ID do usuário no XUI |
xui_bouquet_id | string | opcional | Bouquet ID |
xui_bouquets | string | opcional | JSON de bouquets |
xui_servers_permitidos | string | opcional | JSON com IDs permitidos |
{
"action": "set_xui",
"id_usuario": 47,
"xui_server_id": 3,
"xui_user_id": 1042
}
limpar_xui Zera todos os campos XUI
{
"action": "limpar_xui",
"id_usuario": 47
}
vencidos Usuários com vencimento ultrapassado
Ideal para bot de cobrança. Retorna apenas usuários do escopo do caller.
{ "action": "vencidos" }
Resposta
{
"success": true,
"dados": {
"total": 8,
"usuarios": [
{
"id_usuario": 12,
"login_usuario": "joao",
"whatsapp": "11999998888",
"data_pagamento_revenda": "2025-02-01",
"estado_usuario": 1
}
]
}
}
a_vencer Vencendo nos próximos N dias
| Campo | Tipo | Req. | Descrição |
|---|---|---|---|
dias | int | padrão: 7 | Janela de antecedência em dias |
{
"action": "a_vencer",
"dias": 3
}
resumo Contadores gerais — dashboard do bot
{ "action": "resumo" }
Resposta
{
"success": true,
"dados": {
"total": 150,
"ativos": 132,
"inativos": 18,
"revendedores": 12,
"usuarios": 138,
"saldo_total": 4230.50,
"vencidos": 8,
"vencendo_7d": 5
}
}
Exemplos de Código
<?php
$apiKey = 'SUA_API_KEY';
$base = 'https://seu-dominio.com/api/create_user.php';
function ZenPanel(string $action, array $params = []): array {
global $apiKey, $base;
$ch = curl_init($base);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode(array_merge(['action' => $action], $params)),
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Authorization: Bearer ' . $apiKey,
],
]);
$res = curl_exec($ch);
curl_close($ch);
return json_decode($res, true);
}
// Ver listas disponíveis
$listas = ZenPanel('listar_listas')['dados']['listas'];
$lista_id = $listas[0]['id_lista'];
// Criar usuário
$r = ZenPanel('criar', [
'login_usuario' => 'cliente001',
'senha_usuario' => 'senha1234',
'nome_completo' => 'João Silva',
'whatsapp' => '11999990000',
'conectado' => 2,
'vencimento' => date('Y-m-d', strtotime('+30 days')),
'lista_id' => $lista_id,
]);
echo $r['dados']['id_usuario'];
// Renovar
ZenPanel('renovar', ['id_usuario' => $r['dados']['id_usuario'], 'dias' => 30]);
// Cobrar vencidos
$vencidos = ZenPanel('vencidos')['dados']['usuarios'];
foreach ($vencidos as $u) {
echo "Cobrar: {$u['whatsapp']} — venceu {$u['data_vencimento']}\n";
}
?>
import requests
API_KEY = 'SUA_API_KEY'
BASE = 'https://seu-dominio.com/api/create_user.php'
HEADERS = {'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'}
def cs(action, **params):
r = requests.post(BASE, json={'action': action, **params}, headers=HEADERS)
r.raise_for_status()
return r.json()
listas = cs('listar_listas')['dados']['listas']
lista_id = listas[0]['id_lista']
novo = cs('criar',
login_usuario='cliente001',
senha_usuario='senha1234',
conectado=2,
vencimento='2026-04-30',
lista_id=lista_id
)
print(f"Criado ID: {novo['dados']['id_usuario']}")
info = cs('resumo')['dados']
print(f"Ativos: {info['ativos']} | Vencidos: {info['vencidos']}")
vencidos = cs('vencidos')['dados']['usuarios']
ids = [u['id_usuario'] for u in vencidos]
if ids:
cs('bloquear_massa', ids=ids, estado_usuario=0)
cs('renovar', id_usuario=47, meses=1)
const axios = require('axios');
const API_KEY = 'SUA_API_KEY';
const BASE = 'https://seu-dominio.com/api/create_user.php';
const headers = { Authorization: `Bearer ${API_KEY}` };
const cs = (action, params = {}) =>
axios.post(BASE, { action, ...params }, { headers }).then(r => r.data);
(async () => {
const { dados: { listas } } = await cs('listar_listas');
const lista_id = listas[0].id_lista;
const { dados } = await cs('criar', {
login_usuario: 'cliente001',
senha_usuario: 'senha1234',
conectado: 2,
vencimento: '2026-04-30',
lista_id,
});
console.log('Criado ID:', dados.id_usuario);
const { dados: d } = await cs('a_vencer', { dias: 2 });
d.usuarios.forEach(u => console.log(`Avisar: ${u.whatsapp}`));
})();
# Listas disponíveis
curl -X POST https://seu-dominio.com/api/create_user.php \
-H "Authorization: Bearer SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action":"listar_listas"}'
# Criar usuário
curl -X POST https://seu-dominio.com/api/create_user.php \
-H "Authorization: Bearer SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action":"criar","login_usuario":"cliente001","senha_usuario":"senha1234","conectado":2,"vencimento":"2026-04-30","lista_id":1}'
# Resumo geral
curl -X POST https://seu-dominio.com/api/create_user.php \
-H "Authorization: Bearer SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action":"resumo"}'
# Renovar
curl -X POST https://seu-dominio.com/api/create_user.php \
-H "Authorization: Bearer SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action":"renovar","id_usuario":47,"dias":30}'
# Bloquear em massa
curl -X POST https://seu-dominio.com/api/create_user.php \
-H "Authorization: Bearer SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action":"bloquear_massa","ids":[10,11,12],"estado_usuario":0}'
#!/usr/bin/env python3
"""
Fluxo completo para bot de cobrança via WhatsApp/Telegram.
Roda como cron job diário.
"""
import requests
from datetime import date, timedelta
API_KEY = 'SUA_API_KEY'
BASE = 'https://seu-dominio.com/api/create_user.php'
HEADERS = {'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'}
def cs(action, **p):
return requests.post(BASE, json={'action': action, **p}, headers=HEADERS).json()
def notificar_whatsapp(numero, mensagem):
pass # integre com WPPConnect, Evolution API, etc.
# ── 1. Avisar quem vence em 3 dias ────────────────────────────────────────
aviso = cs('a_vencer', dias=3)['dados']['usuarios']
for u in aviso:
notificar_whatsapp(u['whatsapp'],
f"⚠️ Olá {u['nome_completo'] or u['login_usuario']}!\n"
f"Sua assinatura vence em {u['data_vencimento']}.\n"
f"Renove agora para não perder o acesso.")
# ── 2. Bloquear vencidos ───────────────────────────────────────────────────
vencidos = cs('vencidos')['dados']['usuarios']
ids = [u['id_usuario'] for u in vencidos if u['estado_usuario'] == 1]
if ids:
cs('bloquear_massa', ids=ids, estado_usuario=0)
for u in vencidos:
notificar_whatsapp(u['whatsapp'],
"🔒 Sua conta foi suspensa.\n"
f"Vencimento: {u['data_vencimento']}.\n"
"Realize o pagamento para reativar.")
# ── 3. Criar cliente após venda ────────────────────────────────────────────
def criar_cliente(login, senha, whatsapp, dias=30, lista_id=1):
vencimento = (date.today() + timedelta(days=dias)).strftime('%Y-%m-%d')
return cs('criar',
login_usuario=login, senha_usuario=senha,
whatsapp=whatsapp, conectado=2,
vencimento=vencimento, lista_id=lista_id
)
# ── 4. Após pagamento confirmado: renovar e reativar ──────────────────────
def on_pagamento_confirmado(id_usuario: int, dias: int = 30):
cs('renovar', id_usuario=id_usuario, dias=dias)
# renovar já define estado_usuario=1 automaticamente
Códigos de Erro HTTP
| Código | Significado | Quando ocorre |
|---|---|---|
| 200 | OK | Operação realizada com sucesso |
| 201 | Created | Usuário criado com sucesso |
| 400 | Bad Request | JSON inválido, campo obrigatório ausente ou valor inválido |
| 401 | Unauthorized | Token ausente ou inválido |
| 403 | Forbidden | Token desativado ou IP não autorizado |
| 404 | Not Found | Usuário não encontrado ou fora do escopo |
| 405 | Method Not Allowed | Requisição não foi POST |
| 500 | Internal Server Error | Erro inesperado no servidor |
Formato de erro
{
"success": false,
"mensagem": "Saldo insuficiente",
"dados": null,
"ts": "2025-03-24T10:05:00-03:00"
}