> ## 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.

# Alcances clave API

> Qué permisos necesita su clave para conectarse, enviar y administrar WhatsApp en Notifique.

<Tip>
  La **clave API** es la tarjeta de acceso del edificio: cada **alcance** abre una puerta. En producción, conceda solo lo que su integración necesita.
</Tip>

## En breve

* Cada clave pertenece a **un espacio de trabajo**.
* Los alcances `whatsapp:*` cubren instancias, envío y lectura del canal.
* El campo **`instanceIds`** restringe **qué números** puede usar la clave.
* Contactos, etiquetas y plantillas multicanal usan alcances **aparte** (solo si los necesita).

Guía general: [Claves API](/es/guides/api-key/index). Conexión: [Inicio rápido](/es/whatsapp-api/como-funciona/quick-start).

***

## Cómo enviar la clave

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

Alternativa: `x-api-key: sk_live_xxxxx`.

<Warning>
  Alcances **vacíos** al crear = acceso **ADMIN** (todo). En producción, restrinja siempre.
</Warning>

***

## Combinaciones listas

<CardGroup cols={2}>
  <Card title="Conectar y enviar" icon="whatsapp">
    `whatsapp:instances:create`, `whatsapp:instances:list`, `whatsapp:send`
  </Card>

  <Card title="Solo enviar" icon="paper-plane">
    `whatsapp:send` + `instanceIds` con el id del número
  </Card>

  <Card title="Bot / soporte" icon="message">
    `whatsapp:send`, `whatsapp:read`
  </Card>

  <Card title="Operar el número" icon="gear">
    `whatsapp:instances:list`, `whatsapp:instances:disconnect`, `whatsapp:instances:delete`
  </Card>
</CardGroup>

***

## Alcances disponibles

<AccordionGroup>
  <Accordion title="whatsapp:instances:list">
    Listar instancias, ver detalles y obtener código/QR.
  </Accordion>

  <Accordion title="whatsapp:instances:create">
    Crear instancia (oficial o no oficial, con o sin enlace compartible).
  </Accordion>

  <Accordion title="whatsapp:instances:disconnect">
    Desconectar sesión activa.
  </Accordion>

  <Accordion title="whatsapp:instances:delete">
    Eliminar instancia (solo cuando esté desconectada).
  </Accordion>

  <Accordion title="whatsapp:send">
    Enviar texto, medios, plantillas, botones y listas.
  </Accordion>

  <Accordion title="whatsapp:read">
    Historial de enviados, estado por id y mensajes recibidos (inbound).
  </Accordion>

  <Accordion title="whatsapp:update">
    Editar mensaje enviado.
  </Accordion>

  <Accordion title="whatsapp:cancel">
    Cancelar programado o en cola.
  </Accordion>

  <Accordion title="whatsapp:delete">
    Eliminar para todos.
  </Accordion>

  <Accordion title="whatsapp:groups">
    Grupos, participantes, invitaciones y envío a JID de grupo. Requiere instancia **no oficial**. Guía: [Grupos WhatsApp](/es/whatsapp-api/grupos/introducao).
  </Accordion>
</AccordionGroup>

***

## Restringir por número (`instanceIds`)

Además del alcance (el **qué**), `instanceIds` define **dónde**:

| Situación                            | Resultado           |
| ------------------------------------ | ------------------- |
| Envío en instancia fuera de la lista | **403**             |
| Listar instancias                    | Solo las permitidas |
| Inbound y consultas                  | Misma regla         |

Ejemplo: ERP que solo envía desde soporte → `whatsapp:send` + `instanceIds: ["clxx123..."]`.

***

## Otros alcances (si los necesita)

| Área                 | Alcances                                                                     |
| -------------------- | ---------------------------------------------------------------------------- |
| Contactos            | `contacts:read`, `contacts:create`, `contacts:update`, `contacts:delete`     |
| Etiquetas            | `tags:read`, `tags:create`, `tags:update`, `tags:delete`                     |
| Plantillas (gestión) | `templates:read`, `templates:create`, `templates:update`, `templates:delete` |

<Info>
  Enviar por plantilla (`POST /v1/templates/send`) usa `whatsapp:send` (y otros canales), no `templates:*`. Detalles: [Alcances de plantillas](/es/template-api/como-funciona/escopos-da-api-key).
</Info>

***

## Errores comunes

| HTTP    | Significado                                            | Qué verificar                               |
| ------- | ------------------------------------------------------ | ------------------------------------------- |
| **401** | Clave ausente, inválida o revocada                     | `Authorization: Bearer sk_...`              |
| **403** | Alcance ausente, instancia bloqueada o límite del plan | Alcance de la ruta, `instanceIds`, créditos |

Más códigos: [Respuestas de error](/es/guides/conceitos/resposta-de-erros).

***

## Próximos pasos

* [Inicio rápido](/es/whatsapp-api/como-funciona/quick-start): conectar y enviar
* [Eventos webhook](/es/whatsapp-api/como-funciona/eventos-do-webhooks): estado en su servidor
* [Claves API](/es/guides/api-key/index): crear y rotar claves