Administração (Superadmin)

17. Administração (Superadmin)#

Rotas exclusivas para administradores da plataforma.

GET/v1/admin/system#

Informações do sistema.

Auth: Superadmin

Resposta 200:

json 
{
  "uptime_seconds": 86400,
  "goroutines": 42,
  "memory": {
    "alloc_mb": 128,
    "sys_mb": 256,
    "gc_cycles": 50,
    "heap_objects": 100000,
    "heap_inuse_mb": 100
  },
  "go_version": "go1.22.0",
  "num_cpu": 4
}

GET/v1/admin/companies#

Lista todas as empresas da plataforma.

Auth: Superadmin

Query Parameters:

Parametro Tipo Padrão Descricao
page int 1 Página
limit int 20 Itens por página (max 100)

Resposta 200:

json 
{
  "data": [
    {
      "id": 1,
      "name": "Minha Empresa",
      "status": "active",
      "created_at": "2026-03-01T00:00:00Z"
    }
  ],
  "total": 10,
  "page": 1,
  "limit": 20
}

GET/v1/admin/companies/{companyId}/stats#

Estatísticas de uma empresa.

Auth: Superadmin

Resposta 200:

json 
{
  "company_id": 1,
  "name": "Minha Empresa",
  "status": "active",
  "instances": 3,
  "messages": 15000,
  "webhooks": 2
}

POST/v1/admin/companies/{companyId}/suspend#

Suspende uma empresa. Todos os acessos são bloqueados.

Auth: Superadmin

Resposta 200:

json 
{
  "company_id": 1,
  "status": "suspended"
}

POST/v1/admin/companies/{companyId}/unsuspend#

Reativa uma empresa suspensa.

Auth: Superadmin

Resposta 200:

json 
{
  "company_id": 1,
  "status": "active"
}

GET/v1/admin/instances#

Lista todas as instâncias de todas as empresas.

Auth: Superadmin

Observação: sem rate limit adicional no grupo admin; a protecao e feita por autenticação JWT + RequireSuperadmin().

Query Parameters:

Parametro Tipo Padrão Descricao
page int 1 Página
limit int 20 Itens por página (max 100)

Resposta 200:

json 
{
  "data": [
    {
      "company_id": 1,
      "instance": { "id": "84c2e480-...", "name": "...", "status": "CONNECTED" }
    }
  ],
  "total": 25,
  "page": 1,
  "limit": 20
}

POST/v1/admin/instances/{instanceId}/disconnect#

Forca a desconexao de uma instância.

Auth: Superadmin

Resposta 200:

json 
{
  "instance_id": "84c2e480-...",
  "disconnected": true
}

POST/v1/admin/instances#

Cria uma nova instância para qualquer empresa.

Auth: Superadmin

Request:

json 
{
  "company_id": 14,
  "name": "Nova instancia"
}

Resposta 201: Objeto de instância criado.

POST/v1/admin/instances/{instanceId}/connect#

Conecta uma instância (gera QR code).

Auth: Superadmin

Resposta 200: Objeto de instância com qr_base64 se disponível.

POST/v1/admin/instances/{instanceId}/restart#

Desconecta e reconecta uma instância, gerando nova sessão QR.

Auth: Superadmin

Resposta 200: Objeto de instância com qr_base64 se disponível.

POST/v1/admin/instances/{instanceId}/logout#

Faz logout e apaga a sessão. Requer novo pareamento.

Auth: Superadmin

Resposta 200: Objeto de instância atualizado.

DELETE/v1/admin/instances/{instanceId}#

Remove uma instância permanentemente.

Auth: Superadmin

Resposta 204: Sem corpo.

GET/v1/admin/instances/{instanceId}/qr#

Retorna o QR code atual de qualquer instância.

Auth: Superadmin

Resposta 200: Mesmo formato de GET /v1/instances/{instanceId}/qr.

GET/v1/admin/instances/{instanceId}/qr/stream#

Stream SSE de QR codes de qualquer instância. Mesmo formato de GET /v1/instances/{instanceId}/qr/stream.

Auth: Superadmin

POST/v1/admin/instances/{instanceId}/pairing-code#

Gera código de pareamento para qualquer instância. Mesmo formato de POST /v1/instances/{instanceId}/pairing-code.

Auth: Superadmin

GET/v1/admin/queue#

Estatísticas globais de todas as filas.

Auth: Superadmin

Resposta 200:

json 
{
  "queues": [
    {
      "name": "instance:84c2e480",
      "size": 100,
      "pending": 5,
      "active": 1,
      "completed": 90,
      "failed": 2,
      "scheduled": 1,
      "retry": 1
    }
  ]
}

GET/v1/admin/queue/archived#

Lista tasks que falharam permanentemente (DLQ — Dead Letter Queue).

Auth: Superadmin

Query params:

  • queue — Nome da fila (default: default)
  • limit — Max items retornados (default: 25, max: 100)

Resposta 200:

json 
{
  "queue": "default",
  "count": 2,
  "archived": [
    {
      "id": "task_abc123",
      "type": "msg:send_text",
      "queue": "default",
      "max_retry": 3,
      "retried": 3,
      "last_failed_at": "2026-03-22T10:30:00Z",
      "last_err": "send failed: not connected",
      "instance_id": "84c2e480-...",
      "company_id": 1
    }
  ]
}

GET/v1/admin/logs/files#

Lista arquivos de log disponíveis no diretorio configurado.

Auth: Superadmin

Resposta 200:

json 
{
  "dir": "./data/logs",
  "files": [
    { "name": "biazap.log", "size": 9371 },
    { "name": "biazap-2026-03-21.log.gz", "size": 2048 }
  ]
}

GET/v1/admin/logs#

Retorna linhas filtradas de um arquivo de log (tail com filtros).

Auth: Superadmin

Query params:

Param Default Descricao
file biazap.log Nome do arquivo (sem path)
limit 200 Max linhas retornadas (max 5000)
skip 0 Pular N linhas do final
level — Filtrar por level (error, warn, info, debug)
contains — Busca texto livre em qualquer campo
instance_id — Filtrar por instance_id

Resposta 200:

json 
{
  "file": "biazap.log",
  "total": 1234,
  "showing": 10,
  "skip": 0,
  "limit": 10,
  "lines": [
    "{\"level\":\"info\",\"time\":\"2026-03-22T13:41:48Z\",\"message\":\"text message sent\"}"
  ]
}

Exemplos de uso:

bash 
# Ultimas 50 linhas
GET /v1/admin/logs?limit=50

# Apenas erros
GET /v1/admin/logs?level=error&limit=100

# Filtrar por instancia
GET /v1/admin/logs?instance_id=84c2e480-xxxx&limit=200

# Busca texto livre
GET /v1/admin/logs?contains=rate+limited&limit=50

POST/v1/admin/broadcast#

Envia uma notificação para todos os webhooks ativos da plataforma.

Auth: Superadmin

Request:

json 
{
  "message": "Manutencao programada para hoje as 22h",
  "type": "system.broadcast"
}
Campo Tipo Obrigatório Descricao
message string sim Conteúdo da notificação
type string não Tipo do evento. Padrão: system.broadcast

Resposta 200:

json 
{
  "broadcast": true,
  "webhooks_notified": 15
}

GET/v1/admin/tokens#

Lista todos os tokens ativos da plataforma.

Auth: Superadmin

Query Parameters:

Parametro Tipo Descricao
company_id int Filtrar por empresa (opcional)

Resposta 200:

json 
[
  {
    "id": 15,
    "company_id": 14,
    "company_name": "EJ ESTETICA",
    "label": "producao",
    "last4": "f4eb",
    "role": "owner",
    "created_at": "2026-03-07T23:42:37Z"
  }
]

POST/v1/admin/tokens#

Cria um token de API para qualquer empresa.

Auth: Superadmin

Request:

json 
{
  "company_id": 14,
  "label": "integracao-v2",
  "role": "owner"
}
Campo Tipo Obrigatório Descricao
company_id int sim ID da empresa
label string sim Nome identificador
role string não owner, admin, agent. Padrão: owner

Resposta 201:

json 
{
  "token_id": 16,
  "token": "bza_xxxx...xxxx",
  "label": "integracao-v2",
  "role": "owner",
  "last4": "xxxx",
  "company_id": 14,
  "created_at": "2026-03-30T14:00:00Z"
}

Importante: O token so e exibido uma vez. Salve-o em local seguro.

DELETE/v1/admin/tokens/{tokenId}#

Revoga qualquer token da plataforma.

Auth: Superadmin

Resposta 204: Sem corpo.

GET/v1/admin/webhooks/{webhookId}/logs#

Lista delivery logs de qualquer webhook.

Auth: Superadmin

Query Parameters:

Parametro Tipo Descricao
page int Página (default: 1)
limit int Itens por página (default: 50, max: 100)
success string Filtrar: true ou false

Resposta 200:

json 
{
  "data": [
    {
      "id": 123,
      "webhook_id": 12,
      "event_id": "evt-uuid",
      "event_type": "message.delivered",
      "payload": "{}",
      "payload_raw": "{\"event_type\":\"message.delivered\",...}",
      "status_code": 500,
      "response": "{\"success\":false,\"error\":\"...\"}",
      "attempt": 1,
      "success": false,
      "created_at": "2026-03-30T15:42:01Z"
    }
  ],
  "total": 27,
  "page": 1,
  "limit": 50
}

Nota: O campo payload_raw contem o corpo completo enviado ao webhook. So disponível para entregas falhadas (deliveries com sucesso tem payload_raw limpo após 48h pelo cleanup).

GET/v1/admin/webhooks#

Lista todos os webhooks da plataforma com enriquecimento de empresa e instância.

Auth: Superadmin

Query Parameters:

Parametro Tipo Padrão Descricao
page int 1 Página
limit int 20 Itens por página (max 100)

Resposta 200:

json 
{
  "data": [
    {
      "id": 12,
      "url": "https://example.com/webhook",
      "events": "message.received,message.sent",
      "active": true,
      "instance_id": "",
      "instance_name": "",
      "company_id": 14,
      "company_name": "EJ ESTETICA",
      "created_at": "2026-03-07T10:00:00Z",
      "updated_at": "2026-03-07T10:00:00Z"
    }
  ],
  "total": 10,
  "page": 1,
  "limit": 20
}

GET/v1/admin/webhooks/{webhookId}#

Retorna um webhook por ID.

Auth: Superadmin

Resposta 200: Mesmo formato do item acima.

PATCH/v1/admin/webhooks/{webhookId}#

Atualiza campos de qualquer webhook.

Auth: Superadmin

Request (todos opcionais):

json 
{
  "url": "https://novo-endpoint.com/webhook",
  "events": "message.received",
  "active": true,
  "instance_id": "84c2e480-..."
}

Resposta 200: Webhook atualizado.

DELETE/v1/admin/webhooks/{webhookId}#

Remove qualquer webhook.

Auth: Superadmin

Resposta 204: Sem corpo.

GET/v1/admin/webhooks/metrics#

Metricas de saúde por webhook (entregas, falhas, taxa de sucesso) em uma janela de tempo.

Auth: Superadmin

Query Parameters:

Parametro Tipo Padrão Descricao
hours int 24 Janela de tempo em horas

Resposta 200:

json 
{
  "period_hours": 2,
  "webhooks": [
    {
      "webhook_id": 21,
      "url": "https://example.com/webhook",
      "company_id": 14,
      "company_name": "EJ ESTETICA",
      "instance_id": "84c2e480-...",
      "instance_name": "EJ Whats",
      "total": 37,
      "successes": 37,
      "failures": 0,
      "success_rate": 100
    }
  ]
}

company_name e instance_name são enriquecidos a partir das tabelas companies e tenant_instances. Se o webhook não está filtrado por instância, instance_id e instance_name ficam vazios.

GET/v1/admin/delivery-logs#

Lista delivery logs de todos os webhooks da plataforma com paginação e filtros.

Auth: Superadmin

Query Parameters:

Parametro Tipo Padrão Descricao
page int 1 Página
limit int 50 Itens por página (max 100)
success bool - Filtrar por sucesso/falha
event_type string - Filtrar por tipo de evento
since string - Filtrar desde data (RFC3339)
webhook_id int - Filtrar por webhook ID

Resposta 200:

json 
{
  "data": [
    {
      "id": 1234,
      "webhook_id": 21,
      "event_id": "3c726dc7-...",
      "event_type": "message.received",
      "status_code": 200,
      "success": true,
      "error_class": "",
      "created_at": "2026-04-12T17:00:00Z",
      "webhook_url": "https://example.com/webhook",
      "company_name": "EJ ESTETICA",
      "company_id": 14
    }
  ],
  "total": 85,
  "page": 1,
  "limit": 50
}

POST/v1/admin/webhooks/retry-batch#

Reenvia entregas falhadas em lote (máximo 500 por chamada).

Auth: Superadmin

Request:

json 
{
  "log_ids": [1234, 1235],
  "webhook_id": 21,
  "event_type": "message.received",
  "since": "2026-04-12T00:00:00Z"
}

Todos os campos são opcionais. log_ids tem prioridade — se fornecido, os demais filtros são ignorados. Sem log_ids, os filtros combinam para selecionar as falhas a reenviar.

Resposta 200:

json 
{
  "requeued": 3,
  "skipped": 1,
  "errors": []
}

Nota: Os endpoints do Security Dashboard (/v1/admin/security/dashboard, /threats, /ip-reputation, /hackers) foram removidos. A deteccao de ameacas agora e gerenciada pela biblioteca compartilhada Sentinel (github.com/ronszcka/sentinel), que possui sua própria interface de administração.