AI Mayak
Начать

Библиотека · Подключения: API, MCP и работа круглосуточно

API и интеграции

Строитель55 минОбновлено: октябрь 2026
22 из 105 в библиотеке

Модуль: 5 — Технические инструменты | Время: ~30 мин теории + 25 мин практики

Суть урока

API — это язык которым программы разговаривают друг с другом. Представь что каждый сервис (Stripe, Gmail, Telegram, CRM) — это страна со своим языком. API — это переводчик и дипломатический протокол одновременно. Claude Code знает этот язык и разговаривает с любым сервисом от твоего имени.

Ключевые концепции

  • API (Application Programming Interface) — стандартизированный способ программам общаться
  • REST API — самый распространённый тип: URL + метод запроса + данные в JSON
  • Claude Code создаёт инструменты которые делают API-вызовы
  • Интеграции = воркфлоу + инструменты для внешних сервисов

Теория

Что такое API — без жаргона

Когда ты заходишь в Telegram и видишь новые сообщения — приложение обращается к серверам Telegram через API: "дай мне сообщения для пользователя X". Сервер отвечает списком сообщений. Это и есть API в действии.

Аналогия официанта: ты сидишь за столиком (твоё приложение), официант (API) ходит на кухню (сервер) с твоими заказами и приносит обратно еду (данные). Ты не заходишь на кухню сам — не нужно знать как там всё устроено.

Почему это важно для тебя: большинство инструментов которые хочет автоматизировать бизнес — имеют API. Stripe принимает платежи через API. SendGrid отправляет письма через API. Notion хранит задачи в API. Если сервис имеет API — Claude Code может с ним работать.

REST API: как устроены запросы

🎨 Образ: REST API — это стандартная форма заявления. Везде одинаковая структура: кому, что прошу, мои данные, подпись. Неважно в каком банке или ведомстве — форма одинаковая. Научился заполнять одну — умеешь все.

Большинство современных API — REST API. Запрос состоит из:

1. URL (адрес)

Напиши в чат
https://api.stripe.com/v1/customers

Это адрес ресурса. Как адрес дома — ты знаешь куда обращаться.

2. Метод запроса

  • GET — получить данные ("дай мне список клиентов")
  • POST — создать новое ("создай нового клиента")
  • PUT / PATCH — обновить существующее ("измени email клиента")
  • DELETE — удалить ("удали клиента")

3. Данные в формате JSON

json
{
  "email": "[email protected]",
  "name": "Алексей Краснов",
  "plan": "premium"
}

JSON — это текст в фигурных скобках. Читаемый, структурированный. Как заполненный бланк.

4. Заголовки (Headers) Метаданные запроса: кто ты, какой формат ожидаешь, токен авторизации.

API ключи: как работает авторизация

🎨 Образ: API ключ — это пропуск на завод. Без него охранник не пускает. С чужим пропуском — заходишь как чужой сотрудник и можешь наделать дел от чужого имени. Поэтому пропуск не кладут на проходной.

Большинство API требуют "пропуск" — API ключ. Это длинная строка символов которая идентифицирует тебя как авторизованного пользователя.

Пример: ключ Stripe выглядит как sk_live_AbCdEfGh1234... (длинная строка символов).

Критически важное правило: API ключи — это как пароли. Никогда, ни при каких обстоятельствах не вставляй их прямо в код. Если ключ попадёт в GitHub — злоумышленники могут списать деньги с твоего Stripe счёта или разослать спам через твой SendGrid.

Правильный способ хранения:

Код
# Файл .env (локально)
STRIPE_SECRET_KEY=sk_live_AbCdEfGh1234...
SENDGRID_API_KEY=SG.xyz...
TELEGRAM_BOT_TOKEN=1234567890:AbCdEf...

Файл .env добавляется в .gitignore (не попадает в репозиторий). В коде используется process.env.STRIPE_SECRET_KEY — ссылка на переменную, не сам ключ.

Claude Code обычно следует этому правилу и не вставляет ключи в код, но перед коммитом всё равно просматривай изменения и проверяй, что ключей в них нет.

Тестирование API

Прежде чем встроить API в воркфлоу — проверяешь что он работает. Это называется "тестовый запрос".

Через curl (в терминале):

bash
curl -X GET "https://api.stripe.com/v1/customers?limit=3" \
  -H "Authorization: Bearer sk_test_..."

Через Postman / Insomnia: графические инструменты где можно отправлять запросы через интерфейс, без командной строки.

Через Claude Code: просто говоришь "отправь тестовый запрос к Stripe API и покажи что он возвращает" — агент сам пишет и выполняет запрос.

Обработка ошибок: реальность API интеграций

🎨 Образ: Коды ответов API — как светофор. 200 — зелёный, едешь. 401 — красный, нет пропуска. 429 — оранжевый, притормози, слишком быстро. 500 — авария на перекрёстке, не твоя вина, жди.

API не всегда отвечают успешно. Коды ответов:

Код Значение Что делать
200 Успех Всё хорошо, обрабатывай данные
201 Создано Ресурс создан успешно
400 Плохой запрос Проверь формат данных
401 Не авторизован Проверь API ключ
403 Запрещено Нет прав на эту операцию
404 Не найдено Неправильный URL или ID
429 Слишком много запросов Rate limit, жди
500 Ошибка сервера Проблема на стороне сервиса

Rate limiting — ограничение на количество запросов. Например, у Stripe есть общий лимит запросов в секунду в боевом режиме, а в песочнице он ниже (цифры меняются, актуальные — в документации сервиса). Если превышаешь — получаешь 429. Воркфлоу должен это учитывать: либо замедляться, либо повторять запрос через паузу (с нарастающим интервалом).

Агент знает типичные подходы к rate limits и добавляет обработку, но конкретные лимиты сверяй с документацией сервиса.

Реальные интеграции: примеры

Stripe (платежи)

Что умеет: принимать платежи картой, создавать подписки, управлять клиентами, отправлять инвойсы, делать возвраты.

Сценарий: воркфлоу автоматически выставляет инвойс клиенту когда проект завершён — агент создаёт инвойс в Stripe через API и отправляет ссылку на оплату.

python
# Агент пишет этот код за тебя
import stripe
stripe.api_key = os.environ["STRIPE_SECRET_KEY"]

invoice = stripe.Invoice.create(
    customer="cus_abc123",
    auto_advance=True,
)

Тестовый режим: Stripe даёт тестовые ключи (sk_test_...) и песочницу (sandbox) — можно тестировать платежи с тестовыми карточками без реальных денег.

Twilio (SMS и звонки)

Что умеет: отправлять SMS, делать звонки, WhatsApp Business API, верификация по номеру.

Сценарий: воркфлоу мониторит новые заявки. Когда приходит заявка от VIP клиента (сумма > $10,000) — агент отправляет SMS на телефон руководителя.

python
from twilio.rest import Client
client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])

message = client.messages.create(
    body="Новая VIP заявка: $15,000, свяжись сегодня",
    from_="+1415xxxxxxx",
    to="+7916xxxxxxx"
)

SendGrid (email)

Что умеет: отправка транзакционных писем (подтверждения, уведомления), маркетинговые рассылки, шаблоны писем, аналитика открытий.

Сценарий: после оплаты клиент автоматически получает письмо с инструкциями по доступу к курсу — агент отправляет его через SendGrid API.

Паттерн интеграции: воркфлоу + инструменты

🎨 Образ: Воркфлоу с инструментами — как операционный штаб. Командир (воркфлоу) отдаёт приказы: "свяжись с поставщиком", "отправь счёт", "уведоми склад". Каждый специалист (инструмент) знает свою задачу и своего контрагента. Командир не звонит сам — делегирует.

В архитектуре WAT (Workflow + Agent + Tools) интеграции с API живут в инструментах:

yaml
# workflows/invoice-on-completion.yaml
name: auto-invoice
description: Создаёт и отправляет инвойс когда проект помечен завершённым
steps:
  - action: get_project_details
  - action: create_stripe_invoice    # Stripe API
  - action: send_notification_email  # SendGrid API
  - action: send_sms_to_manager      # Twilio API
  - action: update_crm_status        # CRM API

Каждое action — это вызов отдельного инструмента. Инструмент знает как обратиться к конкретному API.

Как Claude Code помогает с API

🎨 Образ: Claude Code с API — как переводчик-дипломат. Ты говоришь "хочу договориться о поставке". Переводчик знает язык страны, протокол, как правильно обратиться. Переговоры идут на правильном языке, ты получаешь результат на своём.

Поиск документации: "найди как создать платёж через Stripe API для разовой покупки без сохранения карты" — агент находит нужный эндпоинт в документации.

Написание кода: агент пишет функцию-инструмент для конкретного API вызова, с обработкой ошибок и правильным использованием переменных окружения.

Отладка: если API возвращает ошибку — агент читает ответ, понимает причину, исправляет.

Обновление: если API изменился (новая версия) — агент находит что изменилось и обновляет код.

Практика

Задание: создай API endpoint и протестируй его

  1. Попроси Claude Code: "Создай простой API endpoint на Express.js который принимает POST запрос с полями name и email, валидирует что они не пустые, и возвращает JSON с подтверждением что данные получены"

  2. Агент создаст файл server.js. Запусти его: node server.js

  3. Протестируй через curl (агент поможет с командой):

bash
curl -X POST http://localhost:3000/subscribe \
  -H "Content-Type: application/json" \
  -d '{"name": "Алексей", "email": "[email protected]"}'

  1. Попробуй отправить запрос без email — посмотри как обрабатывается ошибка

  2. Дополнительно: попроси агента добавить интеграцию с реальным сервисом — например "при получении email — добавь его в список Mailchimp через API" (нужен Mailchimp API ключ)

Инструменты и ресурсы

  • Postman — графический клиент для тестирования API, бесплатно
  • Insomnia (insomnia.rest) — альтернатива Postman, более лёгкий
  • OpenAPI Specification — стандарт описания REST API (Swagger). Если сервис даёт OpenAPI spec — Claude Code может прочитать его и сгенерировать код автоматически
  • Stripe Dashboard — управление платежами, тестовые ключи
  • SendGrid (sendgrid.com) — есть бесплатный пробный период; условия и цены смотри на сайте
  • Twilio — бесплатный триальный номер при регистрации
  • httpbin.org — тестовый API для экспериментов (возвращает что ты ему отправил)
  • JSONPlaceholder (jsonplaceholder.typicode.com) — фейковый REST API для практики

Условия бесплатных планов меняются: актуальные цены и версии: Актуальное сейчас.

Ключевые выводы

API — это не сложно, это стандарт. Когда понимаешь что запрос = URL + метод + данные, ты понимаешь основу любого API.

Ключи в .env, никогда в коде — это не рекомендация, это правило без исключений. Одна утечка ключа может стоить тысячи долларов.

Claude Code превращает тебя из "человека который не умеет программировать" в "человека который может интегрировать любой сервис". Это принципиально меняет ценность которую ты можешь предложить клиентам.

Связанные уроки

Следующий урок

→ MCP: расширяем возможности Claude Code: как подключить внешние инструменты

Отметка хранится только в этом браузере и никуда не отправляется. Мой прогресс