API Documentation

API REST enterprise-grade para integração segura com múltiplas instâncias WHMCS. Esta API serve como camada central entre clientes automatizados (bots, sites, sistemas) e suas instâncias WHMCS.

Base URL: https://api.whmcs.vplaysh.top/v1

Segurança

Autenticação por token, rate limiting, e logs auditáveis

Multi-WHMCS

Suporte a múltiplas instâncias WHMCS por tenant

Performance

Cache, filas e rate limiting para alta performance

Quick Start

Exemplo de requisição

curl -X GET "https://api.whmcs.vplaysh.top/v1/me" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Prerequisites

Token de API válido (veja Autenticação)
Permissões adequadas para o endpoint desejado
Instância WHMCS configurada e ativa

Autenticação

A API utiliza autenticação por token via header Authorization. Os tokens são armazenados como hash SHA-256 e nunca em texto puro.

Header de Autenticação

Authorization: Bearer sk_dev_xxxxxxxxxxxxxxxxxxxxx

Formato do Token

Tokens de desenvolvimento começam com sk_dev_ seguidos de 64 caracteres hexadecimais.

Importante: O token é mostrado apenas uma vez durante o seeding. Guarde-o em local seguro!

Health Check

GET /api/v1/health

Verifica o status de saúde da API. Não requer autenticação.

Response Example

{
  "success": true,
  "message": "API is running",
  "data": {
    "status": "healthy",
    "timestamp": "2024-01-01T00:00:00+00:00"
  },
  "meta": {
    "request_id": "uuid",
    "timestamp": "2024-01-01T00:00:00+00:00"
  }
}

Contexto do Consumidor

GET /api/v1/me

Retorna informações sobre o consumidor autenticado, tenant e permissões.

Response Example

{
  "success": true,
  "message": "Contexto do consumidor",
  "data": {
    "consumer": {
      "id": 1,
      "name": "Development API Consumer",
      "slug": "dev-consumer",
      "tenant_id": 1
    },
    "tenant": {
      "id": 1,
      "name": "Development Tenant",
      "slug": "dev-tenant"
    },
    "permissions": {
      "clients": ["search", "read", "read_summary"],
      "services": ["read", "read_summary", "suspend", "unsuspend"],
      "invoices": ["search", "read", "read_open"]
    },
    "rate_limit": 100,
    "last_used_at": "2024-01-01T00:00:00+00:00"
  },
  "meta": {
    "request_id": "uuid",
    "timestamp": "2024-01-01T00:00:00+00:00"
  }
}

Clientes

POST /api/v1/clients/search

Busca clientes com filtros opcionais. Requer permissão clients.search.

Request Body

{
  "search": "nome do cliente",
  "email": "cliente@email.com",
  "status": "Active",
  "limit": 25,
  "offset": 0
}

Response Example

{
  "success": true,
  "message": "Clientes encontrados",
  "data": {
    "clients": [
      {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com",
        "company_name": "Example Inc",
        "status": "Active",
        "created_at": "2024-01-01",
        "phone": "+1234567890",
        "country": "United States",
        "state": "California",
        "city": "San Francisco"
      }
    ],
    "total": 1,
    "limit": 25,
    "offset": 0
  },
  "meta": {
    "request_id": "uuid",
    "timestamp": "2024-01-01T00:00:00+00:00"
  }
}

GET /api/v1/clients/{id}

Retorna detalhes completos de um cliente. Requer permissão clients.read.

Path Parameters

Name	Type	Description
id	integer	ID do cliente no WHMCS

GET /api/v1/clients/{id}/summary

Retorna um resumo do cliente. Requer permissão clients.read_summary.

Response Example

{
  "success": true,
  "message": "Resumo do cliente",
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "status": "Active",
    "activeServices": 3
  },
  "meta": {
    "request_id": "uuid",
    "timestamp": "2024-01-01T00:00:00+00:00"
  }
}

Serviços

GET /api/v1/services/{id}

Retorna detalhes completos de um serviço. Requer permissão services.read.

Response Example

{
  "success": true,
  "message": "Serviço encontrado",
  "data": {
    "id": 1,
    "product_name": "Web Hosting Pro",
    "domain": "example.com",
    "status": "Active",
    "next_due_date": "2024-12-31",
    "billing_cycle": "Monthly",
    "created_at": "2024-01-01"
  },
  "meta": {
    "request_id": "uuid",
    "timestamp": "2024-01-01T00:00:00+00:00"
  }
}

POST /api/v1/services/{id}/suspend

Suspende um serviço. Requer permissão services.suspend.

Ação crítica: Esta ação suspende imediatamente o serviço no WHMCS.

Response Example

{
  "success": true,
  "message": "Serviço suspenso com sucesso",
  "data": {
    "success": true,
    "message": "Serviço suspenso com sucesso"
  },
  "meta": {
    "request_id": "uuid",
    "timestamp": "2024-01-01T00:00:00+00:00"
  }
}

POST /api/v1/services/{id}/unsuspend

Reativa um serviço suspenso. Requer permissão services.unsuspend.

Faturas

POST /api/v1/invoices/search

Busca faturas com filtros opcionais. Requer permissão invoices.search.

Request Body

{
  "client_id": 1,
  "status": "Unpaid",
  "limit": 25,
  "offset": 0
}

GET /api/v1/invoices/{id}

Retorna detalhes completos de uma fatura. Requer permissão invoices.read.

GET /api/v1/clients/{clientId}/open-invoices

Retorna faturas em aberto de um cliente. Requer permissão invoices.read_open.

Códigos de Erro

A API retorna erros no seguinte formato:

{
  "success": false,
  "message": "Descrição amigável do erro",
  "error_code": "ERROR_CODE",
  "errors": {},
  "meta": {
    "request_id": "uuid",
    "timestamp": "2024-01-01T00:00:00+00:00"
  }
}

Error Code	HTTP Status	Description
UNAUTHENTICATED	401	Token ausente ou inválido
FORBIDDEN	403	Sem permissão para acessar o recurso
NOT_FOUND	404	Recurso não encontrado
VALIDATION_ERROR	422	Erro de validação nos dados de entrada
RATE_LIMIT_EXCEEDED	429	Limite de requisições excedido
INTEGRATION_ERROR	502	Erro ao comunicar com WHMCS
SERVICE_UNAVAILABLE	503	WHMCS indisponível
INTERNAL_ERROR	500	Erro interno no servidor

Rate Limiting

A API implementa rate limiting por consumidor para prevenir abuso. O limite padrão é configurável por consumidor.

Headers de Rate Limit

Header	Description
X-RateLimit-Limit	Número máximo de requisições por minuto
X-RateLimit-Remaining	Requisições restantes no período atual

Nota: Ao exceder o limite, a API retorna HTTP 429 com o código de erro RATE_LIMIT_EXCEEDED.