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

> Permisos para contactos, etiquetas, temas, segmentos y campañas.

<Tip>
  Cinco familias: **`contacts`**, **`tags`**, **`topics`**, **`segments`**, **`campaigns`**. Las campañas también exigen alcances de **envío** por canal (`whatsapp:send`, `sms:send`, …).
</Tip>

Cada **alcance** desbloquea un tipo de operación en Contactos. Use solo lo que su integración necesita.

## Cómo enviar la clave

**Recomendado**

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

**Alternativo**

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

<Info>
  Cada clave API pertenece a **un** espacio de trabajo. No puede acceder a otro espacio de trabajo con la misma clave.
</Info>

## Combinaciones comunes

<CardGroup cols={2}>
  <Card title="Solo leer base" icon="magnifying-glass">
    `contacts:read`, `tags:read`
  </Card>

  <Card title="Sincronizar CRM" icon="rotate">
    `contacts:read`, `contacts:create`, `contacts:update`, `tags:read`, `tags:create`
  </Card>

  <Card title="Campañas vía API" icon="paper-plane">
    `campaigns:read`, `campaigns:create`, `campaigns:run` + alcances de envío de los canales
  </Card>

  <Card title="Gestión completa" icon="address-book">
    Todos los `contacts:*`, `tags:*`, `topics:*`, `segments:*`, `campaigns:*`
  </Card>
</CardGroup>

<Warning>
  Lista de alcances **vacía** al crear = acceso **ADMIN** (todo). En producción, restrinja siempre.
</Warning>

## Contactos (`contacts:*`)

<AccordionGroup>
  <Accordion title="contacts:read">
    Listar y obtener contacto por ID.
  </Accordion>

  <Accordion title="contacts:create">
    Crear contacto (teléfono y/o correo obligatorio).
  </Accordion>

  <Accordion title="contacts:update">
    Editar ficha, etiquetas y campos.
  </Accordion>

  <Accordion title="contacts:delete">
    Eliminar contacto.
  </Accordion>
</AccordionGroup>

## Etiquetas (`tags:*`)

<AccordionGroup>
  <Accordion title="tags:read">
    Listar y obtener etiqueta.
  </Accordion>

  <Accordion title="tags:create">
    Crear etiqueta reutilizable.
  </Accordion>

  <Accordion title="tags:update">
    Renombrar etiqueta.
  </Accordion>

  <Accordion title="tags:delete">
    Eliminar etiqueta.
  </Accordion>
</AccordionGroup>

## Temas (`topics:*`)

Consentimiento por **tema** de marketing (Newsletter, Promociones). Igual que en el panel en **Audience → Topics**.

<AccordionGroup>
  <Accordion title="topics:read">
    Listar y obtener tema.
  </Accordion>

  <Accordion title="topics:create">
    Crear tema con slug estable.
  </Accordion>

  <Accordion title="topics:update">
    Editar nombre, descripción y opt-in predeterminado.
  </Accordion>

  <Accordion title="topics:delete">
    Eliminar tema.
  </Accordion>
</AccordionGroup>

## Segmentos (`segments:*`)

Audiencias con **reglas** (etiquetas, campos, temas, marketing). Incluye **preview** antes de campañas.

<AccordionGroup>
  <Accordion title="segments:read">
    Listar, obtener y **preview** (muestra paginada de la audiencia).
  </Accordion>

  <Accordion title="segments:create">
    Crear segmento con JSON `version: 1`, `match`, `rules`.
  </Accordion>

  <Accordion title="segments:update">
    Editar reglas del segmento.
  </Accordion>

  <Accordion title="segments:delete">
    Eliminar segmento.
  </Accordion>
</AccordionGroup>

## Campañas (`campaigns:*`)

<AccordionGroup>
  <Accordion title="campaigns:read">
    Listar, obtener, **estadísticas** y **destinatarios** por ejecución.
  </Accordion>

  <Accordion title="campaigns:create">
    Crear campaña (opcionalmente con `scheduledFor`).
  </Accordion>

  <Accordion title="campaigns:update">
    Editar campaña y **cancelar** (DRAFT/SCHEDULED → CANCELLED).
  </Accordion>

  <Accordion title="campaigns:delete">
    Eliminar campaña.
  </Accordion>

  <Accordion title="campaigns:run">
    **Disparar ahora** (Run); encola envíos en los canales de la campaña.
  </Accordion>
</AccordionGroup>

<Warning>
  Disparar una campaña exige `campaigns:run` **y** alcances de envío de cada canal (`whatsapp:send`, `sms:send`, `email:send`, `telegram:send`) cuando la cola procese mensajes.
</Warning>

## Errores comunes

<AccordionGroup>
  <Accordion title="403: alcance ausente">
    Verifique el alcance de la operación (`Missing scope: contacts:read`, etc.).
  </Accordion>

  <Accordion title="402: límite CRM o espacio de trabajo bloqueado">
    Plan o límite `PLAN_LIMIT_CRM`. Regularice en el panel.
  </Accordion>

  <Accordion title="409: duplicado">
    Teléfono o correo ya registrado en el espacio de trabajo.
  </Accordion>
</AccordionGroup>

## Próximos pasos

* [Inicio rápido](/es/contacts-api/como-funciona/quick-start)
* [Introducción](/es/contacts-api/como-funciona/introducao)
* [Campañas](/es/contacts-api/como-funciona/campanhas-no-painel)
* [Claves API (guía)](/es/guides/api-key/index)