# Быстрый старт

Пять шагов от ключа до ленты событий. Понадобится терминал с curl, Node.js 18+ или Python 3.

Промпт для ИИ-агента: https://docs.melioralab.io/agent-prompt.txt

### Получите ключ

В раннем доступе ключ выпускаем мы: напишите в [поддержку](https://docs.melioralab.io/support/), какие права и какой охват нужны. Для первого знакомства хватит прав «Кампании», «Лиды» и «События».

Если в вашем кабинете открыт раздел **Настройки › Интеграции › API**, ключ может создать владелец или администратор кнопкой «Создать ключ».

Ключ показывается один раз. Сохраните его сразу: восстановить его нельзя, только перевыпустить.

### Сохраните ключ в окружении

Не вставляйте ключ в код и не передавайте его в адресе запроса. Положите его в переменную окружения:

```bash
export MELIORA_API_KEY="mel_live_..."
```

### Проверьте доступ

Запрос `GET /v1/me` возвращает организацию, права и лимиты ключа. Он доступен с любым набором прав.

```bash
curl https://api.melioralab.io/v1/me \
  -H "Authorization: Bearer $MELIORA_API_KEY"
```
```js
const res = await fetch('https://api.melioralab.io/v1/me', {
  headers: { Authorization: `Bearer ${process.env.MELIORA_API_KEY}` },
});
console.log(res.status, await res.json());
```
```python
import os
import requests

resp = requests.get(
    "https://api.melioralab.io/v1/me",
    headers={"Authorization": f"Bearer {os.environ['MELIORA_API_KEY']}"},
    timeout=15,
)
print(resp.status_code, resp.json())
```

В ответе проверьте `scopes` и `scope`: это права и охват ключа. Если пришла ошибка, ее код и что делать описаны в руководстве [Ошибки](https://docs.melioralab.io/errors/). Чаще всего это `invalid_api_key`: ключ скопирован не полностью или с лишним пробелом.

### Получите кампании и лидов

Список кампаний возвращается страницами, от старых к новым:

```bash
curl -G https://api.melioralab.io/v1/campaigns \
  -H "Authorization: Bearer $MELIORA_API_KEY" \
  -d status=active
```

Возьмите `id` нужной кампании и запросите ее лидов:

```bash
curl -G https://api.melioralab.io/v1/leads \
  -H "Authorization: Bearer $MELIORA_API_KEY" \
  -d campaign_id=4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14 \
  -d limit=100
```

Если в ответе `has_more: true`, передайте значение `next_cursor` в параметре `cursor` следующего запроса. Подробнее в руководстве [Пагинация](https://docs.melioralab.io/pagination/).

### Подпишитесь на события

Чтобы узнавать о новых сообщениях и ответах без обхода всех лидов, читайте ленту событий. Первый запрос с `start=now` возвращает пустую страницу и курсор, с которого начнется лента:

```bash
curl -G https://api.melioralab.io/v1/events \
  -H "Authorization: Bearer $MELIORA_API_KEY" \
  -d start=now
```

Сохраните `next_cursor` и раз в минуту запрашивайте `GET /v1/events?cursor=...`. Каждый ответ содержит новый курсор, даже если событий нет: сохраняйте его всегда.

## Что дальше

- [Опрос событий](https://docs.melioralab.io/events-polling/): цикл, который не теряет и не дублирует события, с примерами на Node.js и Python.
- [Связь с CRM](https://docs.melioralab.io/crm-mapping/): как сопоставить лида с записью CRM через `record_id`.
- [Лимиты и повторы](https://docs.melioralab.io/rate-limits/): как обрабатывать 429 и 503.