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