> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Configurar domínio personalizado

> Vincule um domínio personalizado a uma aplicação com POST /v2/apps/{app_id}/network/custom, ou envie @ para removê-lo. Disponível no Standard, Pro e Enterprise.

**É necessário ter pelo menos o [plano Standard](https://squarecloud.app/pt-br/pricing) para usar esta rota.**

A mesma conta pode associar um domínio a várias aplicações (balanceamento de carga): até 2 aplicações no Standard, 5 no Pro e 10 no Enterprise. Veja [Listar balanceadores de carga](/pt-br/api-reference/endpoint/apps/network/load-balancers).

<ParamField header="Authorization" type="string" placeholder="Chave da API" required>
  A chave da API para sua conta. Você pode encontrá-la nas [configurações da conta](https://squarecloud.app/pt-br/account/security).
</ParamField>

Requer uma chave de API com o [escopo](/pt-br/api-reference/authentication#escopos) `apps:write`.

Substituir um domínio personalizado existente libera o hostname anterior na borda antes de associar o novo, a menos que outra aplicação na mesma conta ainda aponte para ele. A mesma validação roda tanto ao associar quanto ao remover (`custom: "@"`): em uma aplicação compartilhada em workspace, quem chama precisa da [função](/pt-br/api-reference/endpoint/workspace/members/invite#funções) `admin` no workspace ou ser o proprietário.

Um domínio só pode ser reivindicado por uma conta por vez: associar um hostname já pertencente a outra conta retorna `DOMAIN_ALREADY_EXISTS`. Para ver todos os hostnames configurados nas suas aplicações, veja [Listar domínios](/pt-br/api-reference/endpoint/apps/domains). Depois de associado, obtenha os registros de validação necessários com [Obter registros DNS](/pt-br/api-reference/endpoint/apps/network/dns).

## Parâmetros

<ParamField path="app_id" type="string" placeholder="ID da Aplicação" required>
  O ID da aplicação. Você pode encontrá-lo na URL da sua aplicação no dashboard.
</ParamField>

<ParamField body="custom" type="string" placeholder="exemplo.com" required>
  O domínio totalmente qualificado a associar, ou `@` para remover o domínio personalizado atual da aplicação. Não pode ser um domínio da Square Cloud (`squareweb.app`, `squarecloud.app`, ...).
</ParamField>

## Resposta

<ResponseField name="status" type="string">
  Indica se a chamada foi bem-sucedida: `success` se foi, `error` se não.
</ResponseField>

Em caso de falha, a resposta inclui um `code` de erro:

| Status | Code | Significado |
| - | - | - |
| `400` | `INVALID_DOMAIN` | O domínio não é um domínio totalmente qualificado válido. |
| `400` | `RESERVED_DOMAIN` | Domínios da Square Cloud não podem ser usados como domínio personalizado. |
| `403` | `UPGRADE_REQUIRED` | O plano ativo não inclui domínios personalizados (requer Standard, Pro ou Enterprise). |
| `403` | `LOAD_BALANCER_LIMIT_REACHED` | O limite de aplicações neste domínio para o plano foi atingido. |
| `409` | `DOMAIN_ALREADY_EXISTS` | O domínio já está associado a uma aplicação de outra conta. |
| `502` | `DNS_FAILED` | A associação do domínio falhou no provedor de edge. |

<ResponseExample>
  ```json theme={"system"}
  {
      "status": "success"
  }
  ```
</ResponseExample>

## Relacionados

* CLI: [`squarecloud app network domain`](/pt-br/cli-reference/domains#squarecloud-app-network-domain)
* SDKs: [`api.apps.network.setDomain()`](/pt-br/sdks/js/network) (JavaScript), [`client.apps.network.set_domain()`](/pt-br/sdks/py/network) (Python), [`c.Apps.Network.SetDomain()`](/pt-br/sdks/go/network) (Go)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.