Если листание недоступно, весь гайд расположен ниже в обычном порядке. JavaScript для чтения необязателен.

БАЗА / ПО НУЖДЕ GUIDE 07 / 19 · МАРШРУТ НОВИЧКА

Как проходить этот гайд, если ты вообще не программист

Читать сейчас?Да. API - базовое понятие для AI-проектов, даже если сегодня у тебя только одна интеграция.
Внедрять сейчас?Сделай практику, если проект общается с Telegram, AI-моделью, оплатой, CRM, Google или другим сервисом.
Зачем это знать?API - это договор между системами. Понимая его, ты перестаёшь лечить интеграции наугад.

Что сделать по шагам

  1. Выбери одну реальную интеграцию.
  2. Зафиксируй request, response и основные ошибки.
  3. Сделай один реальный успешный запрос и один контролируемый ошибочный сценарий.
Урок закрыт, когда: Есть API_CONTRACT.md / INTEGRATIONS.md и реальный проверенный request → response.
Простой пример: Бот отправляет текст в AI API. Успех возвращает ответ, неверный ключ даёт 401, превышение лимита может дать 429.

Важно: обязательную основу проходим по порядку, остальные модули — по типу проекта. Но чтение урока не означает, что ты обязан внедрить описанную технологию в свой проект. Сложность добавляем только когда появилась реальная причина.

БАЗОВЫЙ ЗАКОН ИНТЕГРАЦИЙ

Сначала контракт, потом код

До подключения сервиса договорись, что именно одна часть системы передаёт другой. Это и есть contract-first.

INPUT { "user_id": "string", "message": "string", "created_at": "ISO datetime" } OUTPUT { "status": "ok | error", "result": "...", "request_id": "..." }

До реализации зафиксируй: input, output, обязательные поля, validation, ошибки, timeout, idempotency и версию контракта. Артефакт: API_CONTRACT.md.

Гайд №07 • Хардкодинг PRO

API и интеграции для новичков

Как научить свой проект общаться с Telegram, AI-моделями, базами данных, CRM, платежами, Google и другими сервисами. Простым русским языком, с примерами и готовыми промптами.

API простыми словами Ключи и .env Уведомление от сервиса (Webhook) Ошибки 400-500 ИИ делает техническую часть
Гайд №8 API и интеграции для новичков

1. API, MCP, SSH и туннели простыми словами

API (программный интерфейс) - это договорённый способ, по которому одна программа обращается к другой.

Представь ресторан. Ты не идёшь на кухню и не готовишь блюдо сам. Ты говоришь официанту, что хочешь получить. Официант передаёт заказ кухне, а потом приносит результат. API работает похожим образом.

Твой проект→API→Внешний сервис→Ответ
Главное: тебе не надо знать внутреннее устройство чужого сервиса. Нужно понимать, что попросить и какой результат ждать.

API, MCP и SSH — это три разные задачи

На уроке мы разобрали три способа «подключить ИИ к чему-то». Они связаны между собой, но решают разные задачи. Если запомнишь разницу ниже, дальше станет сильно проще.

API — разъём между программами

API — это интерфейс и правила, по которым одна программа вызывает другую. Обычно у тебя есть URL / endpoint — адрес, куда обращаться, и API-ключ или token — credential, который подтверждает право доступа.

Когда нужен: отправить сообщение в Telegram, получить данные Wildberries, вызвать ИИ-модель, создать платёж, записать данные в CRM.

MCP — инструменты сервиса специально для AI-агента

MCP (Model Context Protocol) — стандарт, через который AI-клиент может увидеть доступные инструменты, ресурсы и их описания, а затем вызывать их в понятном формате.

По-простому: API даёт программе «разъём», а MCP добавляет агенту понятную карту того, какими инструментами он может пользоваться и какие параметры им передавать. Под капотом MCP нередко сам обращается к обычным API.

Важно: MCP не заменяет API и не означает, что у каждого сервиса обязательно есть готовый MCP-сервер.

SSH — защищённый удалённый доступ к машине

SSH нужен, когда задача не «вызвать функцию сервиса», а зайти на свой VPS / сервер / компьютер и управлять им удалённо: установить приложение, посмотреть логи, обновить код, перезапустить сервис.

Обычно для подключения нужны host, пользователь, порт и способ аутентификации. Для постоянной работы безопаснее использовать SSH-ключи и выдавать только тот доступ, который реально нужен.

SSH-туннель — защищённый маршрут внутри SSH

SSH tunnel / port forwarding — это способ провести сетевой трафик через зашифрованное SSH-соединение. Например, дать удалённой машине доступ к локальному сервису или безопасно достучаться до порта на сервере без публикации этого порта для всего интернета.

Не путай: SSH — протокол удалённого доступа, а туннель — один из способов использовать это SSH-соединение.

Шпаргалка в одну строку:
проект ↔ внешний сервис → API
AI-агент ↔ набор инструментов → MCP
ты или AI-агент ↔ твой VPS/компьютер → SSH
нужно безопасно прокинуть конкретный сетевой порт → SSH-туннель
Секреты не являются частью инструкции. API-ключи, токены и приватные SSH-ключи не хранят в Git и не вставляют в публичные документы. Для API используй .env или secret storage. Для SSH обычно передаётся публичный ключ, а приватный остаётся на доверенной машине.
Что такое API простыми словами
Документация API, HTTP, MCP, SSH · данные проверены 10.10.2026

Коды HTTP: 401 — требуются действительные учётные данные, 403 — нет разрешения, 429 — превышен лимит запросов, 500 — ошибка сервера. Повторять запросы следует с учётом Retry-After, идемпотентности и правил конкретного API. SSH-ключи: приватный ключ остаётся на доверенной машине; публичный передаётся серверу/сервису. MCP — отдельный протокол доступа AI-клиента к инструментам и ресурсам; проверяй источник сервера и предоставляемые разрешения.

Официальная справка HTTP (MDN) · SSH (GitHub Docs) · MCP specification

Информация и интерфейсы могли измениться. Перед подключением сервиса сверь требования с официальной документацией конкретного API.

2. Как работает запрос

Почти любая интеграция состоит из трёх действий:

1. Запрос

Твой проект отправляет данные или просит выполнить действие.

2. Обработка

Внешний сервис принимает запрос и делает работу.

3. Ответ

Сервис возвращает результат или ошибку.

Небольшой пример

Ты создаёшь AI-бота. Пользователь спрашивает: «Напиши пост про мой продукт». Бот отправляет текст в ИИ-сервис. AI генерирует ответ. Бот возвращает его пользователю.

Не надо учить запросы наизусть. ИИ может сам прочитать документацию и сформировать правильный запрос. Твоя задача - понимать логику.
Запрос обработка ответ

3. Что можно подключить к проекту

Через API проект может использовать возможности десятков внешних сервисов. Важно не подключать всё подряд, а выбирать то, что решает конкретную задачу.

Telegram

Сообщения, боты, уведомления, команды, мини-приложения.

ИИ-модели

Генерация текста, анализ, классификация, поиск, изображения, аудио.

Google

Таблицы, документы, диск, календарь, почта и другие сервисы.

CRM

Создание лидов, обновление сделок, задачи менеджерам, данные клиентов.

Платежи

Создание оплаты, проверка статуса, подписки, выдача доступа после оплаты.

Базы данных

Пользователи, заявки, история действий, настройки, результаты и аналитика.

Хороший вопрос перед интеграцией: «Что изменится для пользователя или бизнеса после подключения этого сервиса?» Если ответа нет, интеграция, скорее всего, пока не нужна.
Что можно подключить

Бизнес-практика: API Wildberries / Ozon без риска

Цель: научиться проектировать интеграцию по документации, проверить данные на тестовом примере и только после этого обсуждать реальные подключения. Никаких реальных ключей для учебного этапа.

Документация → контракт данных → тестовая JSON-заглушка → аналитика → сверка

Шаг 1. Исследуй конкретный API

Открой официальную документацию WB API и Ozon Seller API. Выбери один разрешённый метод чтения. Зафиксируй endpoint, параметры, права, формат ответа, ошибки 401/429 и лимиты. Не придумывай единую схему для двух площадок.

Шаг 2. Протестируй без ключа

Промпт ученика

Спроектируй только read-only интеграцию с API маркетплейса. Сначала изучи актуальный официальный метод, его параметры и ограничения. Создай локальный JSON-fixture с вымышленными SKU и продажами; проверь обработку 200/401/429, пустого ответа, повтора запроса и пропущенных полей. Не подключай живой кабинет, не запрашивай мой токен в чат, не логируй секреты и не выполняй операции записи. Покажи контракт входа/выхода и критерии приёмки.

Шаг 3. Прими работу

  • ✅ Тестовый ответ парсится, данные приводятся к таблице, есть исходный JSON и источник формул.
  • ✅ Ошибка 401 не провоцирует повторное раскрытие ключа; 429 обрабатывается с учётом опубликованных лимитов.
  • ✅ Ключ не находится в исходниках, отчёте, логах, запросах ученика и Git. Используй защищённое хранение секретов и минимальные права.
  • ✅ При отсутствии данных система сообщает об ошибке, не придумывает продажи или прибыль.
  • ✅ Реальное чтение — отдельный следующий этап только с разрешением владельца; операции записи исключены.

Данные проверены: 16.10.2026. Документация и лимиты могут измениться. Этот пример не подключён к личному кабинету и не получает настоящие данные WB/Ozon.

4. Слова, которые встретятся в документации

Не пугайся терминов. Ниже перевожу их на человеческий язык.

Адрес запроса (endpoint)
Конкретный интернет-адрес, куда программа отправляет запрос.
Метод запроса
Что мы хотим сделать. GET обычно получает данные, POST создаёт или запускает действие, PATCH изменяет, DELETE удаляет.
Заголовки (headers)
Служебная информация. Например, ключ доступа или формат данных.
Тело запроса (body)
Данные, которые мы передаём сервису.
JSON
Популярный текстовый формат, которым программы передают структурированные данные.
Ответ (response)
То, что сервис вернул после обработки запроса.
Лимит запросов (rate limit)
Ограничение, сколько обращений можно сделать за определённое время.
Время ожидания (timeout)
Сколько наш проект готов ждать ответ внешнего сервиса.
Пример логики, а не обязательного кода: POST /create Данные: {{ "topic": "AI для бизнеса" }} Ответ: {{ "status": "ok", "result": "Готовый текст..." }}

5. API-ключи и файл .env

API-ключ - это секретный ключ доступа к сервису. Относись к нему как к паролю.

Неправильно

Вставлять реальный ключ прямо в код, отправлять его в GitHub, показывать на скриншоте или хранить в открытом чате.

Правильно

Хранить секреты в переменных окружения. На локальном компьютере часто используется файл .env. Для сервера - защищённые переменные окружения или менеджер секретов.

.env.example - пример того, какие переменные нужны проекту. Настоящие значения ключей туда не помещаются.
Если ключ случайно попал в публичный репозиторий: недостаточно просто удалить строку. Обычно ключ нужно отозвать в сервисе и создать новый.
API ключи и env

6. Уведомление от сервиса (webhook) простыми словами

Уведомление от сервиса (Webhook) - это способ, когда внешний сервис сам сообщает твоему проекту, что произошло событие.

Обычный запрос

Твой проект сам спрашивает сервис: «Есть новая информация?»

Уведомление от сервиса (Webhook)

Сервис сам отправляет сообщение твоему проекту: «Событие произошло, вот данные».

Пример с оплатой

Пользователь оплатил продукт. Платёжный сервис отправляет webhook на специальный URL проекта. Проект получает событие, проверяет его и открывает доступ пользователю.

Плюс webhook: не надо каждую секунду спрашивать сервис, не произошло ли что-то новое. Событие приходит само.
Уведомление от сервиса (Webhook) простыми словами

7. Реальный пример: Telegram-бот + ИИ + база данных

Возьмём простую связку, которую новичок реально может собрать.

1. ПользовательПишет сообщение в Telegram.
2. Telegram-ботПолучает сообщение и передаёт его backend проекта.
3. ИИ-сервисПолучает запрос, анализирует его и формирует ответ.
4. База данныхПри необходимости сохраняет пользователя, историю, результат или настройки.
5. ОтветПроект отправляет результат обратно пользователю в Telegram.
Telegram→Backend→AI→База→Ответ

Дальше можно подключить CRM, Google Таблицы, оплату, календарь или другие сервисы. Но начинай с одной полезной связи.

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

8. Ошибки API и что означают коды

Ошибка не означает, что «всё сломалось». Код ответа часто сразу показывает класс проблемы.

200 / 201Обычно запрос выполнен успешно.
400Неверный запрос. Например, не хватает обязательного поля или данные имеют неправильный формат.
401Проблема с авторизацией. Часто неправильный или отсутствующий ключ.
403Сервис понял, кто мы, но у нас нет права выполнить действие.
404Адрес запроса или нужный объект не найден.
429Слишком много запросов или достигнут лимит.
500+Проблема на стороне сервиса или сервера.
Правильная работа с ошибкой: передай ИИ код ответа, текст ошибки, фактический запрос и ссылку на документацию. Попроси сначала диагностировать, а не переписывать всё подряд.
Ошибки API

9. Что должен делать ИИ, а не ученик

Тебе не нужно держать в голове документацию OpenAI, Telegram, Google, CRM и каждого нового API.

Твоя задача

  • объяснить бизнес-задачу;
  • выбрать нужный сервис;
  • дать доступы;
  • подтвердить важные решения;
  • проверить пользовательский результат.

Задача ИИ

  • читать официальную документацию;
  • подбирать адреса и методы запросов;
  • собирать интеграцию;
  • хранить ключи безопасно;
  • писать тесты и тестовые запросы;
  • диагностировать ошибки;
  • вести INTEGRATIONS.md;
  • объяснять тебе, что произошло.
подход через ИИ: не «научи меня писать curl вручную», а «изучи документацию, подключи сервис, протестируй и объясни мне результат».
Следующий шаг с API

10. Готовые промпты для ИИ

Эти промпты можно использовать как шаблоны. Замени поля в квадратных скобках на свой проект.

Промпт №1. Изучи API до написания кода

Промпт №2. Собери карту интеграций

Промпт №3. Реализуй одну интеграцию

Промпт №4. Настрой уведомление от сервиса (webhook)

Промпт №5. Диагностируй ошибку

Промпт №6. Работай как мой AI-интегратор

Промпт №7. Подключись к моему VPS по SSH

Промпт №8. Найди и подключи MCP

11. Чек-лист: интеграция действительно готова?

Отмечай пункты. Прогресс сохраняется на устройстве.

0 / 20 выполнено
20-23 пунктов: интеграция выглядит зрелой и проверенной.
15-19 пунктов: уже хорошо, но есть технические пробелы.
0-14 пунктов: не спеши считать интеграцию готовой.

12. Практическое задание

Главная цель урока - не выучить термины, а один раз руками пройти цепочку подключения вместе с ИИ.

Шаг 1

Выбери одну реальную задачу: подключить внешний сервис или получить доступ к своему VPS.

Шаг 2

Определи вместе с ИИ, что здесь нужно: API, готовый MCP, SSH или SSH-туннель. Попроси ИИ объяснить выбор одним абзацем.

Шаг 3

Попроси ИИ изучить официальную документацию сервиса или VPS-провайдера до любых изменений.

Шаг 4

Передай доступ безопасно: API-секрет — в .env / secret storage; для SSH предпочитай ключевую аутентификацию и не публикуй приватный ключ.

Шаг 5

Сделай безопасный smoke-test. Для API/MCP — один реальный запрос/tool call. Для SSH — сначала только hostname, whoami и pwd.

Шаг 6

Если нужен SSH-туннель, сначала попроси ИИ назвать конкретный порт, направление туннеля и зачем он нужен. Не открывай лишние порты.

Шаг 7

Попроси ИИ встроить подключение в проект и обновить INTEGRATIONS.md: что подключено, где лежит конфигурация и как проверить.

Шаг 8

Проверь отказоустойчивость: неправильный параметр, отозванный token, недоступный сервис или отсутствие SSH-доступа. Ошибка должна быть понятной и безопасной.

Навык освоен, если: ты видишь новую задачу и можешь выбрать правильный уровень подключения: API для программной интеграции, MCP для инструментов AI-агента, SSH для управления своей машиной и SSH-туннель для безопасного проксирования нужного сетевого порта.
Альтернативная короткая практика: только API (оригинал training)

12. Практическое задание

Главная цель урока - не прочитать гайд, а сделать одну реальную интеграцию.

Шаг 1

Выбери один внешний сервис, который реально нужен твоему проекту.

Шаг 2

Дай ИИ промпт №1 и попроси изучить официальную документацию.

Шаг 3

Получи ключ доступа и сохрани его безопасно.

Шаг 4

Сделай один тестовый запрос и получи реальный ответ.

Шаг 5

Попроси ИИ встроить интеграцию в проект и обновить INTEGRATIONS.md.

Шаг 6

Проверь негативный сценарий: например, неправильный параметр или отключённый сервис.

Навык освоен, если: ты можешь взять незнакомый сервис, объяснить ИИ задачу, дать ему документацию, получить рабочую интеграцию и сам проверить, что пользовательский сценарий действительно работает.
КОНТРАКТ API ДЛЯ НОВИЧКА

Не просто «API работает». Договорись, какие данные оно принимает и возвращает

API-контракт - это обычная договорённость между двумя частями проекта. Например: «я отправляю email как текст, а ты возвращаешь user_id как число».

Почему это важно: если одна часть ждёт email, а другая внезапно начнёт присылать user_email, проект может сломаться даже если обе части по отдельности «работают».

Три вещи, которые нужно зафиксировать

  1. Какие поля обязательны. Например: email, name.
  2. Какого они типа. Текст, число, список, true/false.
  3. Что приходит в ответ. Успех, ошибка и понятные поля ответа.

Schema validation означает простую вещь: система автоматически проверяет, что данные соответствуют этой договорённости. Если нет - возвращает понятную ошибку, а не пытается «догадаться».

Breaking change - изменение, после которого старый клиент перестаёт работать. Например, мы удалили поле, которое он использовал. Если такое изменение действительно нужно, безопаснее создать новую версию API, например v2, а старую v1 не ломать мгновенно.

API CONTRACT PROMPT

Проверить контракт без переписывания проекта

Если автокопирование заблокировано, текст можно выделить вручную.
🧠 WIKI ЭТОГО ГАЙДА

Непонятные слова простыми словами

Не зубри определения. Вернись сюда, если встретил термин и забыл, что он означает.

EndpointКонкретный адрес одной функции API.
RequestЗапрос, который одна система отправляет другой.
ResponseОтвет системы на запрос.
PayloadДанные внутри запроса или ответа.
WebhookКогда внешний сервис сам сообщает твоему проекту, что событие произошло.
Rate limitОграничение на количество запросов за определённое время.
IdempotencyЗащита от дублей: повтор одного и того же запроса не должен дважды списать деньги или создать две записи.
Хардкодинг PRO • Гайд №09 • API и интеграции для новичков
Перед следующим гайдом — практика: закрепи тему на реальной задаче «Собери Telegram-бота». После практики маршрут сам приведёт тебя к гайду 10.
Перед переходом дальше: Переходи дальше после общей части. Практику внедряй только если интеграция реально нужна твоему проекту. Кнопка «Дальше» означает следующий учебный урок, а не обязанность внедрить каждую технологию.
Перейти к чек-листу