Короткий ответ
API — набор правил, по которым одна программа просит у другой данные или действие без человека за экраном. Запрос уходит на адрес вместе с ключом, в ответ приходят данные и код состояния. Лимиты, платные тарифы и версии задаёт владелец сервиса, поэтому интеграции нужны хозяин ключей, журнал ошибок и человек, который следит за изменениями.
API — это окно обслуживания для программ, а не для людей
Подрядчик говорит: «сайт и CRM свяжем по API» — и владелец кивает, хотя картинки в голове нет. Так что такое API, если объяснять без программиста? Справочник MDN Web Docs определяет его как набор возможностей и правил внутри программы, которые позволяют взаимодействовать с ней через другую программу, а не через интерфейс для человека. Там же сказано, что API можно считать простым договором между приложением и теми программами, которые к нему обращаются.
Википедия заходит с другой стороны: пользовательский интерфейс соединяет компьютер с человеком, а API — программы между собой. Возьмите банк: вы видите в приложении экраны и кнопки, а ваша бухгалтерская программа — окно обслуживания с перечнем бланков. Она подаёт бланк условленного вида, получает условленный ответ и в служебные помещения не заходит. Википедия называет это одной из главных задач API: скрыть внутреннее устройство системы.
Из чего состоят запрос и ответ, если обойтись без кода
API, с которыми сталкивается небольшая компания, почти всегда работают через интернет: Telegram, например, описывает свой Bot API как интерфейс на основе HTTP. В обзоре HTTP на MDN обмен описан просто: клиент отправляет запросы, сервер возвращает ответы. Запрос состоит из метода — глагола вроде GET или POST, — пути к ресурсу, необязательных заголовков и иногда тела. На языке магазина это действие, адрес окна, пометка «кто спрашивает» и сам бланк.
В ответе приходит код состояния: по словам MDN, он показывает, выполнен ли запрос и если нет, то почему. MDN делит коды на пять классов: от 200 до 299 — успех, от 400 до 499 — ошибка клиента, от 500 до 599 — ошибка сервера. Владельцу важно одно: любой обмен оставляет след. Жалобу «интеграция не работает» можно превратить в точный вопрос — что отправили и какой код вернулся.
Что малый бизнес на деле связывает через API
Типовых связок немного. Форма на сайте передаёт заявку в CRM, и её не приходится перепечатывать из письма. Сайт просит платёжный сервис создать платёж и позже узнаёт, что деньги пришли. Магазин запрашивает у перевозчика стоимость доставки и трек-номер. Заказы уходят в 1С или другую учётную систему, а бот в мессенджере сообщает менеджеру о каждом новом.
Окно есть не у каждой программы, и не каждое открыто для вас. Википедия перечисляет три режима доступа: закрытый API — только для самой компании, партнёрский — для отдельных деловых партнёров, публичный — для всех. Поэтому сначала выясните, есть ли API у сервиса, за который вы уже платите, и входит ли он в ваш тариф. К тому же API отдаёт лишь то, что решил открыть его владелец: если действия нет в документации, вызвать его не сможет ни один подрядчик.
Ключ API — это пароль, а утёкший ключ — открытая дверь
Окну нужно знать, кто спрашивает, и для этого служит ключ. ЮKassa принимает идентификатор магазина как имя пользователя, а секретный ключ — как пароль. Руководство по ключам международного платёжного сервиса Stripe формулирует принцип прямо: секретный ключ API — это учётные данные, как логин и пароль. Тот, кто его получил, сказано там, может проводить списания, читать данные клиентов или нарушить работу интеграции. Stripe добавляет, что злоумышленники постоянно просматривают открытые хранилища кода в поисках ключей, и просит не пересылать их по почте и в чатах.
В списке OWASP API Security Top 10 за 2023 год нарушенная аутентификация стоит на втором месте, а передача токенов и паролей прямо в адресе запроса названа признаком уязвимого API. Ответ Stripe — ограниченный ключ с правами под одну задачу; его пример — сторонний сервис, который следит за спорами по платежам и получает к этим данным доступ только на чтение. Засвеченный ключ руководство велит заменить немедленно. Владельцу достаточно трёх привычек: ключи создаются в вашем аккаунте, подрядчик получает самый узкий, а вы знаете, как его отозвать.
Лимиты запросов, платные тарифы и версии задаёт другая сторона
API — чужое оборудование, и хозяин его бережёт. Stripe пишет, что ограничивает частоту запросов ради стабильности и защиты от злоупотреблений; сейчас в его документации указан общий лимит 100 запросов в секунду в рабочем режиме, а программа, которая его превысила, получает код 429 Too Many Requests. По лимитам же проходит граница между бесплатным и платным. В справке Telegram для ботов сейчас сказано, что массовая рассылка ограничена примерно 30 сообщениями в секунду, и описаны платные рассылки, которые поднимают потолок до 1000 с оплатой в звёздах Telegram.
Третье правило — версии. Википедия отмечает, что изменения в API могут нарушить совместимость с программами, которые на него опираются, а части публичного API могут объявить устаревшими. Stripe описывает свой ритм так: новые версии выходят каждый месяц без ломающих изменений, а дважды в год — крупный выпуск, где они есть, и переход может потребовать правок в готовой интеграции. Значит, кто-то должен читать уведомления сервиса, а поддержку закладывают в план с первого дня.
Вебхуки: когда чужая система сама стучится к вам
В обычной схеме ваша программа спрашивает, а сервис отвечает. Но часть событий происходит позже и без вас: банк подтверждает платёж через несколько минут после того, как покупатель закрыл страницу. Спрашивать каждую минуту, оплачено ли, — значит тратить запросы, поэтому сервисы дают обратный канал, вебхук. Вы сообщаете сервису адрес, и он сам присылает туда сообщение о событии. В документации Stripe сказано, что он в реальном времени отправляет данные на зарегистрированный адрес, когда, например, банк покупателя подтвердил платёж.
У вебхука свои правила. Stripe требует общедоступный адрес с HTTPS, и доставка не вечна: ЮKassa повторяет уведомление в течение 24 часов с момента события, Stripe в рабочем режиме — до трёх дней. Stripe предупреждает также, что одно событие может прийти больше одного раза, а без проверки подлинности злоумышленник способен прислать поддельное событие и, например, запустить отгрузку заказа. Если сайт пролежал длинные выходные, часть оплаченных заказов останется неоплаченной в вашей системе, пока человек не сверит их вручную.
О чём спросить подрядчика до начала интеграции
Начните с ключей. Спросите, кто их создаёт и в чьём аккаунте: аккаунт должен быть вашим, а не подрядчика. Спросите, где они будут храниться; руководство Stripe прямо запрещает класть секретные ключи в исходный код. Уточните, что разрешено каждому ключу и как его заменят по окончании работ. И спросите про тестовую среду: у Stripe, например, есть «песочница» со своими ключами, где платёжные системы не проводят настоящих платежей.
Затем спросите, что будет при сбое. Хороший пример есть в документации ЮKassa: если за 30 секунд точного ответа дать нельзя, сервис возвращает HTTP 500, и этот код не говорит, прошла операция или нет, — результат нужно сначала выяснить. Там же описан ключ идемпотентности: повторный запрос с ним обрабатывается как исходный, и это помогает избежать повторения транзакций. Поэтому спросите, защищён ли покупатель от двойного списания, где журнал и кому приходит сообщение об ошибке.
Готовый коннектор, сервис без кода или разработка: что подготовить
Путей три, и правильный — самый дешёвый из подходящих. Сначала загляните в настройки сервисов, которыми уже пользуетесь: у многих CRM, конструкторов сайтов и платёжных сервисов есть готовые связки друг с другом. Если готовой нет, сервисы автоматизации без кода соединяют два API наглядной цепочкой: новая заявка, карточка в CRM, сообщение менеджеру. Разработка оправданна, когда коннектора нет, когда логика у вас своя, когда объёмы подходят к лимитам или когда речь о деньгах и сбои нужно обрабатывать точно.
Какой бы путь вы ни выбрали, сначала подготовьте один лист. Опишите каждую связку одной фразой: когда здесь происходит это, там должно появиться то. Перечислите системы и тарифы, поля данных, которые передаются, примерное число событий в день и владельца каждого аккаунта. С таким листом студия вроде VITON13 Studio или ваш разработчик скажет, какой путь подходит, и оценит работу точно. А вопрос «что такое API» уступит место более полезному: какие две системы в вашем бизнесе должны заговорить друг с другом первыми.
Практический чеклист
- Выпишите сервисы, за которые уже платите, и проверьте в настройках каждого, входит ли API в ваш тариф.
- Запишите каждую связку одной фразой: когда в системе А происходит это, в системе Б должно появиться то.
- Создайте ключи API в своих аккаунтах и выдайте подрядчику ключ с самыми узкими правами под задачу.
- Договоритесь, где ведётся журнал ошибок, кому приходит сигнал о сбое и кто читает уведомления сервиса об изменениях.
- Проверьте интеграцию в тестовой среде сервиса на тестовых ключах до первого настоящего платежа и данных клиентов.
Вопросы и ответы
Нужен ли малому бизнесу программист, чтобы пользоваться API?
Не всегда. У многих сервисов есть готовые связки, которые включаются в настройках, а сервисы автоматизации без кода соединяют две системы наглядной цепочкой. Разработчик нужен, когда коннектора нет, когда логика особенная или когда через интеграцию идут платежи и сбои с дублями нельзя оставлять на самотёк.
Ключ API — это то же самое, что пароль от моего аккаунта?
По сути да. Руководство Stripe называет секретные ключи учётными данными, как логин и пароль: программа, предъявившая ключ, действует в вашем аккаунте в пределах его прав. Отличия вам на руку: ключу можно оставить несколько операций, а отозвать и заменить его удаётся без смены собственного пароля.
Что делать, если ключ API оказался в чате или в письме?
Считать его раскрытым и заменить. Stripe советует менять засвеченный ключ сразу, даже если неясно, видел ли его кто-то: выпускается новый, старый перестаёт работать, интеграцию переводят на новый. Потом просмотрите журнал запросов — нет ли там обращений, которых вы не делали, — и больше не пересылайте ключи в мессенджерах.
Чем вебхук отличается от обычного запроса к API?
Направлением. При обычном запросе ваша программа спрашивает сервис и ждёт ответа. С вебхуком вы один раз сообщаете адрес, и сервис сам присылает туда сообщение, когда что-то произошло, например подтвердился платёж. Это избавляет от постоянных опросов, но адрес должен быть доступен, а отправителя нужно проверять.
Может ли интеграция по API сама перестать работать после запуска?
Да, и обычно по одной из трёх причин: сервис выпустил версию с ломающими изменениями, ключ истёк или был отозван, поток запросов упёрся в лимит. На сайте этого не видно, пока заявки не перестанут доходить до CRM. Поэтому интеграции нужны журнал, оповещение и ответственный, который читает уведомления сервиса.