← Что делаем

API-интеграции: подключение внешних сервисов и разработка своего API

API — это способ для одной программы попросить что-то у другой. Подключение к платежной системе, к службе доставки, к маркетплейсу, к сервису проверки контрагентов, к телефонии — все это работа с чужими API. И наоборот: когда партнеры или ваши же приложения должны обращаться к вашей системе, нужен свой.

Технически это несложная работа. Сложной ее делает то, что происходит, когда та сторона отвечает медленно, ошибкой или не отвечает вовсе.

Три разные задачи

Подключиться к чужому API

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

Сделать свой API

Чтобы к вашей системе могли обращаться партнеры, мобильное приложение или другие ваши системы. Здесь важны продуманность, версионность и то, что менять его потом будет больно.

Принимать уведомления

Внешний сервис сам сообщает о событии: платеж прошел, посылка доставлена, статус изменился. Экономнее опроса, но требует надежного приема: потерянное сообщение никто не повторит.

Что происходит, когда та сторона подводит

Внешний сервис однажды не ответит — это не гипотеза, а расписание. Разница между надежной интеграцией и хрупкой целиком в том, что происходит в этот момент.

Что учитываем при подключении к чужому API

Повторы с нарастающей задержкой. Не долбить сервис каждую секунду, а повторять через увеличивающиеся промежутки. Иначе при сбое на той стороне вы добавляете нагрузку и получаете блокировку.
Защита от двойного выполнения. Если ответ потерялся, повтор не должен создать второй платеж или вторую отгрузку. Каждой операции присваивается признак, по которому та сторона узнает повтор.
Ограничения на частоту. У большинства сервисов есть лимит обращений. Его надо знать заранее и укладываться в него, иначе интеграция встанет ровно в момент пиковой нагрузки.
Журнал запросов и ответов. Что отправили, что получили, когда. Без этого спор с поставщиком услуги о том, чья ошибка, решить невозможно.
Тестовый контур. У нормальных сервисов он есть, и проверять надо в нем, а не на живых платежах.
Версии и изменения. API меняются. Нужны мониторинг и уведомления, чтобы узнать о поломке в день ее появления.
Хранение ключей. Ключи доступа не должны лежать в коде и в репозитории. Это базовая гигиена, которую нарушают чаще, чем хотелось бы.

Если делаем свой API

Здесь другой набор вопросов, и цена ошибки выше: чужой API вы можете сменить, свой придется поддерживать годами.

Понять, кто будет им пользоваться. Партнеры, ваше мобильное приложение, интеграторы клиентов. От этого зависит все: от способа авторизации до подробности документации.
Спроектировать от задач, а не от таблиц. API, повторяющий структуру базы, удобен разработчику и мучителен для того, кто подключается. Он должен отражать понятия предметной области.
Заложить версионность сразу. Первое же изменение сломает тех, кто уже подключился, если нет способа жить со старой версией параллельно.
Ограничить доступ и частоту. Ключи, права, лимиты по каждому потребителю. Иначе один некорректно написанный клиент положит сервис всем.
Написать документацию. С примерами реальных запросов и ответов, включая ошибки. Документация без примеров ошибок бесполезна: именно с ними будет возиться подключающийся.
Дать тестовый контур. Чтобы партнер мог подключиться, не трогая ваши боевые данные.

Что подключают чаще всего

Платежные системы. Прием оплаты, возвраты, регулярные списания, чеки. Самая ответственная категория: здесь недопустимы ни двойное списание, ни потерянный платеж, поэтому подключение всегда идет через тестовый контур и с журналом.
Службы доставки и транспортные компании. Расчет стоимости, создание заявки, печать наклеек, отслеживание. Сложность в том, что у каждой компании свои правила и свой формат, а клиенту нужно единое поведение.
Маркетплейсы. Заказы, остатки, цены, статусы. Отдельная головная боль — ограничения на частоту обращений: при большом ассортименте обновление остатков надо планировать, а не делать в лоб.
Банки. Выписки, платежные поручения, проверка контрагентов. Обычно требует отдельного согласования и работы в защищенном контуре.
ЭДО и электронная подпись. Отправка и прием документов, статусы подписания, автоматическое создание записей в учете.
Телефония. Звонки в карточке клиента, запись разговоров, всплывающая карточка при входящем. Классический пример интеграции, которая окупается за счет мелочей.
Государственные сервисы. Маркировка, проверка реквизитов и статуса контрагента, реестры. Здесь чаще всего встречаются жесткие форматы и специфические требования к соединению.
Сервисы уведомлений. Почта, сообщения, мессенджеры. Технически просто, но требует аккуратности с очередями: рассылка не должна тормозить основную работу системы.

Как понять, сколько это займет

Оценка подключения почти целиком определяется тремя вопросами, и ответы на них видны до начала работ.

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

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

Где здесь искусственный интеллект

Разбор чужой документации. Описание большого API читается и превращается в рабочий черновик подключения заметно быстрее, чем вручную. Особенно когда документация объемная и написана плохо.
Приведение неструктурированного к структуре. Заказы приходят письмом в свободной форме, прайсы — файлами разного формата от каждого поставщика. Модель разбирает их и выдает структуру, пригодную для загрузки, — задача, которая раньше требовала живого оператора на постоянной основе.
Разбор ошибок обмена. Логи с тысячами записей превращаются в объяснение, что именно и когда начало ломаться.
Генерация тестов и заглушек. Проверка поведения при всех вариантах ответа внешнего сервиса, включая те, которые в жизни случаются раз в год.

Сроки и стоимость

от 3 днейподключение к сервису с хорошей документацией: платежи, доставка, проверка контрагентов

1–3 неделиинтеграция со сложным или плохо документированным API, с журналом и обработкой сбоев

3–6 недельсвой API для партнеров с авторизацией, лимитами, версиями и документацией

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

Подключим то, что нужно, и сделаем это устойчиво

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

Обсудить подключение

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

Частые ошибки

Считают, что внешний сервис всегда доступен. Работает месяц, потом у поставщика сбой — и ваши заказы перестают оформляться вообще, вместо того чтобы встать в очередь.
Нет защиты от двойного выполнения. Клиента списали дважды, товар зарезервировали дважды. Обнаруживается в самый неудобный момент.
Ключи в репозитории. Классика, которая заканчивается неприятно, особенно если репозиторий когда-нибудь станет доступен шире.
Нет журнала. Что-то не прошло, а доказать нечем — ни своей правоты, ни чужой ошибки.
Свой API как зеркало базы данных. Каждое изменение структуры ломает всех подключенных, и менять систему становится страшно.
Проверяют на боевых данных. Особенно с платежами и отгрузками. Тестовый контур существует именно для этого.

Что остается у вас

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

Для своего API — документация с примерами и тестовый контур, которые позволяют партнеру подключиться без участия разработчика. Это тот случай, когда качество документации напрямую превращается в скорость подключения новых партнеров.

Дальше по теме

Интеграция 1С с сайтом — остатки, цены и заказы без ручного переноса API-интеграции — как связать системы Интеграция с 1С Синхронизация данных между системами Личный кабинет клиента SaaS-платформа

Обсудить задачу

Частые вопросы

Сколько стоит подключить внешний сервис?

Подключение к сервису с хорошей документацией и тестовым контуром — от трех дней. Интеграция со сложным или плохо документированным API, с журналом и обработкой сбоев — 1–3 недели. Разброс объясняется качеством той стороны, и это выясняется в процессе, а не по названию сервиса.

Что происходит, если внешний сервис не отвечает?

То, что заложено заранее: повтор с нарастающей задержкой (через 1, 5, 30 минут, чтобы не добить чужой сервис), а когда попытки кончились — операция уходит в очередь и человеку приходит уведомление. Операция не теряется, и кто-то знает, что она висит. Подключение занимает дни, а правильное поведение при сбоях — остальное время проекта.

Как защититься от двойного списания или двойной отгрузки?

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

Нужен ли нам свой API?

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

Сколько занимает разработка своего API?

API для партнеров с авторизацией, лимитами по каждому потребителю, версиями, документацией с примерами и тестовым контуром — 3–6 недель. Больше всего времени уходит не на код, а на проектирование: API должен отражать понятия предметной области, а не структуру вашей базы.

Что такое ограничения на частоту обращений и почему это важно?

У большинства сервисов есть лимит числа запросов за период. Его надо знать заранее и укладываться в него, иначе интеграция встанет ровно в момент пиковой нагрузки. Особенно заметно на маркетплейсах: при большом ассортименте обновление остатков приходится планировать, а не делать в лоб.

Где будут храниться ключи доступа?

В вашем хранилище, не в коде и не в репозитории. Это базовая гигиена, которую нарушают чаще, чем хотелось бы, и последствия неприятные — особенно если репозиторий когда-нибудь станет доступен шире.

Как доказать, чья ошибка, если что-то не прошло?

Журналом запросов и ответов: что отправили, что получили, когда. Без него спор с поставщиком услуги решить невозможно. Журнал мы делаем всегда и отдаем к нему доступ вам, а не держим у себя.

Начать проект