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

# Escopos da API Key

> Permissões para gerenciar templates e disparar envios multicanal.

<Tip>
  **`templates:*`** gerencia modelos; **`whatsapp:send`**, **`sms:send`**, etc. **disparam**. Ter `templates:create` **não** basta para enviar.
</Tip>

Cada **escopo** libera um tipo de operação em Templates. Use só o que sua integração precisa.

## Como enviar a chave

**Recomendado**

```http theme={null}
Authorization: Bearer sk_live_sua_chave_aqui
```

**Alternativo**

```http theme={null}
x-api-key: sk_live_sua_chave_aqui
```

<Info>
  A API Key pertence a **um** workspace. Você não acessa outro workspace com a mesma chave.
</Info>

## Duas famílias de escopo

| Família             | Para quê                                                                                                                                 |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **`templates:*`**   | Criar, listar, editar e apagar templates                                                                                                 |
| **Envio por canal** | Disparar com **Enviar por template** (`whatsapp:send`, `sms:send`, `email:send`, `telegram:send`, `rcs:send`, `push:send`, `voice:call`) |

<Warning>
  Ter `templates:create` **não** basta para enviar. No disparo, cada canal pedido precisa do escopo de envio daquele canal.
</Warning>

## Combinações comuns

<CardGroup cols={2}>
  <Card title="Só disparar" icon="paper-plane">
    `whatsapp:send`, `sms:send`, `email:send`, `rcs:send`, etc. (conforme canais usados)
  </Card>

  <Card title="Só gerenciar modelos" icon="folder">
    `templates:read`, `templates:create`, `templates:update`, `templates:delete`
  </Card>

  <Card title="App completo" icon="layer-group">
    Todos os `templates:*` + escopos de envio dos canais do template
  </Card>

  <Card title="Só consultar" icon="magnifying-glass">
    `templates:read`
  </Card>
</CardGroup>

<Warning>
  Lista de escopos **vazia** na criação = acesso **ADMIN**. Em produção, restrinja sempre.
</Warning>

## Escopos de gestão (`templates:*`)

<AccordionGroup>
  <Accordion title="templates:read">
    Listar templates e buscar detalhe por ID.
  </Accordion>

  <Accordion title="templates:create">
    Criar template novo no workspace.
  </Accordion>

  <Accordion title="templates:update">
    Editar template existente (canais, textos, padrões de variáveis, traduções).
  </Accordion>

  <Accordion title="templates:delete">
    Excluir template.
  </Accordion>
</AccordionGroup>

## Escopos de envio (por canal)

Na operação **Enviar por template**, valide o escopo de **cada** canal em `channels`:

| Canal em `channels` | Escopo necessário                     |
| ------------------- | ------------------------------------- |
| `whatsapp`          | `whatsapp:send`                       |
| `sms`               | `sms:send`                            |
| `email`             | `email:send`                          |
| `telegram`          | `telegram:send`                       |
| `rcs`               | `rcs:send`                            |
| `push`              | `push:send`                           |
| `voice`             | **`voice:call`** (não é `voice:send`) |

Status de **entrega** (enviado, entregue, falhou) vem dos **webhooks do canal**, não de um webhook de envio de template.

Status de **aprovação Meta** (aprovado, rejeitado, pausado, categoria) vem dos eventos **`template.*`**, veja [Eventos dos webhooks](/template-api/como-funciona/eventos-do-webhooks).

## Erros comuns

| Código HTTP | Situação                                                                                                       |
| ----------- | -------------------------------------------------------------------------------------------------------------- |
| **403**     | Escopo ausente (`Missing scope: templates:read`, `Missing scope: rcs:send`, `Missing scope: voice:call`, etc.) |
| **403**     | Créditos insuficientes para toda a requisição (`INSUFFICIENT_CREDITS`)                                         |
| **402**     | Limite de gasto da chave ou workspace bloqueado                                                                |

Detalhe na **referência da API** na aba Templates.

## Próximos passos

* [Quick Start](/template-api/como-funciona/quick-start)
* [Introdução](/template-api/como-funciona/introducao)
* [Templates oficiais Meta](/template-api/como-funciona/templates-oficiais-meta)
* [Eventos dos webhooks](/template-api/como-funciona/eventos-do-webhooks)