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

Термины, которые чаще всего встречаются в ТЗ на интеграцию сайта с CRM, оплатой или складом. Без рекламы курсов — только смысл.

База

• 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 и окно обслуживания.