Сonnector api

Сonnector api#

Base URL: https://connector-direct.i-dgtl.ru

Аутентификация#

Все запросы (кроме /auth/token) должны содержать заголовок Authorization с Bearer-токеном:

Authorization: Bearer <token>

Получить токен#

POST /auth/token

Request:

{
  "login": "partner@example.com",
  "password": "your_password"
}

Поле

Тип

Обязательное

Описание

login

string

да

Логин партнера в системе Direct

password

string

да

Пароль партнера

Response: 200 OK

{
  "token": "dGhpcyBpcyBhbiBleGFtcGxlIHRva2VuIGZvciBkb2Nz..."
}

Полученный токен используйте в заголовке Authorization:

Authorization: Bearer dGhpcyBpcyBhbiBleGFtcGxlIHRva2VuIGZvciBkb2Nz...

Важно:

  • При смене пароля в Direct нужно получить новый токен

Company API#

Управление компаниями (клиентами).

Создать компанию#

POST /company

Request:

{
  "company": {
    "name": "ООО Рога и Копыта",
    "counteragentType": "LEGAL",
    "counteragentInn": "7707083893",
    "counteragentAddress": "г. Москва, ул. Примерная, д. 1",
    "counteragentKpp": "770701001"
  },
  "budget": 10000.00
}

Поле

Тип

Обязательное

Описание

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

{
  "companyId": 123
}

Получить список компаний#

GET /company?page=1&per_page=10

Query Parameters:

Параметр

Тип

По умолчанию

Описание

page

int

1

Номер страницы

per_page

int

10

Количество на странице

Response: 200 OK

{
  "page": 1,
  "perPage": 10,
  "total": 42,
  "items": [
    {
      "companyId": 123,
      "name": "ООО Рога и Копыта",
      "counteragentName": "ООО Рога и Копыта",
      "counteragentInn": "7707083893",
      "status": "ACTIVE",
      "budget": {
        "value": 10000.00,
        "currency": "RUB"
      }
    }
  ]
}

Обновить компанию#

PUT /company/{id}

Request:

{
  "budget": 50000.00,
  "status": "ACTIVE",
  "name": "Новое название",
  "actualAddress": "г. Москва, ул. Фактическая, д. 10"
}

Поле

Тип

Описание

budget

double

Месячный лимит расходов

status

enum

Статус: ACTIVE, DISABLED

name

string

Название компании

actualAddress

string

Фактический адрес

Все поля опциональны. Передавайте только те, которые нужно изменить.

Response: 200 OK

{
  "companyId": 123,
  "updatedAt": "2024-01-15T10:30:00+03:00"
}

Загрузить документ#

POST /company/{id}/documents
Content-Type: multipart/form-data

Form Data:

  • file — файл документа (PDF, JPG, PNG, до 10 МБ)

Response: 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "companyId": 123,
  "filename": "contract.pdf",
  "createdAt": "2024-01-15T10:30:00+03:00"
}

Получить список документов#

GET /company/{id}/documents

Response: 200 OK

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "companyId": 123,
    "filename": "contract.pdf",
    "createdAt": "2024-01-15T10:30:00+03:00"
  }
]

Sender API#

Управление отправителями (имена отправителя/подписи для SMS).

Создать отправителя#

POST /senders

Request:

{
  "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"
  ]
}

Поле

Тип

Обязательное

Описание

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

{
  "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 — закрыт

Получить список отправителей#

GET /senders?companyId=123

Query Parameters:

Параметр

Тип

Описание

companyId

int

ID компании (обязательный)

brand

string[]

Фильтр по операторам

commonType

string[]

Фильтр по типу

status

string[]

Фильтр по статусу

channelType

string[]

Фильтр по каналу

countryCode

string[]

Фильтр по коду страны

Пример с фильтрами:

GET /senders?companyId=123&brand=MTS&brand=BEELINE&status=APPROVED

Response: 200 OK

[
  {
    "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"
  }
]

Удаление отправителя возможно через:

  1. PUT /senders/{id} с указанием dateTo — дата окончания действия (правила и ограничения уточняйте у бизнеса)

  2. POST /senders/{id}/suspend — немедленная блокировка использования в рассылках

Получить отправителя по ID#

GET /senders/{id}?companyId=123

Response: 200 OK (структура как в списке)

Обновить отправителя#

PUT /senders/{id}

Request:

{
  "senderName": "NewName",
  "commonType": "COMMON",
  "dateFrom": "2024-02-01T00:00:00Z",
  "dateTo": "2025-01-01T00:00:00Z",
  "documentIds": []
}

Поле

Тип

Описание

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.

POST /senders/{id}/suspend

Request (опционально):

{
  "reason": "Жалоба на спам"
}

Response: 200 OK (структура как в списке, с suspended: true и suspendReason)

Возобновить отправителя#

POST /senders/{id}/unsuspend

Response: 200 OK (структура как в списке, с suspended: false)

Dispatch API#

Создание и управление рассылками.

Создать рассылку#

POST /dispatches

Request:

{
  "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"]
}

Поле

Тип

Обязательное

Описание

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

{
  "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).

POST /dispatches/{id}/messages

Request:

{
  "messages": [
    {
      "destination": "79009876543",
      "substitutions": {
        "name": "Петр",
        "code": "NY2024"
      }
    }
  ]
}

Response: 200 OK (структура как при создании)

Запустить рассылку#

POST /dispatches/{id}/start

Response: 200 OK

{
  "id": 1001,
  "status": "STARTED"
}

Остановить рассылку#

POST /dispatches/{id}/stop

Response: 200 OK

{
  "id": 1001,
  "status": "STOPPED"
}

Получить список рассылок#

GET /dispatches?companyId=123&status=STARTED&page=1&perPage=10

Query Parameters:

Параметр

Тип

По умолчанию

Описание

companyId

int

—

ID компании (обязательный)

status

string

—

Фильтр по статусу: CREATED, STARTED, STOPPED, COMPLETED

page

int

1

Номер страницы

perPage

int

10

Количество на странице

Response: 200 OK

{
  "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#

GET /dispatches/{id}

Response: 200 OK (структура как в списке)

Message API#

Получение статусов сообщений.

Получить сообщения рассылки#

GET /messages?dispatchId=1001&status=DELIVERED&page=1&perPage=100

Query Parameters:

Параметр

Тип

По умолчанию

Описание

dispatchId

int

—

ID рассылки (обязательный)

status

string

—

Фильтр по статусу: CREATED, SENT, DELIVERED, FAILED

page

int

1

Номер страницы

perPage

int

100

Количество на странице

Response: 200 OK

{
  "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#

Управление черным списком.

Добавить/удалить из черного списка#

PUT /recipients

Request (добавить в blacklist):

{
  "companyId": 123,
  "msisdn": "79001234567",
  "blacklist": true,
  "comment": "Отписался от рассылки"
}

Request (удалить из blacklist):

{
  "companyId": 123,
  "msisdn": "79001234567",
  "blacklist": false
}

Поле

Тип

Обязательное

Описание

companyId

int

да

ID компании

msisdn

string

да

Номер телефона

blacklist

bool

да

true — добавить, false — удалить

comment

string

нет

Причина блокировки

Response: 200 OK

{
  "msisdn": "79001234567",
  "companyId": 123,
  "blacklist": true
}

Callbacks (Webhooks)#

При указании callbackUrl в рассылке, система отправляет POST-запросы на этот URL при изменении статусов сообщений.

Пример callback для события ``delivered``:

{
  "event": "delivered",
  "messageUuid": "550e8400-e29b-41d4-a716-446655440001",
  "destination": "79001234567",
  "status": "DELIVERED",
  "deliveredAt": "2024-01-15T10:35:05Z"
}

Пример callback для события ``sent``:

{
  "event": "sent",
  "messageUuid": "550e8400-e29b-41d4-a716-446655440001",
  "destination": "79001234567",
  "status": "SENT",
  "sentAt": "2024-01-15T10:35:00Z"
}

Price API#

Тарифы и стоимость сендернеймов. Операция от имени партнёра (admin operation).

Получить тарифы трафика#

GET /price/tariffs

Query Parameters (все опциональные):

Параметр

Тип

Описание

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

{
  "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[]``:

Поле

Тип

Описание

from

int

Порог

price

double

Цена за сообщение

priceMauBatch

double

Цена за MAU-пакет

Получить стоимость имён отправителей#

GET /price/senders

Response: 200 OK

{
  "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"}
  ]
}

Поле

Тип

Описание

brand

string

Оператор

value

double

Абонентская плата за имя отправителя

currency

string

Валюта

Ошибки#

Все ошибки возвращаются в формате:

{
  "error": {
    "code": 4000,
    "msg": "Описание ошибки"
  }
}

Коды ошибок:

Код

HTTP Status

Описание

4000

400

Bad Request — некорректные данные

4040

404

Not Found — ресурс не найден