API простыми словами: что это и почему ваши системы не дружат сами по себе

Слово «API» звучит на каждой встрече с разработчиками. «Нужна интеграция через API», «у них закрытый API», «API упал — данные не синхронизируются». Большинство руководителей в этот момент кивают и идут дальше. В принципе, так и можно — но тогда вы принимаете решения о проекте, не понимая базовых вещей.

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

Это очень заезженный пример - но он реально хорошо показывает, как работает API. Даже на некоторых вводных курсах по IT API объясняют именно через этот пример.

Вы сидите за столиком в ресторане. На кухне есть повара, продукты, оборудование. Но вы не идёте на кухню сами. Между вами и кухней — официант.

Вы говорите официанту: «Пожалуйста, котлетки с макарошками... нет, с пюрешкой! И воду». Официант идёт на кухню, передаёт заказ в нужном формате, кухня готовит, официант приносит результат. Вам не нужно знать, как работает кухня, а кухне не нужно знать, кто вы. Официант — это стандартный, понятный обеим сторонам "интерфейс".

API — это официант. Только между программными системами. Это технология, когда одна система (не важно какая - клиент ресторана) в заранее установленном виде (параметры запроса - бланк с блюдами, заполняемый официантом) передает "инструкции" (запрос - это и есть официант) на кухню (это вторая система, тоже не важно какая и как работает). А кухня отдает тоже через официанта готовое блюдо (ответ на запрос).

Главное - чтобы вы с официантом общались на одном языке, и у вас было меню. Иначе то, что вы закажете (отправите) вам просто не принесут.

А вот как это работает на реальном примере.
Ваша CRM хочет получить список заказов из 1С. Она не лезет напрямую в базу данных 1С — это было бы как войти на кухню и самому достать кастрюлю. Она отправляет запрос через API: «дай мне товары за последние 24 часа». 1С обрабатывает запрос и возвращает данные в понятном формате. CRM забирает, сохраняет у себя.

Это главное заблуждение, которое приводит к неприятным сюрпризам в проектах.

Когда компания покупает CRM и отдельно использует 1С — они не начинают автоматически обмениваться данными. Это два отдельных продукта, написанных разными командами, в разное время, для разных задач. У них разная внутренняя структура, разный язык, разные форматы хранения данных.

1С называет поле «КодКонтрагента». CRM называет то же самое «client_id». Это не просто разные названия — это разные логики, разные типы данных, разные правила валидации.

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

Именно поэтому «готовая интеграция с CRM» не всегда значит «всё заработает сразу». Готовая интеграция — это шаблонный мост под стандартные случаи. Как только у вас нестандартный процесс — начинаются костыли или кастомная разработка.

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

REST API — это самый распространённый тип. Обычно его и имеют в виду, когда говорят "прокинуть апишку". Работает по принципу запрос-ответ. Ваша система спрашивает, другая система отвечает. Это как отправить письмо и получить ответ. Инициатива всегда на стороне того, кто спрашивает.

Например: каждые 15 минут CRM спрашивает у склада «есть ли новые отгрузки?». Склад отвечает - CRM обновляет данные.

Webhook — обратный принцип. Система не ждёт, когда её спросят — она сама отправляет данные в момент события. Можно сказать, что это "обмен по триггеру со стороны отвечающей системы".

Например: как только заказ в 1С перешёл в статус «отгружен», 1С сама отправляет данные в CRM, без запроса со стороны CRM.

Почему это важно для вас: если данные должны синхронизироваться в реальном времени — нужны вебхуки или очереди событий. Если небольшая задержка допустима — REST достаточно. Это влияет на архитектуру и на стоимость.

Сделать интеграцию один раз и забыть - можно. Но у неё есть свои точки отказа.

1. API меняется. Поставщик системы выпускает обновление и меняет формат данных. Ваша интеграция, которая работала год, перестаёт работать на следующее утро после их обновления. Без предупреждения. Если, конечно, обе системы не являются вашей собственной разработкой - тогда разработчики сами вместе с обновлением поменяют и API.

2. Токены "протухают". Большинство API используют ключи доступа, которые нужно периодически обновлять. Если ключ истёк — данные перестали идти. Опять таки, если разработчики не занимаются поддержкой ваших систем.

3. Лимиты запросов. Многие API ограничивают количество запросов в минуту или в сутки. Если ваша система делает их слишком часто — начнут приходить ошибки.
и снова ситуация касается тех случаев, когда одна из сторон - не ваша, а чужая программа или сервис

4. Данные расходятся. Интеграция работает, но логика маппинга не учла какой-то частный случай. В 1С — одно значение, в CRM — другое. Никто не замечает, пока это не всплывает в отчёте.

Сложные интеграции требуют периодического мониторинга и поддержки. Хорошо сделанная интеграция включает логирование ошибок, оповещения при сбоях и понятную точку для диагностики.

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

Есть ли у системы API? Не все системы его предоставляют. Некоторые старые продукты, самописные решения или системы с жёсткой лицензионной политикой — закрытые. Интеграция с ними возможна только через экспорт файлов, что медленно и ненадёжно.

Что через него можно делать? API бывает частичным. Читать данные — можно, писать — нет. Или доступны только некоторые сущности. Это нужно выяснять до начала разработки, а не в процессе.

Есть ли документация? Хорошая API-документация — признак зрелого продукта. Если документация отсутствует или устарела — интеграция займёт в разы больше времени: разработчик будет разбираться методом проб и ошибок.

всегда)
Интеграция оправдана, если данные между системами передаются часто, ошибки при ручном переносе критичны, или ручная синхронизация отнимает значительное время сотрудников.

Если данные нужны раз в месяц и их немного — иногда проще и дешевле выгрузить Excel и загрузить вручную (бывает и такое).

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

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

В следующий раз, когда разработчик скажет «там нет нормального API» — вы будете понимать, почему это проблема и что это означает для сроков.