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

От тестового ключа до билета с QR за пять минут. Всё в тестовом режиме: настоящие продажи и гости этих запросов не увидят.

Ваш сайт продаёт билет и принимает оплату. После оплаты он отправляет заказ в API «буду». Мы выпускаем билеты с QR, присылаем гостю письмо со ссылкой на билет и проверяем QR на входе.

- Базовый адрес: `https://api.budu.events/v1`, только HTTPS.
- Запросы и ответы в JSON, кодировка UTF-8.
- Ключ передаётся в заголовке `Authorization: Bearer bt_test_…`.

## Получите тестовый ключ {#key}

Ключ создаёт владелец организации в кабинете, раздел **интеграция → ключи API**. Переключите кабинет в тестовый режим, и ключ получится тестовым, с префиксом `bt_test_`. Полный ключ показывают один раз: сразу сохраните его.

```bash
export BUDU_KEY=bt_test_…
```

Тестовый ключ видит только тестовые события. Письма по тестовым заказам уходят на адреса сотрудников организации и на адреса из **настройки → тестовые адресаты**. Добавьте туда свою почту, чтобы получить письмо с билетом. Подробнее в разделе [тестовый режим](https://budu.events/docs/test-mode/).

## Создайте событие {#event}

Событие появляется черновиком. Время передаётся в UTC по RFC 3339, часовой пояс нужен письму и странице билета. Цена `price_minor` указывается в копейках: `250000` — это 2 500 ₽.

```bash Запрос
curl https://api.budu.events/v1/events \
  -H "Authorization: Bearer $BUDU_KEY" \
  -H "Idempotency-Key: event-jazz-2026" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Джаз в саду",
    "starts_at": "2026-12-12T16:00:00Z",
    "ends_at": "2026-12-12T19:00:00Z",
    "timezone": "Europe/Moscow",
    "venue_name": "Площадка «Сад»",
    "venue_address": "Москва, Садовая улица, 1",
    "tariffs": [
      {"code": "dance", "name": "Танцпол", "price_minor": 250000, "quota": 300}
    ]
  }'
```

В ответе событие целиком. Дальше понадобятся `id` события и `id` тарифа:

```json Ответ 201
{
  "id": "0193e0b2-4a7c-7d10-9e3f-2c5a8b1d4e60",
  "title": "Джаз в саду",
  "status": "draft",
  "tariffs": [
    {
      "id": "0193e0b2-4a7d-7a21-8c44-6e2f9a0b3c71",
      "code": "dance",
      "name": "Танцпол",
      "price_minor": "250000",
      "currency": "RUB",
      "quota": 300
    }
  ]
}
```

## Опубликуйте событие {#publish}

Продажа открывается только у опубликованного события.

```bash Запрос
curl -X POST https://api.budu.events/v1/events/0193e0b2-4a7c-7d10-9e3f-2c5a8b1d4e60/publish \
  -H "Authorization: Bearer $BUDU_KEY"
```

Ответ `200` с событием в статусе `published`. Остатки доходят до продажи за несколько секунд. Заказ, отправленный раньше, получит `409 event_not_on_sale`: повторите его чуть позже или проверьте [остатки](https://budu.events/docs/events/#availability).

## Отправьте заказ {#order}

Этот запрос ваш сайт отправляет после оплаты. В `Idempotency-Key` положите номер заказа на вашей стороне. Если ответ потеряется, повтор с тем же ключом вернёт тот же заказ, и второй комплект билетов не выпустится.

```bash Запрос
curl https://api.budu.events/v1/orders \
  -H "Authorization: Bearer $BUDU_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "0193e0b2-4a7c-7d10-9e3f-2c5a8b1d4e60",
    "items": [{"tariff_id": "0193e0b2-4a7d-7a21-8c44-6e2f9a0b3c71", "qty": 2}],
    "buyer": {
      "email": "maria@example.ru",
      "first_name": "Мария",
      "last_name": "Соколова"
    },
    "payment_ref": "pay-77812"
  }'
```

```json Ответ 201
{
  "id": "0193e0c5-1f20-7c3e-b6a1-9d4e2f7a8b10",
  "org_id": "0193d9a1-2b3c-7d4e-8f50-61728394a5b6",
  "livemode": false,
  "event_id": "0193e0b2-4a7c-7d10-9e3f-2c5a8b1d4e60",
  "status": "issued",
  "buyer": {
    "email": "maria@example.ru",
    "first_name": "Мария",
    "last_name": "Соколова",
    "phone": ""
  },
  "items": [
    {"tariff_id": "0193e0b2-4a7d-7a21-8c44-6e2f9a0b3c71", "qty": 2, "seat": ""}
  ],
  "hold_expires_at": "2026-10-22T12:15:04Z",
  "payment_ref": "pay-77812",
  "tickets": [
    {
      "id": "0193e0c5-1f6b-7e02-a3c9-5b8d1e4f9f0a",
      "url": "https://budu.events/t/Vw3kqP7nX2bLmR9tYc4sHa",
      "tariff_id": "0193e0b2-4a7d-7a21-8c44-6e2f9a0b3c71",
      "holder_first_name": "Мария",
      "holder_last_name": "Соколова",
      "status": "valid",
      "seat": null
    },
    {
      "id": "0193e0c5-1f6b-7e02-a3c9-5b8d1e4fa21c",
      "url": "https://budu.events/t/9pLmZ2xQw8RkT4vNb6CyJe",
      "tariff_id": "0193e0b2-4a7d-7a21-8c44-6e2f9a0b3c71",
      "holder_first_name": "Мария",
      "holder_last_name": "Соколова",
      "status": "valid",
      "seat": null
    }
  ],
  "seats": [],
  "reason": "",
  "source": "api"
}
```

## Откройте билет {#ticket}

`tickets[].url` ведёт на страницу билета с QR. Ссылку можно показать покупателю у себя на сайте сразу после оплаты. На тестовом билете стоит плашка «ТЕСТ». Если ваш адрес среди тестовых адресатов, письмо с билетами придёт и на почту.

Иногда билеты не успевают выпуститься за пару секунд. Тогда ответ будет `202` и `{"status": "processing", "order_id": "…"}`. Билеты выпустятся сами, а письмо уйдёт как обычно. Ссылки появятся в [`GET /v1/orders/{id}`](https://budu.events/docs/orders/#get).

## Что дальше {#next}

- [Ключи и запросы](https://budu.events/docs/auth/): боевой ключ и форматы полей.
- [Идемпотентность](https://budu.events/docs/idempotency/): как безопасно повторять запросы.
- [Ошибки и лимиты](https://budu.events/docs/errors/): коды ошибок и что с ними делать.
- [Заказы](https://budu.events/docs/orders/): резерв на время оплаты, места, статусы.
- [Билеты](https://budu.events/docs/tickets/): поиск, отмена, перевыпуск и повторное письмо.