Методы для партнёров-агрегаторов (SUBPARTNER)#

Обзор#

Партнёр-агрегатор — партнёр, через которого к «Подели» подключаются другие продавцы — субпартнёры. Методы SUBPARTNER позволяют агрегатору зарегистрировать субпартнёра, узнать его статус и обновить его данные. Остальным партнёрам эти методы недоступны.

Жизненный цикл субпартнёра:

  1. Регистрация. Партнёр-агрегатор подаёт заявку методом SUBPARTNER/REGISTRATION.

  2. Рассмотрение. «Подели» рассматривает заявку — активирует субпартнёра или отказывает. Срок рассмотрения — до 5 рабочих дней.

  3. Активация или отказ. О результате «Подели» сообщает HTTP-нотификацией; текущий статус в любой момент можно запросить методом SUBPARTNER/INFO.

  4. Обновление данных. При изменении реквизитов субпартнёра агрегатор передаёт новые данные методом SUBPARTNER/UPDATE.

Метод

Эндпоинт

Назначение

REGISTRATION

POST /subpartner/registration

Подать заявку на регистрацию субпартнёра

INFO

GET /subpartner/info/{subpartner_login}

Запросить статус субпартнёра

UPDATE

POST /subpartner/update

Обновить данные субпартнёра

Запросы выполняются в формате JSON поверх HTTPS; соединение защищено по схеме Mutual TLS (mTLS) — см. Настройка защищённого соединения. Авторизация — Basic Auth (логин и пароль партнёра-агрегатора). Полный набор обязательных заголовков приведён в каждом методе ниже.

Адрес тестового контура — https://api-sand.podeli.ru/partners/v1; адрес боевого контура уточните у менеджера по интеграции.

О смене статуса субпартнёра «Подели» уведомляет HTTP-нотификацией — см. нотификацию о статусе субпартнёра и справочник статусов. Нотификация — основной канал: о смене статуса узнавайте из неё, а метод INFO используйте для сверки и восстановления после сбоев.

SUBPARTNER/REGISTRATION — регистрация субпартнёра#

Регистрирует заявку на подключение субпартнёра к сервису.

POST https://api-sand.podeli.ru/partners/v1/subpartner/registration

Как работает

  1. Партнёр-агрегатор направляет данные субпартнёра для автоматической регистрации в сервисе.

  2. «Подели» регистрирует заявку и возвращает подтверждение в поле feedback.

  3. После рассмотрения заявки (активация или отказ) на URL из notificationUrlReg (или на дефолтный адрес нотификаций партнёра) придёт HTTP-нотификация со статусом субпартнёра.

Заголовки запроса

Все заголовки обязательны.

Заголовок

Тип

Описание

Content-Type

string

Тип контента: application/json

Authorization

base64

Basic Auth: логин и пароль партнёра-агрегатора в формате логин:пароль, закодированные в base64

X-Correlation-ID

string(36)

Идентификатор запроса в формате UUID v4. Для каждого нового HTTP-запроса передавайте новое значение

User-Agent

string

Название и версия ПО, выполняющего запрос, например curl/7.81.0. Обязательный заголовок

Host

string

Доменное имя контура, к которому выполняется запрос (для тестового — api-sand.podeli.ru). Обязательный заголовок

Параметры запроса

Тело запроса — объект subPartnerInfo:

Объект subPartnerInfo#

Поле

Тип

Обяз.

Описание

login

string

✓

Логин субпартнёра. Не менее 4 символов

name

string

✓

Наименование субпартнёра

legalEntity

string

✓

Наименование юридического лица. Формат важен, например: ИП ИВАНОВ ИВАН ИВАНОВИЧ, ООО "РОМАШКА"

inn

string

✓

ИНН субпартнёра

kpp

string

—

КПП субпартнёра

ogrn

string

—

ОГРН субпартнёра

mcc

string

✓

MCC-код. Ровно 4 цифры

email

string

✓

Email (для реестров)

siteUrl

string

✓

URL сайта субпартнёра

notificationUrlReg

string

—

URL для получения нотификаций о смене статуса субпартнёра

agreementSignDate

string date

✓

Дата подписания договора в формате YYYY-MM-DD

commission

number

✓

Размер вознаграждения — установленный процент с мерчанта по тарифу

averageCheck

number

—

Средний чек по всем операциям за последние 30 дней

requisite

object

✓

Банковские реквизиты

├─ bankName

string

✓

Наименование банка

├─ bankIdentifierCode

string

✓

БИК

├─ correspondingAccount

string

✓

Корреспондентский счёт

└─ paymentAccount

string

✓

Расчётный счёт, установленный в магазине

address

object

✓

Юридический адрес мерчанта

├─ index

string

✓

Индекс

├─ city

string

✓

Город

├─ street

string

—

Улица

├─ house

string

—

Дом

└─ office

string

—

Офис/квартира

Тело ответа

Поле

Тип

Обяз.

Описание

feedback

string

—

Сообщение об успешной регистрации заявки

error

object

—

Описание ошибки (поля code, text)

Примеры

Все значения в примерах условные.

{
  "subPartnerInfo": {
    "login": "submerchant_01",
    "name": "Ромашка",
    "legalEntity": "ООО \"РОМАШКА\"",
    "inn": "7712345678",
    "kpp": "771201001",
    "ogrn": "1207700123456",
    "mcc": "5651",
    "email": "finance@romashka.ru",
    "siteUrl": "https://romashka.ru",
    "notificationUrlReg": "https://partner.site/subpartnerStatus",
    "agreementSignDate": "2026-06-01",
    "commission": 1.0,
    "averageCheck": 1000.00,
    "requisite": {
      "bankName": "Банк Пример",
      "bankIdentifierCode": "044525999",
      "correspondingAccount": "30101810400000000999",
      "paymentAccount": "40702810900000012345"
    },
    "address": {
      "index": "125009",
      "city": "Москва",
      "street": "Тверская",
      "house": "1",
      "office": "10"
    }
  }
}

{
  "feedback": "Заявка на регистрацию субпартнера успешно заведена."
}

Статус-коды и ошибки метода

Код

Код ошибки

Значение

200

—

Заявка создана

400

invalid_request

Ошибка валидации тела/параметров запроса (в т.ч. некорректные login, mcc или X-Correlation-ID)

401

not_authorized_partner_login, not_authorized_partner_expired

Аутентификация не пройдена: неверные логин/пароль, партнёр отключён или истёк срок договора

422

duplicated_request

Субпартнёр с таким логином уже существует

500

unknown_error

Неизвестная ошибка

Связанные нотификации

Результат рассмотрения заявки приходит нотификацией о статусе субпартнёра.

SUBPARTNER/INFO — статус субпартнёра#

Возвращает текущий статус субпартнёра.

GET https://api-sand.podeli.ru/partners/v1/subpartner/info/{subpartner_login}

Как работает

  1. Партнёр-агрегатор передаёт логин субпартнёра в параметре пути subpartner_login. Тело запроса пустое.

  2. «Подели» возвращает логин и текущий статус субпартнёра.

Заголовки запроса

Все заголовки обязательны.

Заголовок

Тип

Описание

Content-Type

string

Тип контента: application/json

Authorization

base64

Basic Auth: логин и пароль партнёра-агрегатора в формате логин:пароль, закодированные в base64

X-Correlation-ID

string(36)

Идентификатор запроса в формате UUID v4. Для каждого нового HTTP-запроса передавайте новое значение

User-Agent

string

Название и версия ПО, выполняющего запрос, например curl/7.81.0. Обязательный заголовок

Host

string

Доменное имя контура, к которому выполняется запрос (для тестового — api-sand.podeli.ru). Обязательный заголовок

Параметры запроса

Поле

Тип

Обяз.

Описание

subpartner_login

string, параметр пути

✓

Логин субпартнёра

Тело ответа

Поле

Тип

Обяз.

Описание

subPartnerInfo

object

✓

Субпартнёр

├─ login

string

✓

Логин субпартнёра

└─ status

string

✓

Статус субпартнёра в верхнем регистре — см. справочник статусов

error

object

—

Описание ошибки (поля code, text)

Примеры

{
  "subPartnerInfo": {
    "login": "submerchant_01",
    "status": "ACTIVATED"
  }
}

Статус-коды и ошибки метода

Код

Код ошибки

Значение

200

—

Запрос успешно обработан

400

invalid_request

Ошибка валидации параметров запроса

401

not_authorized_partner_login, not_authorized_partner_expired

Аутентификация не пройдена: неверные логин/пароль, партнёр отключён или истёк срок договора

404

sub_partner_not_found

Запись субпартнёра с указанным login не найдена для партнёра, сделавшего запрос

500

unknown_error

Неизвестная ошибка

Связанные нотификации

О смене статуса субпартнёра «Подели» дополнительно уведомляет HTTP-нотификацией — метод INFO позволяет проверить статус в любой момент по запросу.

SUBPARTNER/UPDATE — обновление данных субпартнёра#

Обновляет данные ранее зарегистрированного субпартнёра.

POST https://api-sand.podeli.ru/partners/v1/subpartner/update

Как работает

  1. При изменении реквизитов субпартнёра Партнёр-агрегатор направляет метод UPDATE с объектом subPartnerInfo.

  2. «Подели» обновляет данные и возвращает подтверждение в поле feedback.

Внимание

Поля login, name, inn, kpp, ogrn и mcc изменению не подлежат — они передаются для идентификации субпартнёра. Если переданные значения отличаются от сохранённых, метод вернёт статус-код 409 (sub_partner_data_conflict).

Заголовки запроса

Все заголовки обязательны.

Заголовок

Тип

Описание

Content-Type

string

Тип контента: application/json

Authorization

base64

Basic Auth: логин и пароль партнёра-агрегатора в формате логин:пароль, закодированные в base64

X-Correlation-ID

string(36)

Идентификатор запроса в формате UUID v4. Для каждого нового HTTP-запроса передавайте новое значение

User-Agent

string

Название и версия ПО, выполняющего запрос, например curl/7.81.0. Обязательный заголовок

Host

string

Доменное имя контура, к которому выполняется запрос (для тестового — api-sand.podeli.ru). Обязательный заголовок

Параметры запроса

Тело запроса — объект subPartnerInfo:

Объект subPartnerInfo#

Поле

Тип

Обяз.

Описание

login

string

✓

Логин субпартнёра (не изменяется)

name

string

✓

Наименование субпартнёра (не изменяется)

inn

string

✓

ИНН субпартнёра (не изменяется)

kpp

string

—

КПП субпартнёра (не изменяется)

ogrn

string

—

ОГРН субпартнёра (не изменяется)

mcc

string

✓

MCC-код (не изменяется)

email

string

✓

Email (для реестров)

siteUrl

string

✓

URL сайта субпартнёра

notificationUrlReg

string

—

URL для получения нотификаций о смене статуса субпартнёра

agreementSignDate

string date

✓

Дата подписания договора в формате YYYY-MM-DD

commission

number

—

Размер вознаграждения — установленный процент с мерчанта по тарифу

averageCheck

number

—

Средний чек по всем операциям за последние 30 дней

requisite

object

✓

Банковские реквизиты: bankName ✓, bankIdentifierCode ✓, correspondingAccount ✓, paymentAccount ✓ — как в SUBPARTNER/REGISTRATION

address

object

✓

Юридический адрес мерчанта: index ✓, city ✓, street, house, office — как в SUBPARTNER/REGISTRATION

Тело ответа

Поле

Тип

Обяз.

Описание

feedback

string

—

Сообщение об успешном изменении данных

error

object

—

Описание ошибки (поля code, text)

Примеры

Все значения в примерах условные.

{
  "subPartnerInfo": {
    "login": "submerchant_01",
    "name": "Ромашка",
    "inn": "7712345678",
    "kpp": "771201001",
    "ogrn": "1207700123456",
    "mcc": "5651",
    "email": "billing@romashka.ru",
    "siteUrl": "https://romashka.ru",
    "notificationUrlReg": "https://partner.site/subpartnerStatus",
    "agreementSignDate": "2026-06-01",
    "requisite": {
      "bankName": "Банк Пример",
      "bankIdentifierCode": "044525999",
      "correspondingAccount": "30101810400000000999",
      "paymentAccount": "40702810900000067890"
    },
    "address": {
      "index": "125009",
      "city": "Москва",
      "street": "Тверская",
      "house": "1",
      "office": "10"
    }
  }
}

Статус-коды и ошибки метода

Код

Код ошибки

Значение

200

—

Данные обновлены

400

invalid_request

Ошибка валидации тела/параметров запроса

401

not_authorized_partner_login, not_authorized_partner_expired

Аутентификация не пройдена: неверные логин/пароль, партнёр отключён или истёк срок договора

404

sub_partner_not_found

Запись субпартнёра с указанным login не найдена для партнёра, сделавшего запрос

409

sub_partner_data_conflict

Переданы изменения в полях, недоступных для редактирования: «Изменение информации недоступно для поля {поле}»

429

req_number_exceeded

Превышен лимит запросов; в заголовке X-Retry-After придёт время в секундах до повторного запроса

500

unknown_error

Неизвестная ошибка

Связанные нотификации

При смене статуса субпартнёра (активация, отказ, отключение) «Подели» отправляет нотификацию о статусе субпартнёра.