# Criar instância e emitir token

`POST /instance/init`

Não pareia nem conecta. Guardar instance.id e instance.token no backend; listar não recupera o token. kind=whatsapp por padrão; kind=calls cria um dispositivo vinculado próprio para voz.

## Autenticação

Header obrigatório: `admintoken`. Use o token administrativo do servidor.

Base URL: a API do servidor selecionado, como `https://1.atendro.cloud`. O domínio `wpp.atendro.cloud` hospeda a documentação e o console.

**Idempotência:** suporta `Idempotency-Key`, com retenção de 15 minutos. Preserve a mesma chave, método, caminho e bytes do corpo ao repetir. [Entenda a idempotência](https://wpp.atendro.cloud/docs/guias/erros-e-idempotencia.md).

## Headers adicionais

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `X-Request-Id` | `string` | opcional | ASCII visível sem espaços, 1–128 caracteres. Inválido/ausente é substituído por UUID. Ecoado na resposta. Comprimento máximo: `128` |
| `Idempotency-Key` | `string` | opcional | ASCII visível sem espaços, 1–128. Repetir método, caminho e os mesmos bytes do JSON. 409 em andamento; 422 se mudar a requisição. 504 é guardado e não deve causar reenvio automático. Comprimento mínimo: `1`. Comprimento máximo: `128` |

## Corpo da requisição

Formato: `application/json`. Corpo obrigatório.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `name` | `string` | obrigatório | Obrigatório, até 128 bytes UTF-8, sem controle ou espaços nas extremidades. Comprimento mínimo: `1`. Comprimento máximo: `128` |
| `systemName` | `string` | opcional | Até 128 bytes; recomendado Atendro. Comprimento máximo: `128` |
| `companyId` | `string` | opcional | Até 128 bytes; vínculo com tenant no consumidor. Filtro de lista, não autorização. Comprimento máximo: `128` |
| `kind` | `string` | opcional | Imutável após criar. calls exige o módulo habilitado e pareamento próprio. Valores: `"whatsapp"`, `"calls"`. Padrão: `"whatsapp"` |

## Resposta 200

Criar instância e emitir token

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `response` | `string` | obrigatório | — |
| `connected` | `boolean` | obrigatório | Valores: `false` |
| `loggedIn` | `boolean` | obrigatório | Valores: `false` |
| `instance` | `object` | obrigatório |  Modelo: [IssuedInstance](https://wpp.atendro.cloud/docs/modelos/issued-instance.md). |

Exemplo ilustrativo, com valores sintéticos:

```json
{
  "connected": false,
  "instance": {
    "id": "00000000-0000-4000-8000-000000000001",
    "kind": "whatsapp",
    "name": "instancia-de-teste",
    "owner": "",
    "profileName": "",
    "qrcode": "",
    "status": "disconnected",
    "token": "0000000000000000000000000000000000000000000000000000000000000000"
  },
  "loggedIn": false,
  "response": "Instance created"
}
```

## Resposta 400

invalid_name, invalid_kind ou invalid_json.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

## Resposta 401

unauthorized: header ausente, inválido ou duplicado. Bearer/query/instancekey não substituem admintoken/token.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

Exemplo ilustrativo, com valores sintéticos:

```json
{
  "error": "unauthorized"
}
```

## Resposta 409

Conflito de sessão ou idempotency_in_progress; respeitar o código error.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

## Resposta 422

Falha semântica da operação ou idempotency_mismatch.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

## Resposta 501

calls_not_supported ao solicitar kind=calls com o módulo desligado.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

## Resposta 502

storage_unavailable (Retry-After=5). Algumas rotas também retornam 502 por falha da conexão/mídia; consultar error.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

Exemplo ilustrativo, com valores sintéticos:

```json
{
  "error": "storage_unavailable"
}
```

## Resposta default

Falha; usar HTTP status e error. 404 rota inexistente; 405 método inválido com Allow. Ver catálogo no guia de integração.

| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
| `error` | `string` | obrigatório | — |
| `message` | `string` | opcional | — |
| `messageid` | `string` | opcional | ID para reconciliação quando o resultado é ambíguo. |
| `messageId` | `string` | opcional | — |
| `id` | `string` | opcional | — |
| `provider_code` | `integer` | opcional | — |
| `error_key` | `string` | opcional | — |
| `error_source` | `string` | opcional | — |
| `details` | `object` | opcional | — |
| `instance` | `object` | opcional |  Modelo: [Instance](https://wpp.atendro.cloud/docs/modelos/instance.md). |

## Exemplos de requisição

Defina as variáveis no ambiente privado e substitua os dados sintéticos antes de usar. Os exemplos não executam operações nesta página.

### cURL

```sh
curl --request POST "$ATENDROZAP_URL/instance/init" \
  --header "admintoken: $ATENDROZAP_ADMIN_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{
  "name": "atendimento-teste",
  "systemName": "Atendro",
  "companyId": "empresa-teste"
}'
```

### JavaScript

```javascript
const baseUrl = process.env.ATENDROZAP_URL;
let path = "/instance/init";
const url = new URL(path, baseUrl);

const response = await fetch(url, {
  method: "POST",
  headers: {
    "admintoken": process.env.ATENDROZAP_ADMIN_TOKEN,
    "Content-Type": "application/json",
    "Idempotency-Key": process.env.IDEMPOTENCY_KEY
  },
  body: JSON.stringify({
    "name": "atendimento-teste",
    "systemName": "Atendro",
    "companyId": "empresa-teste"
  }),
});

if (!response.ok) {
  throw new Error(`AtendroZAP: HTTP ${response.status}`);
}
const result = await response.json();
```

## Relacionados

- [Instâncias](https://wpp.atendro.cloud/docs/api/instancias.md)
- [Autenticação](https://wpp.atendro.cloud/docs/guias/autenticacao.md)
- [Erros e idempotência](https://wpp.atendro.cloud/docs/guias/erros-e-idempotencia.md)