DomíniosMarketplace
EntrarComeçar →
Marketplace
REST API · v1.1
SmartCloud

SmartCloud API

Automatize a gestão de domínios, hosting, email e segurança directamente a partir do seu código.

Obter API Key OpenAPI JSON
SmartCloud
v1.1 · estável
Começar
Endpoints
Referência

Links úteis

OpenAPI JSON Estado do sistema Changelog

Introdução

A SmartCloud API REST permite-lhe gerir todos os seus serviços programaticamente — desde o registo de domínios ao aprovisionamento de servidores VPS, passando por caixas de email, certificados SSL e muito mais.

Domínios

Registe, transfira e gerencie domínios .ao e internacionais

Hosting & VPS

Crie e escale servidores em segundos via API

Segurança

Emita certificados SSL e gerencie firewalls

URL Base

Todas as chamadas à API devem usar o seguinte URL base:

Base URL
https://api.smartcloud.ao/v1

Health check

Verifique a disponibilidade da API sem autenticação. Útil para monitorização e alertas.

GET https://api.smartcloud.ao/ping

Resposta imediata, sem base de dados. Retorna 200 e { "ok": true, "ts": "..." }.

curl -s https://api.smartcloud.ao/ping

GET https://api.smartcloud.ao/health

Estado completo: BD, memória, SMTP, Stripe, AppyPay, etc. Retorna JSON com status (healthy | degraded | unhealthy) e checks.

curl -s https://api.smartcloud.ao/health

Autenticação

A SmartCloud API usa API Keys para autenticar os pedidos. Inclua a chave no cabeçalho Authorization de cada pedido.

⚠️ Nunca exponha a sua API key no código público ou no front-end. Use variáveis de ambiente no servidor.

Header de autenticação
Authorization: Bearer sc_xxxxxxxxxxxxxxxxxxxx
Exemplo cURL
curl https://api.smartcloud.ao/v1/domains \
  -H "Authorization: Bearer sc_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Crie e gira as suas API keys em Dashboard → API Keys

Códigos de Resposta

200
OK

O pedido foi concluído com sucesso.

201
Created

O recurso foi criado com sucesso.

400
Bad Request

Parâmetros inválidos ou em falta.

401
Unauthorized

API key inválida, expirada ou ausente.

403
Forbidden

Sem permissão para este recurso.

404
Not Found

O recurso solicitado não existe.

409
Conflict

O recurso já existe (e.g., domínio já registado).

429
Too Many Requests

Rate limit excedido. Aguarde antes de tentar novamente.

500
Internal Server Error

Erro inesperado no servidor SmartCloud.

Rate Limits

Os limites aplicam-se por API key. Os cabeçalhos de resposta indicam o estado atual do rate limit.

Free60 req/min1 000 req/dia
Pro300 req/min50 000 req/dia
Business1 000 req/min500 000 req/dia
EnterpriseIlimitadoIlimitado
Cabeçalhos de rate limit
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1709254800
Retry-After: 60

Endpoints

GET/v1/domains

Listar Domínios

Retorna todos os domínios associados à sua conta, com informações de expiração, estado DNS e configurações de renovação automática.

Parâmetros

ParâmetroTipoObrigatórioDescrição
pageintegernãoNúmero da página (padrão: 1)
per_pageintegernãoResultados por página, máx. 100 (padrão: 20)
statusstringnãoFiltrar por estado: active | expired | pending
tldstringnãoFiltrar por TLD, e.g. ".ao" ou ".com"

Respostas

200Sucesso — retorna os dados solicitados
401Não autorizado — API key inválida ou ausente
429Rate limit excedido
500Erro interno do servidor
curl https://api.smartcloud.ao/v1/domains \
  -H "Authorization: Bearer sc_xxxxxxxxxxxx"
200 OK
{
  "domains": [
    {
      "id": "dom_9xkL2mNp",
      "name": "meusite.ao",
      "status": "active",
      "expires_at": "2026-03-01T00:00:00Z",
      "auto_renew": true,
      "dns_status": "propagated",
      "created_at": "2024-03-01T10:00:00Z"
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "per_page": 20
  }
}
GET/v1/hosting/plans

Planos de Hosting

Lista todos os planos de hosting disponíveis com especificações de armazenamento, largura de banda e funcionalidades incluídas.

Parâmetros

ParâmetroTipoObrigatórioDescrição
typestringnãoTipo: shared | wordpress | woocommerce | agencies
currencystringnãoMoeda: AOA (padrão) | USD | EUR

Respostas

200Sucesso — retorna os dados solicitados
401Não autorizado — API key inválida ou ausente
429Rate limit excedido
500Erro interno do servidor
curl "https://api.smartcloud.ao/v1/hosting/plans?type=wordpress" \
  -H "Authorization: Bearer sc_xxxxxxxxxxxx"
200 OK
{
  "plans": [
    {
      "id": "plan_wp_starter",
      "name": "WordPress Starter",
      "type": "wordpress",
      "storage_gb": 10,
      "bandwidth_gb": 100,
      "domains": 1,
      "ssl": true,
      "price": {
        "monthly_aoa": 15000,
        "annual_aoa": 144000
      }
    }
  ]
}
POST/v1/cloud/servers

Criar Servidor Cloud

Provisiona um novo servidor VPS ou Cloud com as especificações escolhidas. O servidor fica disponível em menos de 60 segundos.

Parâmetros

ParâmetroTipoObrigatórioDescrição
plan_idstringsimID do plano VPS/Cloud a aprovisionar
regionstringsimRegião: ao-luanda | eu-west | us-east
osstringsimSistema operativo: ubuntu-22.04 | debian-12 | centos-9
hostnamestringnãoNome do servidor (gerado automaticamente se omitido)
ssh_keysarraynãoIDs das chaves SSH a instalar no servidor
backupsbooleannãoActivar backups automáticos diários (padrão: false)

Respostas

200Sucesso — retorna os dados solicitados
401Não autorizado — API key inválida ou ausente
429Rate limit excedido
500Erro interno do servidor
curl -X POST https://api.smartcloud.ao/v1/cloud/servers \
  -H "Authorization: Bearer sc_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "vps_2cpu_4gb",
    "region": "ao-luanda",
    "os": "ubuntu-22.04",
    "hostname": "web-prod-01"
  }'
200 OK
{
  "server": {
    "id": "srv_7tKmX3nQ",
    "hostname": "web-prod-01",
    "status": "provisioning",
    "ip_address": "196.46.xx.xx",
    "region": "ao-luanda",
    "os": "ubuntu-22.04",
    "plan": {
      "cpu": 2,
      "ram_gb": 4,
      "disk_gb": 80,
      "bandwidth_tb": 5
    },
    "created_at": "2026-02-28T18:05:00Z",
    "ready_at": "2026-02-28T18:06:00Z"
  }
}
POST/v1/email/mailboxes

Criar Caixa de Email

Cria uma nova caixa de email profissional num domínio verificado na sua conta SmartCloud.

Parâmetros

ParâmetroTipoObrigatórioDescrição
domainstringsimDomínio onde criar a caixa (deve estar na sua conta)
usernamestringsimNome da caixa (sem @dominio). E.g. "info"
passwordstringsimPalavra-passe da caixa (mín. 12 caracteres)
quota_mbintegernãoQuota em MB (padrão: 5120 = 5 GB)
spam_filterbooleannãoActivar filtro anti-spam com IA (padrão: true)

Respostas

200Sucesso — retorna os dados solicitados
401Não autorizado — API key inválida ou ausente
429Rate limit excedido
500Erro interno do servidor
curl -X POST https://api.smartcloud.ao/v1/email/mailboxes \
  -H "Authorization: Bearer sc_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "meusite.ao",
    "username": "info",
    "password": "SuperSecret123!",
    "quota_mb": 10240,
    "spam_filter": true
  }'
200 OK
{
  "mailbox": {
    "id": "mbx_4pRnY8vL",
    "address": "[email protected]",
    "domain": "meusite.ao",
    "quota_mb": 10240,
    "used_mb": 0,
    "spam_filter": true,
    "status": "active",
    "imap": "mail.smartcloud.ao:993",
    "smtp": "mail.smartcloud.ao:587",
    "created_at": "2026-02-28T18:07:00Z"
  }
}
POST/v1/ssl/certificates

Emitir Certificado SSL

Solicita e emite um certificado SSL/TLS para um domínio verificado. Certificados DV são emitidos em segundos por Let's Encrypt ou ZeroSSL.

Parâmetros

ParâmetroTipoObrigatórioDescrição
domainstringsimDomínio para o certificado (e.g. "meusite.ao")
typestringsimTipo: dv | ov | ev | wildcard
auto_renewbooleannãoRenovar automaticamente 30 dias antes de expirar (padrão: true)

Respostas

200Sucesso — retorna os dados solicitados
401Não autorizado — API key inválida ou ausente
429Rate limit excedido
500Erro interno do servidor
curl -X POST https://api.smartcloud.ao/v1/ssl/certificates \
  -H "Authorization: Bearer sc_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"domain": "meusite.ao", "type": "dv", "auto_renew": true}'
200 OK
{
  "certificate": {
    "id": "ssl_2wMzP6jK",
    "domain": "meusite.ao",
    "type": "dv",
    "status": "issued",
    "issuer": "Let's Encrypt",
    "valid_from": "2026-02-28T00:00:00Z",
    "valid_until": "2026-05-29T00:00:00Z",
    "auto_renew": true
  }
}
POST/v1/orders

Criar Encomenda

Cria uma nova encomenda para qualquer produto SmartCloud. Retorna um link de pagamento e o ID da encomenda para acompanhamento.

Parâmetros

ParâmetroTipoObrigatórioDescrição
product_idstringsimID do produto/plano a encomendar
quantityintegernãoQuantidade (padrão: 1)
periodstringnãoPeríodo: monthly | annually (padrão: monthly)
payment_methodstringsimMétodo: appypay | kwik | stripe
addonsarraynãoLista de IDs de add-ons adicionais

Respostas

200Sucesso — retorna os dados solicitados
401Não autorizado — API key inválida ou ausente
429Rate limit excedido
500Erro interno do servidor
curl -X POST https://api.smartcloud.ao/v1/orders \
  -H "Authorization: Bearer sc_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "plan_wp_starter",
    "period": "annually",
    "payment_method": "appypay"
  }'
200 OK
{
  "order": {
    "id": "ord_8hTvQ5xN",
    "status": "pending_payment",
    "product": "WordPress Starter (Anual)",
    "total_aoa": 144000,
    "payment_url": "https://pay.smartcloud.ao/ord_8hTvQ5xN",
    "expires_at": "2026-02-28T19:07:00Z"
  }
}
Referência

Formato de Erros

Todos os erros retornam um objecto JSON com o campo error.

Exemplo de erro
{
  "error": {
    "code": "domain_not_found",
    "message": "O domínio especificado não existe na sua conta.",
    "status": 404,
    "request_id": "req_5yKmX3nQpL"
  }
}

Paginação

Todos os endpoints de lista suportam paginação via parâmetros page e per_page. O campo meta da resposta inclui a contagem total.

Exemplo de paginação
curl "https://api.smartcloud.ao/v1/domains?page=2&per_page=50" \
  -H "Authorization: Bearer sc_xxxxxxxxxxxx"

Changelog

v1.1— Documentação pública da API (domínios, hosting, cloud, email, SSL, encomendas). Health check e referência OpenAPI.

Webhooks

Configure webhooks para receber notificações em tempo real sobre eventos como pagamentos concluídos, domínios a expirar ou servidores prontos.

ParâmetroTipoObrigatórioDescrição
order.completedeventnãoEncomenda paga e aprovisionada com sucesso
domain.expiringeventnãoDomínio expira em 30 / 14 / 7 / 1 dia(s)
server.readyeventnãoServidor VPS/Cloud pronto para uso
ssl.renewedeventnãoCertificado SSL renovado automaticamente
payment.failedeventnãoTentativa de pagamento falhou
Payload de webhook
{
  "event": "order.completed",
  "timestamp": "2026-02-28T18:10:00Z",
  "data": {
    "order_id": "ord_8hTvQ5xN",
    "product": "WordPress Starter",
    "status": "active"
  },
  "signature": "sha256=abc123..."
}