API, вебхуки и интеграции: словарь для заказчика

Интеграции. Запомните образ: сами спросили у сервиса (REST) или сервис сам прислал сигнал (webhook) при оплате или статусе заказа.

Собрал термины, которые всплывают в переписках про CRM, оплату и склад. Без курсов "стань Senior за вечер" - только то, что реально помогает читать ТЗ.

База

• HTTP - протокол запроса: метод (GET/POST/PUT/DELETE), URL, заголовки, тело.
• JSON - текстовый формат обмена данными { "key": "value" }.
• REST - стиль API на ресурсах и HTTP-методах; не единственный вариант, но самый распространённый.
• Endpoint - конкретный URL метода API, например /api/v1/orders.

Авторизация

• API key - секрет в заголовке; просто, но утечка = полный доступ.
• OAuth 2.0 - выдача токена с ограниченными правами и сроком жизни; стандарт для SaaS.
• JWT - подписанный токен с claims; удобен для stateless, следить за сроком и алгоритмом подписи.

События

• Webhook - ваш сервер принимает HTTP POST от внешней системы при событии (оплата прошла, заказ создан).
• Retry - повтор доставки вебхука при 5xx/таймауте; в ТЗ указать идемпотентность.
• Idempotency-Key - заголовок, чтобы повтор того же запроса не создал дубликат заказа/платежа.

Нагрузка и ошибки

• Rate limit - лимит запросов в минуту/час; превышение → 429.
• Pagination - cursor или offset/limit для больших списков.
• Коды 4xx/5xx - в ТЗ приложить таблицу: что делает фронт/бот при каждом коде.

Что попросить у вендора API

• OpenAPI/Swagger или Postman-коллекция.
• Песочница и тестовые ключи.
• SLA и окно обслуживания.

Пример REST-запроса

GET /api/v1/orders/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>

{ "id": 42, "status": "paid", "total": 15000 }

Пример webhook

POST /webhooks/payment HTTP/1.1
X-Signature: sha256=abc123...
{ "event": "payment.succeeded", "order_id": 42 }

Два способа связать ваш сайт с чужой системой

Первый — как вопрос в гости: ваш сайт сам спрашивает «что там по заказу?» по расписанию или когда пользователь нажал кнопку. Второй — как звонок в дверь: чужая система сама присылает вам сообщение, когда что‑то произошло, например оплата прошла. Для оплат чаще удобен второй способ, но его нужно надёжно «подписать», чтобы не подделали.

Когда говорят «вход через Google» и токены

Это про то, чтобы сайт мог делать что‑то от имени пользователя в другом сервисе. Для вас важно: где хранятся «ключи» доступа и как их обновляют — обычно это задача разработчика, но спросить имеет смысл.

Ограничения по частоте и повторные нажатия

У внешних сервисов бывают лимиты «не чаще столько‑то раз в минуту». Если сеть моргнула и запрос повторился, для оплат нужно, чтобы не создался второй платёж. Это снова к разработчику, но вы можете спросить: «а что если интернет моргнул?»

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

Рабочие привычки

• Один источник правды по задачам (Notion/Trello/ Issues), не десять чатов.
• Ежедневный демо или скрин прогресса заказчику — меньше сюрпризов.
• Жёсткий scope на неделю; новое — в следующий спринт.
• Автоматизируйте деплой и линтер — руками не тратьте внимание.

Типичные ошибки

Перегруз эффектами и библиотеками «на всякий случай»; отсутствие проверки на слабом интернете и старых телефонах; копирование чужого дизайна без адаптации под свою аудиторию; отсутствие явного CTA; ожидание, что «сайт сам продаст» без трафика и оффера.

Для коммерческих проектов отдельно болит размытое ТЗ и бесконечные правки без доплаты — лечится этапами и лимитом итераций.

Когда имеет смысл привлечь разработчика

Если нужен не шаблон, а связка дизайна, скорости, интеграций и сопровождения — проще обсудить задачу один раз, чем чинить конструктор полгода. Я беру лендинги, визитки и MVP под ключ; ориентиры по срокам и бюджету — на странице цен.

Читать дальше

• Мой стек 2026 — инструменты
• Обо мне — как работаю