В версии 3 добавлена функциональность выбора способа доставки карты для пластиковых карт.
Важные правила:
formFactor = PLASTIC — блок delivery обязателенformFactor = VIRTUAL — блок delivery запрещён (виртуальные карты не требуют физической доставки)POST /rest/practice/cards/api/v1/card-issue
Важно: URL не изменился. Изменилась только структура запроса — добавлен обязательный блок delivery.
deliveryВ тело запроса добавлен блок delivery на одном уровне с cardOwner, formFactor, cardHolder и options.
Для PLASTIC карт (обязателен):
{
"request": {
"cardOwner": "...",
"formFactor": "PLASTIC",
"cardHolder": { ... },
"options": { ... },
"delivery": { ... } // ОБЯЗАТЕЛЕН для PLASTIC
}
}
Для VIRTUAL карт (запрещён):
{
"request": {
"cardOwner": "...",
"formFactor": "VIRTUAL",
"cardHolder": { ... },
"options": { ... }
// delivery НЕ ДОЛЖЕН быть указан!
}
}
Клиент должен выбрать один из двух способов доставки:
| Способ | Поле | Описание |
|---|---|---|
| В отделение | toBranch |
Карта доставляется в выбранное отделение банка |
| Курьером | courier |
Карта доставляется курьером по указанному адресу |
Бизнес-правило: Нельзя указать оба способа одновременно. Нельзя оставить блок пустым.
toBranch)"delivery": {
"toBranch": {
"id": "0001"
}
}
| Поле | Тип | Обязательность | Описание |
|---|---|---|---|
id |
string | Да | Идентификатор отделения банка (4 цифры) |
В системе доступно 20 отделений с ID от 0001 до 0020.
Получить список: GET /rest/practice/cards/branch-api/api/v1/branches
courier)"delivery": {
"courier": {
"address": {
"country": "Россия",
"region": "Московская область",
"city": "Москва",
"street": "Ленина",
"building": "1",
"apartment": "25"
},
"recipient": {
"userId": "XAAAAA"
},
"date": "26-12-2025",
"timeSlot": {
"from": "09:00",
"to": "13:00"
}
}
}
address — Адрес доставки| Поле | Тип | Обязательность | Описание |
|---|---|---|---|
country |
string | Да | Страна |
region |
string | Да | Регион / область |
city |
string | Да | Город |
street |
string | Да | Улица |
building |
string | Да | Номер дома / строения |
apartment |
string | Нет | Номер квартиры / офиса |
recipient — ПолучательПолучателем карты может быть:
userIduserБизнес-правило: Нельзя указать оба варианта одновременно.
"recipient": {
"userId": "XAAAAA"
}
| Поле | Тип | Обязательность | Описание |
|---|---|---|---|
userId |
string | Да* | ID клиента в системе (формат: X + 5 символов) |
Бизнес-правило: Клиент с указанным userId должен существовать в системе.
"recipient": {
"user": {
"firstName": "Сергей",
"middleName": "Иванович",
"lastName": "Сидоров",
"contactInfo": {
"phone": "79001234567"
}
}
}
| Поле | Тип | Обязательность | Описание |
|---|---|---|---|
firstName |
string | Да | Имя получателя |
middleName |
string | Нет | Отчество получателя |
lastName |
string | Да | Фамилия получателя |
contactInfo.phone |
string | Да | Телефон получателя (формат: 7XXXXXXXXXX) |
Важно: Данные третьего лица не сохраняются в базу клиентов. Они используются только для оформления доставки.
date — Дата доставки| Поле | Тип | Обязательность | Формат | Описание |
|---|---|---|---|---|
date |
string | Да | dd-MM-yyyy |
Желаемая дата доставки |
Бизнес-правила:
timeSlot — Временной интервал| Поле | Тип | Обязательность | Формат | Описание |
|---|---|---|---|---|
from |
string | Да | HH:mm |
Начало временного окна |
to |
string | Да | HH:mm |
Конец временного окна |
Бизнес-правила:
from должно быть в диапазоне 09:00 — 17:00to должно быть в диапазоне 13:00 — 21:00from и to должен быть ровно 4 часаНачало (from) |
Конец (to) |
|---|---|
| 09:00 | 13:00 |
| 10:00 | 14:00 |
| 11:00 | 15:00 |
| 12:00 | 16:00 |
| 13:00 | 17:00 |
| 14:00 | 18:00 |
| 15:00 | 19:00 |
| 16:00 | 20:00 |
| 17:00 | 21:00 |
| Ситуация | Сообщение |
|---|---|
PLASTIC без delivery |
Delivery is required for PLASTIC cards |
VIRTUAL с delivery |
Delivery is not allowed for VIRTUAL cards |
Указаны и toBranch, и courier |
Only one delivery method allowed: toBranch or courier |
| Не указан ни один способ доставки | Delivery method required: toBranch or courier |
| Неверный формат ID отделения | Branch ID must be exactly 4 digits |
| Не указан получатель | Recipient is required for courier delivery |
Указаны и userId, и user |
Only one recipient allowed: userId or user |
| Дата в прошлом или сегодня | Delivery date must be at least tomorrow |
| Дата более 7 дней | Delivery date must be within 7 days |
from вне диапазона |
Time slot 'from' must be between 09:00 and 17:00 |
to вне диапазона |
Time slot 'to' must be between 13:00 and 21:00 |
| Интервал не 4 часа | Time slot interval must be exactly 4 hours |
| Ситуация | Сообщение в failureReason |
|---|---|
| Отделение не найдено | Branch with id {id} does not exist |
| Получатель (userId) не найден | Recipient user with id {id} does not exist |
{
"request": {
"cardOwner": "XAAAAA",
"formFactor": "PLASTIC",
"cardHolder": {
"userId": "XAAAAA",
"nameless": false,
"embossedName": "IVAN PETROV"
},
"delivery": {
"toBranch": {
"id": "0005"
}
}
}
}
{
"request": {
"cardOwner": "XAAAAA",
"formFactor": "PLASTIC",
"cardHolder": {
"userId": "XAAAAA",
"nameless": false,
"embossedName": "IVAN PETROV"
},
"delivery": {
"courier": {
"address": {
"country": "Россия",
"region": "Московская область",
"city": "Москва",
"street": "Тверская",
"building": "10",
"apartment": "5"
},
"recipient": {
"userId": "XAAAAA"
},
"date": "27-12-2025",
"timeSlot": {
"from": "10:00",
"to": "14:00"
}
}
}
}
}
{
"request": {
"cardOwner": "XAAAAA",
"formFactor": "PLASTIC",
"cardHolder": {
"userId": "XAAAAA",
"nameless": false,
"embossedName": "IVAN PETROV"
},
"delivery": {
"courier": {
"address": {
"country": "Россия",
"region": "Ленинградская область",
"city": "Санкт-Петербург",
"street": "Невский проспект",
"building": "100"
},
"recipient": {
"user": {
"firstName": "Мария",
"lastName": "Петрова",
"contactInfo": {
"phone": "79219876543"
}
}
},
"date": "28-12-2025",
"timeSlot": {
"from": "14:00",
"to": "18:00"
}
}
}
}
}
| API | Назначение |
|---|---|
| Branch API | Справочник отделений |
| User API | Проверка существования клиентов |