# Criar instância

`POST /instance/create`

Pasta: **Administração**

## Autenticação

```http
admintoken: {{adminToken}}
```

## Descrição

# Criar instância

Cria uma nova instância WhatsApp no tenant. Use quando for provisionar um número/conta novo; a instância nasce desconectada e recebe um `token` exclusivo na resposta.

## Endpoint

`POST {{baseUrl}}/instance/create`

## Autenticação

Envie o token de administrador no header `admintoken: {{adminToken}}`.

## Corpo da requisição

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `name` | string | Não | Nome amigável da instância. |
| `connection_mode` | string | Não | `companion` (padrão, QR/pair code), `mobile` (socket nativo) ou `migration`. |
| `phone` / `owner` | string | Condicional | Número com DDI, só dígitos (ex.: `5511999999999`). Obrigatório quando `connection_mode` é `mobile`. `phone` preenche `owner` se este estiver vazio. |
| `adminField01` | string | Não | Metadado administrativo livre. |
| `adminField02` | string | Não | Metadado administrativo livre. |
| `token` | string | Não | Se omitido, a API gera um token automaticamente. |
| `proxy_mode` | string | Não | Padrão `dynamic`. |

## Exemplo de Requisição

```bash
curl --request POST '{{baseUrl}}/instance/create' \
  --header 'admintoken: {{adminToken}}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "minha-instancia",
  "connection_mode": "companion",
  "adminField01": "cliente-premium",
  "adminField02": "plano-enterprise"
}'
```

## Resposta de Sucesso

**Status:** `201 Created`

```json
{
  "success": true,
  "token": "inst_abc123",
  "instance": {
    "id": "uuid-da-instancia",
    "name": "minha-instancia",
    "status": "disconnected",
    "token": "inst_abc123",
    "connection_mode": "companion",
    "proxy_mode": "dynamic",
    "proxy_enabled": true
  }
}
```

## Erros comuns

- `401 Unauthorized`: `admintoken` ausente ou inválido.
- `400 Bad Request`: modo mobile sem `phone`/`owner` válido.
- `403 Forbidden`: cota de instâncias esgotada (`quota exceeded`).

## Observações

- Guarde o `token` retornado: ele autentica as demais rotas da instância.
- Em `mobile`, o número precisa ter DDI e só dígitos; a plataforma padrão é `ios` e `isBusiness` fica `true`.
- Depois de criar, conecte com `POST /instance/connect` (ou o fluxo mobile correspondente).

## Corpo (exemplo)

```json
{
  "name": "minha-instancia",
  "connection_mode": "companion",
  "adminField01": "cliente-premium",
  "adminField02": "plano-enterprise"
}
```

## cURL

```bash
curl -X POST "{{baseUrl}}/instance/create" \
  -H "admintoken: {{adminToken}}" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "minha-instancia",
  "connection_mode": "companion",
  "adminField01": "cliente-premium",
  "adminField02": "plano-enterprise"
}'
```

---

[Índice da pasta](./index.md) · [Índice geral](../index.md) · [UI](https://gozap.dev/docs?op=administracao/criar-instancia)