# Domínios e DNS

Zonas DNS da empresa no Cloudflare, registros com proteções para MX, NS e apex, e subdomínios da zona da ArduMaker.

Fonte: https://ardumaker.com/pt/docs/dominios-y-dns/

- Categoria: Servidores e infraestrutura
- Estado: Disponível
- Requisitos: Uma empresa na ArduMaker; Para adicionar ou excluir um domínio e para editar registros: ser admin da empresa; Para criar registros: ser membro ou admin da empresa; Acesso ao painel do registrador onde o domínio foi comprado, para mudar os nameservers
- Ferramentas MCP (Só leem): `listar_dominios_empresa`, `ver_dominio_empresa`, `ver_estado_ns_dominio`, `listar_registros_dns`, `verificar_dominio_vps`
- Ferramentas MCP (Escrevem ou modificam): `crear_dominio_empresa`, `crear_registro_dns`, `crear_dominio_vps`
- Ferramentas MCP (Destrutivas): `eliminar_dominio_empresa`, `editar_registro_dns`

## O que permite fazer?

### Domínios próprios da empresa

- Adicionar um domínio: a ArduMaker cria a zona no Cloudflare e devolve os nameservers para onde é preciso apontá-lo.
- Consultar se os nameservers já apontam (`is_connected`) e o estado da zona.
- Listar, criar e editar registros A, AAAA, CNAME, MX, TXT, NS, SRV e CAA.
- Retirar um domínio da empresa (exclusão lógica: a zona e os registros não são tocados, e pode ser reativado).

### Subdomínios da zona da ArduMaker

- Criar um subdomínio da zona da plataforma que aponte para um VPS, sem ter domínio próprio.
- Verificar para onde resolve qualquer domínio antes de o publicar em um VPS.

## Quando convém usar?

- Passar a gestão DNS de um domínio próprio para a ArduMaker para o usar com VPS, correio e apps.
- Adicionar os registros que um serviço externo pede (verificação TXT, MX de correio, CAA).
- Testar uma app rapidamente com um subdomínio da zona da ArduMaker.

## Como funciona na ArduMaker?

### Ligar um domínio próprio

1. Um admin adiciona o domínio (`crear_dominio_empresa`). A zona é criada no Cloudflare e são devolvidos os `name_servers`. Se o domínio estava excluído na mesma empresa, é reativado em vez de duplicado. Se é de outra empresa, é rejeitado.
2. No registrador, os nameservers são substituídos pelos que a ArduMaker devolveu.
3. `ver_estado_ns_dominio` consulta o Cloudflare em tempo real e guarda o estado; `is_connected: true` indica que a delegação já está ativa.
4. A partir daí os registros são geridos na ArduMaker.

### Registros e as suas proteções

- **Registros críticos**: qualquer `MX` ou `NS`, e um `A` ou `AAAA` no apex (nome vazio, `@` ou o próprio domínio). Criá-los ou editá-los sem `confirmado=true` responde 409 com `requiere_confirmacion` e o motivo.
- **Conteúdo**: um `A` tem de ser um IPv4 e um `AAAA` um IPv6 (`dns_contenido_invalido`). O resto é validado pelo Cloudflare, e a sua rejeição chega como `dns_rechazado`.
- **Limite**: 10 criações ou alterações por empresa por minuto. O orçamento da API do Cloudflare é compartilhado por todos os clientes; passado o teto a resposta é 429.
- **Editar substitui** o registro inteiro (não é uma mescla de campos).
- `ttl: 1` significa automático. `proxied` só se aplica a A, AAAA e CNAME; `priority` a MX e SRV.

### Subdomínios da zona da ArduMaker

`crear_dominio_vps` cria sempre um **CNAME** para o `dnsip` do VPS (`<slug>.<zona>`), com o proxy do Cloudflare ativado. Regras do nome: um ou dois níveis antes da zona, cada um com pelo menos 3 caracteres, com letras, números e hífens no meio. Se o registro já existe e aponta para outro destino, é rejeitado; se já aponta para este VPS, é devolvido como `exists`.

Cada VPS tem o seu `dnsip`, um nome na zona da ArduMaker que substitui o IP real do host em toda a API. Para um domínio próprio, basta um CNAME para esse `dnsip` ou um registro A para o IP que ele resolve.

## O que muda realmente?

- No Cloudflare: a zona do domínio e os registros criados ou editados. As alterações DNS demoram a propagar mesmo que sejam corrigidas logo.
- Na ArduMaker: a linha do domínio (estado `active` ou `deleted`) e uma entrada de auditoria por cada criação, edição ou exclusão de registro, com quem a fez, o domínio e o registro.
- Se a empresa ficar pendente de verificação de identidade, as suas zonas podem ficar pausadas até ser verificada.

## Esquema

**Cadeia DNS de um domínio até um VPS**

```text
Registrador (nameservers do Cloudflare)
  ↓
Zona no Cloudflare (registros da empresa)
  ↓
CNAME / A (para o dnsip do VPS ou o IP que ele resolve)
  ↓
Host do VPS (o nginx publica o domínio (ver Nginx))
```

## Resultado esperado

- `crear_dominio_empresa` devolve `name_servers`, `cloudflare_status` e `already_existed`.
- `ver_estado_ns_dominio` e `ver_dominio_empresa` mostram `is_connected` e `name_servers`; se o Cloudflare não responde, o domínio sai na mesma com `cloudflare_error`.
- Os registros criados ou editados voltam com o objeto completo do Cloudflare (`id`, `type`, `name`, `content`, `proxied`, `ttl`).
- Para publicar o domínio em um VPS, seguir com [Nginx](https://ardumaker.com/pt/docs/nginx) e [Certificados SSL](https://ardumaker.com/pt/docs/ssl).

## Erros e resolução

| Resposta | Causa | O que fazer |
| --- | --- | --- |
| 409 `requiere_confirmacion` | Registro crítico (MX, NS, A/AAAA no apex) | Rever e reenviar a mesma chamada com `confirmado=true` |
| 429 | Mais de 10 alterações DNS por minuto na empresa | Esperar um minuto |
| 400 `dns_contenido_invalido` | IP mal escrito para A ou AAAA | Corrigir o conteúdo |
| 400 `dns_rechazado` | O Cloudflare rejeitou o registro (duplicado, formato) | Ler a mensagem e corrigir |
| 424 `dependencia_externa` | O Cloudflare não respondeu; nada foi alterado | Tentar de novo daqui a pouco |
| 403 `unauthorized_admin_access_required` | A operação é só para admins da empresa | Pedir a um admin |
| `is_connected: false` | Os nameservers do registrador ainda não apontam para o Cloudflare | Alterá-los no registrador e esperar a propagação |

> **PRECAUCION:** `crear_registro_dns` e `crear_dominio_empresa` não são idempotentes por si só: para tentar de novo após um corte, usar a mesma `idempotency_key` e os mesmos argumentos, ou o registro é duplicado.

## Relação com MCP

Sim. As ferramentas de domínios da empresa estão nos perfis `/mcp` e `/mcp/infra`; as de subdomínios de um VPS, em `/mcp` e `/mcp/vps`.

| Ferramenta | Tipo | Notas |
| --- | --- | --- |
| `listar_dominios_empresa`, `ver_dominio_empresa`, `ver_estado_ns_dominio`, `listar_registros_dns` | Leitura | Estado de zonas e registros |
| `crear_dominio_empresa` | Escrita | Só admin; aceita `idempotency_key` |
| `crear_registro_dns` | Escrita | Membro ou admin; `confirmado` para registros críticos |
| `editar_registro_dns` | Destrutiva | Só admin; substitui o registro inteiro |
| `eliminar_dominio_empresa` | Destrutiva | Só admin; exclusão lógica, reversível com `crear_dominio_empresa` |
| `verificar_dominio_vps`, `crear_dominio_vps` | Leitura / Escrita | Subdomínios da zona para um VPS |

**Excluir um registro DNS não tem ferramenta MCP**, de propósito: é irreversível no momento e o seu efeito propaga-se para fora. Faz-se a partir do painel. Referência em [/mcp/docs](https://ardumaker.com/pt/mcp/docs) e exemplos em [/mcp/dominios](https://ardumaker.com/pt/mcp/dominios).

## Funcionalidades relacionadas

- [Nginx](https://ardumaker.com/pt/docs/nginx/)
- [Certificados SSL](https://ardumaker.com/pt/docs/ssl/)
- [Email profissional](https://ardumaker.com/pt/docs/correo-profesional/)
- [Servidores VPS](https://ardumaker.com/pt/docs/vps/)