Сonnector api ============= Base URL: ``https://connector-direct.i-dgtl.ru`` Аутентификация -------------- Все запросы (кроме ``/auth/token``\ ) должны содержать заголовок ``Authorization`` с Bearer-токеном: .. code-block:: Authorization: Bearer Получить токен ^^^^^^^^^^^^^^ .. code-block:: POST /auth/token **Request:** .. code-block:: json { "login": "partner@example.com", "password": "your_password" } .. list-table:: :header-rows: 1 * - Поле - Тип - Обязательное - Описание * - login - string - да - Логин партнера в системе Direct * - password - string - да - Пароль партнера **Response:** ``200 OK`` .. code-block:: json { "token": "dGhpcyBpcyBhbiBleGFtcGxlIHRva2VuIGZvciBkb2Nz..." } Полученный токен используйте в заголовке ``Authorization``\ : .. code-block:: Authorization: Bearer dGhpcyBpcyBhbiBleGFtcGxlIHRva2VuIGZvciBkb2Nz... **Важно:** * При смене пароля в Direct нужно получить новый токен ---- Company API ----------- Управление компаниями (клиентами). Создать компанию ^^^^^^^^^^^^^^^^ .. code-block:: POST /company **Request:** .. code-block:: json { "company": { "name": "ООО Рога и Копыта", "counteragentType": "LEGAL", "counteragentInn": "7707083893", "counteragentAddress": "г. Москва, ул. Примерная, д. 1", "counteragentKpp": "770701001" }, "budget": 10000.00 } .. list-table:: :header-rows: 1 * - Поле - Тип - Обязательное - Описание * - company.name - string - да - Название компании * - company.counteragentType - enum - да - Тип контрагента: ``LEGAL`` (юрлицо), ``INDIVIDUAL`` (ИП) * - company.counteragentInn - string - да - ИНН * - company.counteragentAddress - string - нет - Юридический адрес * - company.counteragentKpp - string - нет - КПП (для юрлиц) * - budget - double - нет - Месячный лимит расходов **Про лимит расходов:** * ``budget`` — максимальная сумма, которую компания может потратить за месяц * Если не передан — лимит безлимитный * Лимит обнуляется 1-го числа каждого месяца в период с 00:00 до 03:00 * При отправке сообщений резервируется приблизительная стоимость (может быть выше финальной) * Финальная стоимость определяется после доставки и может быть ниже зарезервированной **Response:** ``201 Created`` .. code-block:: json { "companyId": 123 } ---- Получить список компаний ^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: GET /company?page=1&per_page=10 **Query Parameters:** .. list-table:: :header-rows: 1 * - Параметр - Тип - По умолчанию - Описание * - page - int - 1 - Номер страницы * - per_page - int - 10 - Количество на странице **Response:** ``200 OK`` .. code-block:: json { "page": 1, "perPage": 10, "total": 42, "items": [ { "companyId": 123, "name": "ООО Рога и Копыта", "counteragentName": "ООО Рога и Копыта", "counteragentInn": "7707083893", "status": "ACTIVE", "budget": { "value": 10000.00, "currency": "RUB" } } ] } ---- Обновить компанию ^^^^^^^^^^^^^^^^^ .. code-block:: PUT /company/{id} **Request:** .. code-block:: json { "budget": 50000.00, "status": "ACTIVE", "name": "Новое название", "actualAddress": "г. Москва, ул. Фактическая, д. 10" } .. list-table:: :header-rows: 1 * - Поле - Тип - Описание * - budget - double - Месячный лимит расходов * - status - enum - Статус: ``ACTIVE``\ , ``DISABLED`` * - name - string - Название компании * - actualAddress - string - Фактический адрес Все поля опциональны. Передавайте только те, которые нужно изменить. **Response:** ``200 OK`` .. code-block:: json { "companyId": 123, "updatedAt": "2024-01-15T10:30:00+03:00" } ---- Загрузить документ ^^^^^^^^^^^^^^^^^^ .. code-block:: POST /company/{id}/documents Content-Type: multipart/form-data **Form Data:** * ``file`` — файл документа (PDF, JPG, PNG, до 10 МБ) **Response:** ``201 Created`` .. code-block:: json { "id": "550e8400-e29b-41d4-a716-446655440000", "companyId": 123, "filename": "contract.pdf", "createdAt": "2024-01-15T10:30:00+03:00" } ---- Получить список документов ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: GET /company/{id}/documents **Response:** ``200 OK`` .. code-block:: json [ { "id": "550e8400-e29b-41d4-a716-446655440000", "companyId": 123, "filename": "contract.pdf", "createdAt": "2024-01-15T10:30:00+03:00" } ] ---- Sender API ---------- Управление отправителями (имена отправителя/подписи для SMS). Создать отправителя ^^^^^^^^^^^^^^^^^^^ .. code-block:: POST /senders **Request:** .. code-block:: json { "companyId": 123, "senderName": "MyCompany", "channelType": "SMS", "commonType": "PROMO", "brand": "MTS", "dateFrom": "2024-01-01T00:00:00Z", "countryId": 1, "description": "Для рекламных рассылок", "documentIds": [ "550e8400-e29b-41d4-a716-446655440000" ] } .. list-table:: :header-rows: 1 * - Поле - Тип - Обязательное - Описание * - companyId - int - да - ID компании * - senderName - string - да - Имя отправителя (до 11 символов для SMS) * - channelType - string - да - Канал: ``SMS``\ , ``VIBER``\ , ``WHATSAPP``\ , ``VK``\ , ``TELEGRAM`` и др. * - commonType - string - да - Тип: ``PROMO``\ , ``COMMON``\ , ``MULTISIGNATURE``\ , ``INTERNATIONAL_VERIFY``\ , ``INTERNATIONAL_COMMON`` * - brand - string - да - Оператор: ``MTS``\ , ``BEELINE``\ , ``MEGAFON``\ , ``TELE2`` * - dateFrom - datetime - да - Дата начала действия * - countryId - int - нет - ID страны (1 = Россия) * - description - string - нет - Описание/комментарий * - documentIds - string[] - нет - ID документов, ранее загруженных через ``POST /company/{id}/documents`` **Response:** ``201 Created`` .. code-block:: json { "id": 789, "senderName": "MyCompany", "channelType": "SMS", "counteragentName": "ООО Рога и Копыта", "counteragentInn": "7707083893", "dateFrom": "2024-01-01T00:00:00Z", "dateTo": null, "commonType": "PROMO", "brand": "MTS", "status": "DRAFT", "suspended": false, "fee": null, "managerComment": null, "rejectedAt": null, "createdAt": "2024-01-15T10:30:00Z" } **Статусы отправителя:** * ``DRAFT`` — черновик * ``PRE_REVIEW`` — на предварительном рассмотрении * ``INTERNAL_REVIEW`` — на внутреннем рассмотрении * ``EXTERNAL_REVIEW`` — на рассмотрении у оператора * ``AWAITING`` — ожидает активации * ``APPROVED`` — одобрен, можно использовать * ``REJECTED`` — отклонен * ``DENIED`` — запрещен * ``CLOSED`` — закрыт ---- Получить список отправителей ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: GET /senders?companyId=123 **Query Parameters:** .. list-table:: :header-rows: 1 * - Параметр - Тип - Описание * - companyId - int - ID компании (обязательный) * - brand - string[] - Фильтр по операторам * - commonType - string[] - Фильтр по типу * - status - string[] - Фильтр по статусу * - channelType - string[] - Фильтр по каналу * - countryCode - string[] - Фильтр по коду страны **Пример с фильтрами:** .. code-block:: GET /senders?companyId=123&brand=MTS&brand=BEELINE&status=APPROVED **Response:** ``200 OK`` .. code-block:: json [ { "id": 789, "senderName": "MyCompany", "channelType": "SMS", "counteragentName": "ООО Рога и Копыта", "counteragentInn": "7707083893", "dateFrom": "2024-01-01T00:00:00Z", "dateTo": null, "commonType": "PROMO", "brand": "MTS", "status": "APPROVED", "suspended": false, "fee": 0.50, "managerComment": null, "rejectedAt": null, "createdAt": "2024-01-15T10:30:00Z" } ] **Удаление отправителя** возможно через: #. ``PUT /senders/{id}`` с указанием ``dateTo`` — дата окончания действия (правила и ограничения уточняйте у бизнеса) #. ``POST /senders/{id}/suspend`` — немедленная блокировка использования в рассылках ---- Получить отправителя по ID ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: GET /senders/{id}?companyId=123 **Response:** ``200 OK`` (структура как в списке) ---- Обновить отправителя ^^^^^^^^^^^^^^^^^^^^ .. code-block:: PUT /senders/{id} **Request:** .. code-block:: json { "senderName": "NewName", "commonType": "COMMON", "dateFrom": "2024-02-01T00:00:00Z", "dateTo": "2025-01-01T00:00:00Z", "documentIds": [] } .. list-table:: :header-rows: 1 * - Поле - Тип - Описание * - senderName - string - Новое имя отправителя * - commonType - enum - Тип: ``PROMO``\ , ``COMMON``\ , ``MULTISIGNATURE``\ , ``INTERNATIONAL_VERIFY``\ , ``INTERNATIONAL_COMMON`` * - dateFrom - datetime - Дата начала действия * - dateTo - datetime - Дата окончания действия (для закрытия имени) * - documentIds - string[] - ID документов Все поля опциональны. **Response:** ``200 OK`` (структура как в списке) ---- Приостановить отправителя ^^^^^^^^^^^^^^^^^^^^^^^^^ Работает независимо от реального статуса в системе оператора и позволяет остановить трафик по данному sender name. Для полного прекращения обслуживания также необходимо закрыть имя через ``PUT /senders/{id}`` с указанием ``dateTo``. .. code-block:: POST /senders/{id}/suspend **Request (опционально):** .. code-block:: json { "reason": "Жалоба на спам" } **Response:** ``200 OK`` (структура как в списке, с ``suspended: true`` и ``suspendReason``\ ) ---- Возобновить отправителя ^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: POST /senders/{id}/unsuspend **Response:** ``200 OK`` (структура как в списке, с ``suspended: false``\ ) ---- Dispatch API ------------ Создание и управление рассылками. Создать рассылку ^^^^^^^^^^^^^^^^ .. code-block:: POST /dispatches **Request:** .. code-block:: json { "companyId": 123, "name": "Новогодняя акция", "senderIds": [789, 790, 791], "channelType": "SMS", "text": "Привет, {name}! Скидка 20% до конца месяца. Промокод: {code}", "messages": [ { "destination": "79001234567", "substitutions": { "name": "Иван", "code": "NY2024" } }, { "destination": "79007654321", "customText": "Полностью кастомный текст для этого получателя" } ], "schedule": { "startAt": "2024-01-15T10:00:00Z", "hours": [10, 11, 12, 13, 14, 15, 16, 17, 18], "days": [1, 2, 3, 4, 5] }, "callbackUrl": "https://your-api.com/callbacks/dispatch", "callbackEvents": ["delivered", "sent"] } .. list-table:: :header-rows: 1 * - Поле - Тип - Обязательное - Описание * - companyId - int - да - ID компании * - name - string - да - Название рассылки * - senderIds - int[] - да - ID отправителей (по одному на каждого оператора) * - channelType - string - да - Канал: ``SMS``\ , ``VIBER``\ , ``WHATSAPP`` и др. * - text - string - да - Текст сообщения с плейсхолдерами ``{name}`` * - messages - array - да - Список получателей * - messages[].destination - string - да - Номер телефона (79001234567) * - messages[].substitutions - object - нет - Подстановки для плейсхолдеров * - messages[].customText - string - нет - Полностью кастомный текст (игнорирует ``text``\ ) * - schedule - object - нет - Расписание отправки * - schedule.startAt - datetime - да - Время начала рассылки * - schedule.hours - int[] - да - Разрешенные часы (0-23) * - schedule.days - int[] - да - Разрешенные дни недели (1=Пн, 7=Вс) * - callbackUrl - string - нет - URL для webhook-уведомлений о статусах * - callbackEvents - string[] - нет - События: ``delivered``\ , ``sent`` **Response:** ``200 OK`` .. code-block:: json { "id": 1001, "status": "CREATED", "priceEstimate": { "total": 150.00, "currency": "RUB", "parts": 2 }, "total": 2, "success": 2, "failed": 0, "messages": [ { "destination": "79001234567", "messageUuid": "550e8400-e29b-41d4-a716-446655440001", "parts": 1, "senderId": 789 }, { "destination": "79007654321", "messageUuid": "550e8400-e29b-41d4-a716-446655440002", "parts": 1, "senderId": 790 } ] } **Routing:** Система автоматически определяет оператора каждого номера и назначает соответствующего отправителя из ``senderIds``. ---- Добавить сообщения в рассылку ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Добавление сообщений в уже созданную рассылку (только в статусе ``CREATED``\ ). .. code-block:: POST /dispatches/{id}/messages **Request:** .. code-block:: json { "messages": [ { "destination": "79009876543", "substitutions": { "name": "Петр", "code": "NY2024" } } ] } **Response:** ``200 OK`` (структура как при создании) ---- Запустить рассылку ^^^^^^^^^^^^^^^^^^ .. code-block:: POST /dispatches/{id}/start **Response:** ``200 OK`` .. code-block:: json { "id": 1001, "status": "STARTED" } ---- Остановить рассылку ^^^^^^^^^^^^^^^^^^^ .. code-block:: POST /dispatches/{id}/stop **Response:** ``200 OK`` .. code-block:: json { "id": 1001, "status": "STOPPED" } ---- Получить список рассылок ^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: GET /dispatches?companyId=123&status=STARTED&page=1&perPage=10 **Query Parameters:** .. list-table:: :header-rows: 1 * - Параметр - Тип - По умолчанию - Описание * - companyId - int - — - ID компании (обязательный) * - status - string - — - Фильтр по статусу: ``CREATED``\ , ``STARTED``\ , ``STOPPED``\ , ``COMPLETED`` * - page - int - 1 - Номер страницы * - perPage - int - 10 - Количество на странице **Response:** ``200 OK`` .. code-block:: json { "page": 1, "perPage": 10, "total": 5, "items": [ { "id": 1001, "name": "Новогодняя акция", "status": "STARTED", "channelType": "SMS", "parts": { "total": 100, "delivered": 45, "failed": 5, "pending": 50 }, "messages": { "total": 50, "delivered": 20, "failed": 2, "pending": 28 }, "priceEstimate": 7500.00, "createdAt": "2024-01-15T10:30:00Z", "startedAt": "2024-01-15T10:35:00Z" } ] } ---- Получить рассылку по ID ^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: GET /dispatches/{id} **Response:** ``200 OK`` (структура как в списке) ---- Message API ----------- Получение статусов сообщений. Получить сообщения рассылки ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: GET /messages?dispatchId=1001&status=DELIVERED&page=1&perPage=100 **Query Parameters:** .. list-table:: :header-rows: 1 * - Параметр - Тип - По умолчанию - Описание * - dispatchId - int - — - ID рассылки (обязательный) * - status - string - — - Фильтр по статусу: ``CREATED``\ , ``SENT``\ , ``DELIVERED``\ , ``FAILED`` * - page - int - 1 - Номер страницы * - perPage - int - 100 - Количество на странице **Response:** ``200 OK`` .. code-block:: json { "page": 1, "perPage": 100, "total": 50, "items": [ { "messageUuid": "550e8400-e29b-41d4-a716-446655440001", "destination": "79001234567", "text": "Привет, Иван! Скидка 20% до конца месяца. Промокод: NY2024", "parts": 1, "status": "DELIVERED", "price": 2.50, "senderId": 789, "brandId": 1, "createdAt": "2024-01-15T10:30:00Z", "sentAt": "2024-01-15T10:35:00Z", "deliveredAt": "2024-01-15T10:35:05Z" } ] } **Статусы сообщений:** * ``CREATED`` — создано * ``SENT`` — отправлено оператору * ``DELIVERED`` — доставлено * ``FAILED`` — ошибка доставки ---- Recipient API ------------- Управление черным списком. Добавить/удалить из черного списка ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: PUT /recipients **Request (добавить в blacklist):** .. code-block:: json { "companyId": 123, "msisdn": "79001234567", "blacklist": true, "comment": "Отписался от рассылки" } **Request (удалить из blacklist):** .. code-block:: json { "companyId": 123, "msisdn": "79001234567", "blacklist": false } .. list-table:: :header-rows: 1 * - Поле - Тип - Обязательное - Описание * - companyId - int - да - ID компании * - msisdn - string - да - Номер телефона * - blacklist - bool - да - ``true`` — добавить, ``false`` — удалить * - comment - string - нет - Причина блокировки **Response:** ``200 OK`` .. code-block:: json { "msisdn": "79001234567", "companyId": 123, "blacklist": true } ---- Callbacks (Webhooks) -------------------- При указании ``callbackUrl`` в рассылке, система отправляет POST-запросы на этот URL при изменении статусов сообщений. **Пример callback для события ``delivered``\ :** .. code-block:: json { "event": "delivered", "messageUuid": "550e8400-e29b-41d4-a716-446655440001", "destination": "79001234567", "status": "DELIVERED", "deliveredAt": "2024-01-15T10:35:05Z" } **Пример callback для события ``sent``\ :** .. code-block:: json { "event": "sent", "messageUuid": "550e8400-e29b-41d4-a716-446655440001", "destination": "79001234567", "status": "SENT", "sentAt": "2024-01-15T10:35:00Z" } ---- Price API --------- Тарифы и стоимость сендернеймов. Операция от имени партнёра (admin operation). Получить тарифы трафика ^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: GET /price/tariffs **Query Parameters (все опциональные):** .. list-table:: :header-rows: 1 * - Параметр - Тип - Описание * - senderType - enum - Тип имени: ``COMMON``\ , ``START``\ , ``PRO`` * - brand - string - Оператор: ``MTS``\ , ``BEELINE``\ , ``MEGAFON``\ , ``TELE2`` * - trafficType - enum - Тип трафика: ``PROMO``\ , ``SERVICE``\ , ``TRANSACT``\ , ``AUTHORIZE`` * - pricingModel - enum - Модель ценообразования: ``FIXED``\ , ``SCALED``\ , ``MAU`` **Response:** ``200 OK`` .. code-block:: json { "tariffs": [ { "senderType": "COMMON", "pricingModel": "FIXED", "currency": "RUB", "prices": [ {"from": 1, "price": 3.95, "priceMauBatch": 0} ] }, { "senderType": "START", "brand": "MTS", "pricingModel": "SCALED", "currency": "RUB", "prices": [ {"from": 1, "price": 3.50, "priceMauBatch": 0}, {"from": 10001, "price": 3.20, "priceMauBatch": 0}, {"from": 100001, "price": 2.85, "priceMauBatch": 0} ] }, { "senderType": "PRO", "trafficType": "PROMO", "brand": "BEELINE", "pricingModel": "MAU", "currency": "RUB", "prices": [ {"from": 1, "price": 3.00, "priceMauBatch": 0}, {"from": 1001, "price": 0, "priceMauBatch": 9.00}, {"from": 5001, "price": 0, "priceMauBatch": 15.00}, {"from": 10001, "price": 0, "priceMauBatch": 20.00}, {"from": 50001, "price": 0, "priceMauBatch": 25.00} ] } ] } **Типы имён (\ ``senderType``\ ):** * ``COMMON`` — общее имя, доступно без регистрации, фиксированная цена * ``START`` — требует регистрации, фиксированная цена или MAU (Beeline) * ``PRO`` — платное имя, цена зависит от объёма сообщений или MAU **Модели ценообразования (\ ``pricingModel``\ ):** * ``FIXED`` — фиксированная цена, не зависит от объёма. ``prices`` содержит один элемент * ``SCALED`` — цена зависит от объёма сообщений. ``prices[].from`` — порог кол-ва сообщений * ``MAU`` — цена зависит от кол-ва уникальных получателей. ``prices[].from`` — порог уникальных получателей **Структура ``prices[]``\ :** .. list-table:: :header-rows: 1 * - Поле - Тип - Описание * - from - int - Порог * - price - double - Цена за сообщение * - priceMauBatch - double - Цена за MAU-пакет ---- Получить стоимость имён отправителей ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: GET /price/senders **Response:** ``200 OK`` .. code-block:: json { "senderFees": [ {"brand": "MTS", "value": 5000.00, "currency": "RUB"}, {"brand": "BEELINE", "value": 7500.00, "currency": "RUB"}, {"brand": "MEGAFON", "value": 6000.00, "currency": "RUB"}, {"brand": "TELE2", "value": 4500.00, "currency": "RUB"} ] } .. list-table:: :header-rows: 1 * - Поле - Тип - Описание * - brand - string - Оператор * - value - double - Абонентская плата за имя отправителя * - currency - string - Валюта ---- Ошибки ------ Все ошибки возвращаются в формате: .. code-block:: json { "error": { "code": 4000, "msg": "Описание ошибки" } } **Коды ошибок:** .. list-table:: :header-rows: 1 * - Код - HTTP Status - Описание * - 4000 - 400 - Bad Request — некорректные данные * - 4040 - 404 - Not Found — ресурс не найден `` `` .. toctree:: :hidden: