API de gerenciamento de DNS

Visão geral

A API DNS fornece gestão completa de zonas e registros DNS. Todas as zonas são hospedadas em VPS.org servidores de nomes autoritários com geração automática de arquivos de zona BIND9 e implantação.

Infraestrutura do servidor de nomes

ns1.vps.org (38.248.6.195) - Mestre primário com DNSSEC inline-signatura
ns2.vps.org (38.248.6.196) - Escravo secundário
ns3.vps.org (38.248.6.197) - Escravo secundário

Características-chave

Geração e implantação automática de arquivos de zona BIND9
Transferências de zonas através da autenticação da ETIG (replicação de escravos mestres)
Suporte para todos os principais tipos de registros DNS (A, AAAA, CNAME, MX, TXT, NS, SRV, CAA)
Filtragem de nomes de domínio e identificação de zona baseada em UUID
Rotas aninhadas para a gestão de registos específicos de zonas

Autenticação

Todos os pedidos de API do DNS requerem autenticação de token do Bearer. Gere tokens da API no painel de contas em /account/developers/ com as seguintes permissões:

dns:list - Ver zonas e registros DNS
dns:create - Criar novas zonas e registros
dns:update - Modifique as zonas e os registos existentes
dns:delete - Apagar zonas e registos
dns:* - Acesso completo à gestão do DNS

Exemplo

Authorization: Bearer vps_abc123def456...

Importante: Os tokens da API são mostrados apenas uma vez durante a criação. Armazená-los de forma segura. Se você perder um token, você deve gerar um novo.

PEGAR /api/v1/dns-zones/

Listar todas as zonas DNS

Obtenha uma lista paginada de todas as zonas DNS propriedade do usuário autenticado. Suporta filtragem por nome de domínio.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`domain`	string	Não	Filter zones by exact domain name (e.g., `example.com`)

Exemplo de solicitação

cURL

Python

JavaScript

curl -X GET "https://admin.vps.org/api/v1/dns-zones/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

import requests

url = "https://admin.vps.org/api/v1/dns-zones/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.get(url, headers=headers)
print(response.json())

const response = await fetch('https://admin.vps.org/api/v1/dns-zones/', {
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

const zones = await response.json();
console.log(zones);

Exemplo de resposta

[
  {
    "uuid": "abc123-def456-ghi789",
    "domain": "example.com",
    "created_at": "2024-01-15T10:30:00Z",
    "record_count": 12
  },
  {
    "uuid": "xyz789-uvw456-rst123",
    "domain": "myapp.io",
    "created_at": "2024-06-20T14:15:00Z",
    "record_count": 8
  }
]

Campos de resposta

Campo	Tipo	Descrição
`uuid`	string	Unique zone identifier (used in API requests)
`domain`	string	Domain name for this DNS zone
`created_at`	datetime	Zone creation timestamp (ISO 8601 format)
`record_count`	integer	Total number of DNS records in this zone

Códigos de status de resposta

200	Successfully retrieved DNS zones list
401	Unauthorized - Invalid or missing API token
403	Forbidden - Token lacks `dns:list` permission

PEGAR /api/v1/dns-zones/{uuid}/

Obter detalhes da zona DNS

Obtenha informações detalhadas sobre uma zona DNS específica, incluindo todos os registros.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`uuid`	string	Sim	Unique zone identifier

Exemplo de resposta

{
  "uuid": "abc123-def456-ghi789",
  "domain": "example.com",
  "created_at": "2024-01-15T10:30:00Z",
  "record_count": 5,
  "records": [
    {
      "uuid": "rec-001",
      "record_type": "A",
      "name": "@",
      "value": "192.0.2.1",
      "ttl": 3600,
      "priority": null,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "uuid": "rec-002",
      "record_type": "MX",
      "name": "@",
      "value": "mail.example.com",
      "ttl": 3600,
      "priority": 10,
      "created_at": "2024-01-15T10:32:00Z"
    }
  ]
}

Códigos de status de resposta

200	Successfully retrieved zone details
404	Zone not found or not owned by user

POST /api/v1/dns-zones/

Criar uma Zona DNS

Criar uma nova zona DNS para um domínio. A zona será imediatamente implantada para VPS.org servidores de nomes.

Parâmetros do corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`domain`	string	Sim	Domain name (e.g., `example.com`)

Exemplo de solicitação

cURL

Python

JavaScript

curl -X POST "https://admin.vps.org/api/v1/dns-zones/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "newdomain.com"}'

import requests

url = "https://admin.vps.org/api/v1/dns-zones/"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
data = {"domain": "newdomain.com"}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const response = await fetch('https://admin.vps.org/api/v1/dns-zones/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({domain: 'newdomain.com'})
});

const zone = await response.json();
console.log(zone);

Exemplo de resposta

{
  "uuid": "new-zone-uuid",
  "domain": "newdomain.com",
  "created_at": "2026-01-18T16:45:00Z",
  "record_count": 0,
  "records": []
}

Códigos de status de resposta

201	DNS zone created successfully
400	Bad Request - Invalid domain name or zone already exists
403	Forbidden - Token lacks `dns:create` permission

EXCLUIR /api/v1/dns-zones/{uuid}/

Apagar a Zona DNS

Apagar permanentemente uma zona DNS e todos os registros associados. Esta ação não pode ser desfetada.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`uuid`	string	Sim	Unique zone identifier

Códigos de status de resposta

204	Zone deleted successfully (no response body)
403	Forbidden - Token lacks `dns:delete` permission
404	Zone not found

PEGAR /api/v1/dns-zones/{uuid}/records/

Listar os registros DNS na zona

Recuperar todos os registros DNS para uma zona específica (via nested).

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`uuid`	string	Sim	Zone UUID

Exemplo de solicitação

curl -X GET "https://admin.vps.org/api/v1/dns-zones/{uuid}/records/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Exemplo de resposta

[
  {
    "uuid": "rec-001",
    "record_type": "A",
    "name": "@",
    "value": "192.0.2.1",
    "ttl": 3600,
    "priority": null,
    "created_at": "2024-01-15T10:30:00Z"
  },
  {
    "uuid": "rec-002",
    "record_type": "MX",
    "name": "@",
    "value": "mail.example.com",
    "ttl": 3600,
    "priority": 10,
    "created_at": "2024-01-15T10:32:00Z"
  }
]

POST /api/v1/dns-zones/{uuid}/records/

Criar o registro DNS na zona

Adicionar um novo registro DNS a uma zona específica (rota nested).

Parâmetros do corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`record_type`	string	Sim	Record type: A, AAAA, CNAME, MX, TXT, NS, SRV, CAA
`name`	string	Sim	Record name (`@` for root, subdomain, or FQDN)
`value`	string	Sim	Record value (IP address, hostname, text)
`ttl`	integer	No	Time to live in seconds (default: 3600)
`priority`	integer	For MX/SRV	Priority (required for MX and SRV records)

Exemplo de solicitação

cURL

Python

curl -X POST "https://admin.vps.org/api/v1/dns-zones/{uuid}/records/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "record_type": "A",
    "name": "www",
    "value": "192.0.2.1",
    "ttl": 3600
  }'

import requests

url = f"https://admin.vps.org/api/v1/dns-zones/{zone_uuid}/records/"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "record_type": "A",
    "name": "www",
    "value": "192.0.2.1",
    "ttl": 3600
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Códigos de status de resposta

201	DNS record created successfully
400	Bad Request - Invalid parameters or validation error (e.g., MX record missing priority)

GET PUT PATCH DELETE /api/v1/dns-records/{uuid}/

Gerenciar DNS Records (Acesso Direto)

Operações completas CRUD em registros de DNS individuais usando registro UUID.

Operações Disponíveis

GET /api/v1/dns-records/{uuid}/ - Retrieve record details
PUT /api/v1/dns-records/{uuid}/ - Full update (all fields required)
PATCH /api/v1/dns-records/{uuid}/ - Partial update (only changed fields)
DELETE /api/v1/dns-records/{uuid}/ - Delete record

Parâmetros de consulta (para GET /api/v1/dns-records/)

Parameter	Tipo	Descrição
`zone`	string	Filter records by zone UUID
`record_type`	string	Filter by record type (A, AAAA, MX, etc.)

Exemplo: Atualizar o TTL de um registro

curl -X PATCH "https://admin.vps.org/api/v1/dns-records/{rec-uuid}/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttl": 1800}'

Supported DNS Record Types

Tipo	Purpose	Example Value	Priority Required
A	Maps domain to IPv4 address	192.0.2.1	Não
AAAA	Maps domain to IPv6 address	2001:0db8::1	Não
CNAME	Creates alias to another domain	example.com	Não
MX	Mail server for domain	mail.example.com	Sim
TXT	Text record (SPF, DKIM, verification)	v=spf1 include:_spf.google.com ~all	Não
NS	Nameserver delegation	ns1.example.com	Não
SRV	Service location record	10 5060 sip.example.com	Sim
CAA	Certificate authority authorization	0 issue "letsencrypt.org"	Não

Melhores práticas

Configuração TTL

Produção (estabelecimento): 3600-86400 segundos (1-24 horas)
Antes da migração: 300-600 segundos (5-10 minutos) - TTL inferior antes das alterações planejadas
Desenvolvimento: 300-1800 segundos (5-30 minutos) para testes mais rápidos

Padrões comuns

Domínio raíz (@): Utilizar registros A/AAAA, não CNAME
Subdomínio www: Pode usar CNAME apontando para root ou separado Um registro
E-mail (MX): Incluir sempre prioridade, menor número = maior prioridade
CNAME: Não pode coexistir com outros tipos de registro para o mesmo nome

Segurança

Registo da CAA: Especificar que CAs podem emitir certificados
SPF/DKIM/DMARC: Configure a autenticação de e-mail para evitar o spoofing
Auditorias regulares: Revisar registros de DNS trimestralmente, remover entradas não utilizadas

Tratamento de Erros

Erros Comuns

Código de status	Erro	Solução
400	Nome de domínio não válido	Assegurar que o domínio siga as convenções de nomeação do DNS
400	O registo MX requer prioridade	Incluir `priority` campo para os registros MX e SRV
401	Token API inválido	Controle o formato do token (deve iniciar com `vps_`)
403	Permissão ausente	Gerar um token novo com requerido `dns:*` Permissões
404	Zona/registo não encontrado	Verificar UUID e garantir que o recurso pertence a sua conta

Exemplo Resposta de Erro

{
  "detail": "MX records require a priority value",
  "error_code": "validation_error",
  "field": "priority"
}

Teste de Alterações DNS

Verificar Propagação de Registro

# Query A record
dig example.com A

# Query specific nameserver
dig @ns1.vps.org example.com

# Query MX records
dig example.com MX

# Check all records
dig example.com ANY

Usando Ferramentas Online

whatsmydns.net: Check global DNS propagation
dnschecker.org: Multi-location DNS lookup
mxtoolbox.com: Email-related DNS testing

VPS.org API

API de gerenciamento de DNS

Visão geral

Infraestrutura do servidor de nomes

Características-chave

Autenticação

Exemplo

Listar todas as zonas DNS

Parâmetros de consulta

Exemplo de solicitação

Exemplo de resposta

Campos de resposta

Códigos de status de resposta

Obter detalhes da zona DNS

Parâmetros de caminho

Exemplo de resposta

Códigos de status de resposta

Criar uma Zona DNS

Parâmetros do corpo da requisição

Exemplo de solicitação

Exemplo de resposta

Códigos de status de resposta

Apagar a Zona DNS

Parâmetros de caminho

Códigos de status de resposta

Listar os registros DNS na zona

Parâmetros de caminho

Exemplo de solicitação

Exemplo de resposta

Criar o registro DNS na zona

Parâmetros do corpo da requisição

Exemplo de solicitação

Códigos de status de resposta

Gerenciar DNS Records (Acesso Direto)

Operações Disponíveis

Parâmetros de consulta (para GET /api/v1/dns-records/)

Exemplo: Atualizar o TTL de um registro

Supported DNS Record Types

Melhores práticas

Configuração TTL

Padrões comuns

Segurança

Tratamento de Erros

Erros Comuns

Exemplo Resposta de Erro

Teste de Alterações DNS

Verificar Propagação de Registro

Usando Ferramentas Online