# Inicio rápido

> Crea una clave API, compruébala, lista tus leads, importa contactos y crea un webhook: tu primera integración con WhatSetter en cinco minutos.

Source: https://docs.whatsetter.com/es/developers/quickstart/

Cinco peticiones, en cURL, JavaScript y Python. Al final tienes una clave, una lista de contactos y un webhook que te avisa cuando un lead queda calificado.

## Antes de empezar

- Eres **propietario** o **admin** de tu espacio de WhatSetter. La página de la API lo dice: **Solo los propietarios y admins pueden gestionar las claves API.**
- Tienes `curl`, Node.js 18 o más reciente, o Python 3 con `requests`.
- La URL base es `https://app.whatsetter.com/api/v1`.

## 1. Crea una clave API

1. Abre **Configuración**, luego **API y MCP**.
2. Haz clic en **Crear una clave**.
3. Rellena **Nombre de la clave** (por ejemplo `Sync CRM`) y elige los **Permisos**: **Acceso completo**, o **Personalizado** para marcar los scopes uno a uno.
4. Haz clic en **Crear la clave**.
5. Copia la clave. El diálogo lo dice: **Copia tu clave ahora. No volverá a mostrarse.** Luego haz clic en **Ya guardé mi clave**.

Guárdala en una variable de entorno, nunca en tu código:

```bash
export WHATSETTER_API_KEY="ws_live_…"
```

> **¿Perdiste la clave?**
WhatSetter solo guarda una huella de la clave. Si la pierdes, haz clic en **Revocar** en esa clave y crea una nueva.

## 2. Comprueba la clave

[GET /me](/api-reference/operations/getme/) no necesita ningún scope. Te dice qué espacio y qué permisos tiene la clave.

**cURL**

```bash
curl https://app.whatsetter.com/api/v1/me \
  -H "Authorization: Bearer $WHATSETTER_API_KEY"
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/me', {
  headers: { Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}` },
});
console.log(await res.json());
```

**Python**

```python
import os, requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/me",
    headers={"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"},
)
print(r.json())
```

```json
{
  "data": {
    "team_id": "6b0c1d2e3f405162738a",
    "key": {
      "id": "66f1a2b3c4d5e6f7a8b9c0d1",
      "name": "Sync CRM",
      "scopes": ["leads:read", "leads:write", "lists:write", "webhooks:manage"]
    }
  }
}
```

Un `401 invalid_api_key` significa que la clave está mal copiada o revocada. Un `401 missing_api_key` significa que la cabecera no nos llegó.

## 3. Lista tus leads

[GET /leads](/api-reference/operations/listleads/) necesita `leads:read`. Filtra por `status`, `campaign_id`, `phone`, `source` o `since`, y pagina con `limit` (1 a 100) y `cursor`.

**cURL**

```bash
curl "https://app.whatsetter.com/api/v1/leads?status=qualified&limit=10" \
  -H "Authorization: Bearer $WHATSETTER_API_KEY"
```

**JavaScript**

```js
const url = new URL('https://app.whatsetter.com/api/v1/leads');
url.searchParams.set('status', 'qualified');
url.searchParams.set('limit', '10');

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}` },
});
const { data, pagination } = await res.json();
console.log(data.length, pagination.next_cursor);
```

**Python**

```python
import os, requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/leads",
    params={"status": "qualified", "limit": 10},
    headers={"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"},
)
body = r.json()
print(len(body["data"]), body["pagination"]["next_cursor"])
```

```json
{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0d1",
      "phone": "33612345678",
      "name": "Julien",
      "status": "qualified",
      "qualified": true,
      "qualified_at": "2026-09-18T09:12:41.000Z",
      "campaign_id": "acme-france-1-ab12",
      "source": "list",
      "tags": ["hot"],
      "messages_count": 14,
      "last_message_at": "2026-09-18T09:12:00.000Z",
      "last_message_direction": "inbound"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": null }
}
```

El objeto lead está recortado aquí. Cuando `has_more` es `true`, devuelve `next_cursor` como `cursor` para obtener la página siguiente.

## 4. Importa una lista de contactos

Dos llamadas: [POST /lists](/api-reference/operations/createlist/) crea una lista vacía y luego [`POST /lists/{id}/leads`](/api-reference/operations/importleads/) sube hasta 500 contactos por llamada. Ambas necesitan `lists:write`. Los teléfonos se deduplican dentro del lote y contra la lista.

**cURL**

```bash
# 1. Crear la lista
curl -X POST https://app.whatsetter.com/api/v1/lists \
  -H "Authorization: Bearer $WHATSETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sync CRM, leads calientes"}'

# 2. Subir contactos (sustituye LIST_ID por el id del paso 1)
curl -X POST https://app.whatsetter.com/api/v1/lists/LIST_ID/leads \
  -H "Authorization: Bearer $WHATSETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"leads":[{"phone":"+34612345678","name":"Julia","custom_variables":{"ciudad":"Madrid"}}]}'
```

**JavaScript**

```js
const headers = {
  Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}`,
  'Content-Type': 'application/json',
};

// 1. Crear la lista
const created = await fetch('https://app.whatsetter.com/api/v1/lists', {
  method: 'POST',
  headers,
  body: JSON.stringify({ name: 'Sync CRM, leads calientes' }),
});
const { data: list } = await created.json();

// 2. Subir contactos
const imported = await fetch(`https://app.whatsetter.com/api/v1/lists/${list.id}/leads`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    leads: [{ phone: '+34612345678', name: 'Julia', custom_variables: { ciudad: 'Madrid' } }],
  }),
});
console.log(await imported.json());
```

**Python**

```python
import os, requests

headers = {"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"}
base = "https://app.whatsetter.com/api/v1"

# 1. Crear la lista
lst = requests.post(f"{base}/lists", headers=headers,
                    json={"name": "Sync CRM, leads calientes"}).json()["data"]

# 2. Subir contactos
r = requests.post(
    f"{base}/lists/{lst['id']}/leads",
    headers=headers,
    json={"leads": [{"phone": "+34612345678", "name": "Julia",
                     "custom_variables": {"ciudad": "Madrid"}}]},
)
print(r.json())
```

```json
{
  "data": {
    "imported": 1,
    "duplicates_in_list": 0,
    "rejected": [],
    "lead_ids": ["66f1a2b3c4d5e6f7a8b9c0d2"]
  }
}
```

> **Importar todavía no envía ningún mensaje**
Una lista es un depósito de contactos. El primer mensaje sale cuando la lista se vincula a una campaña, al ritmo del [motor anti-ban](/es/dashboard/anti-ban/). Para añadir un solo lead opt-in y escribirle de inmediato, usa [`POST /campaigns/{id}/leads`](/api-reference/operations/addcampaignlead/).

## 5. Crea un webhook

[POST /webhooks](/api-reference/operations/createwebhook/) necesita `webhooks:manage`. El endpoint debe ser HTTPS.

**cURL**

```bash
curl -X POST https://app.whatsetter.com/api/v1/webhooks \
  -H "Authorization: Bearer $WHATSETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://tu-servidor.com/webhooks/whatsetter","events":["contact.qualified","contact.not_qualified"]}'
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://tu-servidor.com/webhooks/whatsetter',
    events: ['contact.qualified', 'contact.not_qualified'],
  }),
});
const { data } = await res.json();
console.log(data.secret); // whsec_… se muestra una sola vez, guárdalo ahora
```

**Python**

```python
import os, requests

r = requests.post(
    "https://app.whatsetter.com/api/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"},
    json={"url": "https://tu-servidor.com/webhooks/whatsetter",
          "events": ["contact.qualified", "contact.not_qualified"]},
)
print(r.json()["data"]["secret"])  # whsec_… se muestra una sola vez, guárdalo ahora
```

```json
{
  "data": {
    "id": "66f1c0ffee00000000000abc",
    "url": "https://tu-servidor.com/webhooks/whatsetter",
    "events": ["contact.qualified", "contact.not_qualified"],
    "active": true,
    "description": null,
    "secret_prefix": "whsec_3f9a",
    "secret": "whsec_3f9a…",
    "last_delivery_at": null,
    "last_delivery_status": null,
    "created_at": "2026-09-19T10:00:00.000Z"
  }
}
```

El `secret` solo aparece en esta respuesta. Guárdalo: lo necesitas para [verificar la firma](/es/developers/webhooks/) de cada entrega. Después envíate un evento de prueba firmado con [`POST /webhooks/{id}/test`](/api-reference/operations/testwebhook/).

## Siguientes pasos

- [Autenticación y permisos](/es/developers/authentication/): scopes, límites de peticiones, rotación de claves.
- [Errores, límites e idempotencia](/es/developers/errors/): cada `code`, y cómo reintentar sin riesgo.
- [Guías por recurso](/es/developers/): leads, campañas, mensajes, grupos, contactos bloqueados, enlaces.
- [Servidor MCP](/es/developers/mcp/): dale la misma clave a Claude, Cursor o ChatGPT.
- [Usar estos docs con asistentes IA](/es/developers/ai-assistants/): deja que un asistente construya la integración por ti.
