Versions Compared

Version Old Version 2 New Version Current
Changes made by

Алексей Федоров (Unlicensed)

Anton Sukhorukov

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
minLevel1
maxLevel7

Создание получателя

Описание: Для начала приема чаевых вашими сотрудниками необходимо создать получателя в системе.

Адрес: https://api.cloudtips.ru/api/receivers/create-many

Тип: POST

Запрос:

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

Тип

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

Описание

placeId

String

Да

Уникальный идентификатор заведения

needConfirmLayouts

bool(default false)

Нет

При значение true, всегда будет создана визитка со статусом ожидания подтверждения

receivers

 

 

Список получателей

phoneNumber

String

Да

Номер получателя

name

String

Да

Имя получателя

Пример запроса:

...

externalId

String

Нет

Идентификатор сотрудника, уникальный в рамках компании

sendPassword

bool(default false)

Нет

Необходимо ли отправлять уведомление, только что зарегистрированному получателю

Пример запроса:

Code Block
{
  "placeId": "string",
  "needConfirmLayouts" : true
  "receivers": [
    {
      "phoneNumber": "string",
      "name": "string",
    }   ]
}
"externalId": "string",
      "sendPassword": true
    }
  ]
}

Ответ:

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

Тип

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

Описание

created

 

 

Созданные получатели

phoneNumber

String

Да

Телефон получателя

name

String

Да

Имя получателя

userId

String

Да

Уникальный идентификатор получателя

layoutId

String

Да

Уникальный идентификатор страниц оплаты получателя

layoutStatus

Enum

Да

Статус получателя

0 - None (Не запрашивалось подтверждение)

1 - Confirmed (Подтвреждена)

2 - WaitingForConfirmation (Ожидает подтверждения)

3 - Declined (Отклонена)

skipped

 

 

Пользователи уже есть в системе и в скоупе

phoneNumber

String

Да

Телефон получателя

name

String

Да

Имя получателя

userId

String

Да

Уникальный идентификатор получателя

layoutId

String

Да

Уникальный идентификатор страниц оплаты получателя

succeed

layoutStatus

Enum

Да

Статус получателя

succeed

String

Да

Стату запроса

errors

Array of string

Да

Возвращатеся список ошибок, относящихся целиком к запросу

validationErrors

Array of string

Да

Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

Пример ответа:

Code Block
{
  "data": {
    "created": [
      {
        "phoneNumber": "string",
        "name": "string",
        "userId": "string",
        "layoutId": "string",
        "layoutStatus": 0
      }
    ],
    "skipped": [
      {
        "phoneNumber": "string",
        "name": "string",
        "userId": "string",
        "layoutId": "string",
        "layoutStatus": 0
      }
    ]
  },
  "succeed": true,
  "errorCode": 0,
  "errors": [
    "string"
  ],
  "validationErrors": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  }
}

Если получатель не был в нашей системе уже создан и не в вашем скоупе, то создастся новая визитка. Вашему сотруднику необходимо подтвердить новую визитку в нашем личном кабинете. До этого момента вы не сможете редактировать его данные и привязывать карту для вывода чаевых.

Если получатель в нашей системе создан и в вашем скоупе, например в другом заведении, то он отобразиться в блоке skipped. Для привязки его к заведению необходимо воспользоваться методом Привязка получателя к заведению.

Если хоть один из получателей уже привязан к текущему заведению, то вернется ошибка, и ни кто не будет создан/привязан.

Загрузки фотографии получателя

Описание: Позволяет загрузить аватарку получателю

Адрес: https://api.cloudtips.ru/api/receivers/{userId}/photo, где userId уникальный идентификатор получателя в системе

Тип: POST, хедер Content-Type=multipart/form-data;
Запрос:

...

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

...

Тип

...

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

...

Описание

...

FormFile

...

file

...

Да

...

Файл с фотографией

Пример запроса:

-

Ответ:

...

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

...

Тип

...

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

...

Описание

...

photoUrl

...

String

...

Да

...

Урл загруженой аватарки

...

photoId

...

String

...

Да

...

Уникальный идентификатор загруженной аватарки

...

succeed

...

String

...

Да

...

Стату запроса

...

errors

...

Array of string

...

Да

...

Возвращатеся список ошибок, относящихся целиком к запросу

...

validationErrors

...

Array of string

...

Да

...

Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

Пример ответа:

...

, то он вернется в массиве created и layoutStatus = WaitingForConfirmation. Никаких подтверждений со стороны пользователя не требуется.

Если получателями не планируется использование личного кабинета CloudTips, то для дальнейшей работы необходимо воспользоваться методом Привязка получателя к заведению.

Если получатель уже есть в системе и в вашем скоупе, то вернется ошибка: “Некоторые номера уже в скоупе: “{номер сотрудника}””

Возможные ошибки

Expand

  • Неверный формат номера телефона

Code Block
languagejson
{
  "succeed": false,
  "errors": [],
  "validationErrors": {
    "PhoneNumber": [
      "Неверный формат телефонного номера: {тут присланный номер телефона}"
    ]
  }
}

  • не указан параметр PlaceId

Code Block
languagejson
{
  "succeed": false,
  "errors": [],
  "validationErrors": {
    "PlaceId": [
      "Необходимо указать заведение"
    ]
  }
}

  • пустой массив получателей

Code Block
languagejson
{
  "succeed": false,
  "errors": [],
  "validationErrors": {
    
"
photoUrl
Receivers":
"string",
[
      "
photold": "string" },
Необходимо указать получателей"
    ]
  }
}

  • заведение не найдено

Code Block
languagejson
{
  "succeed":
true
false,
  "errors": [Заведение {идентификатор заведения}
"string" 
не найдено],
  "validationErrors": {
"additionalProp1": [ 
}
}

  • Если получатель уже есть в системе и скоупе партнера

Code Block
languagejson
{
  "succeed": false,
  "errors": [],
  "validationErrors": {
    "
string"
PhoneNumber": [
      "Некоторые
]
из указанных номеров
}
уже
}

Удаление фотографии получателя

Описание: Позволяет удалить аватарку получателю

Адрес: https://api.cloudtips.ru/api/receivers/{userId}/photo, где userId уникальный идентификатор получателя в системе

Тип: DELETE
Запрос:

-

Пример запроса:

-

Ответ:

...

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

...

Тип

...

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

...

Описание

...

succeed

...

String

...

Да

...

Стату запроса

...

errors

...

Array of string

...

Да

...

Возвращатеся список ошибок, относящихся целиком к запросу

...

validationErrors

...

Array of string

...

Да

...

Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

Пример ответа:

Code Block
{
  "succeed": true,
  "errors": [
    "string"
  ],
  "validationErrors": {
    "additionalProp1": [
      "string"
    ]
  }
}

Редактирование данных получателя

Описание: Позволяет отредактировать данные получателя. Можно передавать одно значение из списка, а не весь список.

Адрес: https://api.cloudtips.ru/api/receivers​/{userId}, где userId уникальный идентификатор получателя в системе

Тип: PATCH

Запрос:

...

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

...

Тип

...

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

...

Описание

...

Name

...

String

...

Да

...

Имя получателя

...

Email

...

String

...

Да

...

Email получателя

Пример запроса:

Code Block
[ { "op": "replace", "path": "/Name", "value": 
в скоупе: {номера телефонов через запятую}"
    ]
  }
}

Привязка получателя к заведению

Для привязки необходимо отправить сотруднику на его номер телефона код в смс сообщении.

POST /places/{placeId}/employees/attach/send-sms

Code Block
{
  UserId: string
}

UserId берется из блока created метода Создание получателя

Интервал между отправками смс - 1 минута

После в вашем интерфейсе запросить от сотрудника передать вам код из смс.

POST /places/{placeId}/employees/attach/confirm

Code Block
{
  UserId: string,
  SmsCode: string
}

Загрузки фотографии получателя

Описание: Позволяет загрузить аватарку получателю

Адрес: https://api.cloudtips.ru/api/receivers/{userId}/photo, где userId уникальный идентификатор получателя в системе

Тип: POST, хедер Content-Type=multipart/form-data;
Запрос:

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

Тип

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

Описание

FormFile

file

Да

Файл с фотографией

Пример запроса:

-

Ответ:

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

Тип

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

Описание

photoUrl

String

Да

Урл загруженой аватарки

photoId

String

Да

Уникальный идентификатор загруженной аватарки

succeed

String

Да

Стату запроса

errors

Array of string

Да

Возвращатеся список ошибок, относящихся целиком к запросу

validationErrors

Array of string

Да

Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

Пример ответа:

Code Block
{
  "data": {
     "photoUrl": "string",
     "photold": "string"
  },
  {
"succeed": true,
   "operrors": "replace",[
    "string"
  ],
  "pathvalidationErrors": "/Email",{
    "valueadditionalProp1": [
      "string"
    ]
  }
]}

Ответ:

...

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

...

Тип

...

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

...

Описание

...

succeed

...

String

...

Да

...

Удаление фотографии получателя

Описание: Позволяет удалить аватарку получателю

Адрес: https://api.cloudtips.ru/api/receivers/{userId}/photo, где userId уникальный идентификатор получателя в системе

Тип: DELETE
Запрос:

-

Пример запроса:

-

Ответ:

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

Тип

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

Описание

succeed

String

Да

Стату запроса

errors

Array of string

Да

Возвращатеся список ошибок, относящихся целиком к запросу

validationErrors

Array of string

Да

Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

Пример ответа:

Code Block
{
  "succeed": true,
  "errors": [
    "string"
  ],
  "validationErrors": {
    "additionalProp1": [
      "string"
    ],
  }
 "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  }
}

Получение списка получателей

...

}

Редактирование данных получателя

Описание: Позволяет отредактировать данные получателя. Можно передавать одно значение из списка, а не весь список.

Адрес: https://api.cloudtips.ru/api/receivers/pages{userId}, где userId уникальный идентификатор получателя в системе

Тип: GETPATCH

Запрос:

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

Тип

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

Описание

dateFrom

Name

String

Нет

Дата и время начала поиска

dateTo

Да

Имя получателя

Email

String

Нет

Дата и время окончания поиска

phoneNumber

String

Нет

Телефонный номер получателя

name

String

Нет

Имя получателя

layoutId

String

Нет

Уникальный идентификатор страницы оплаты

placeId

String

Нет

Уникальный идентификатор заведения

type

Enum

Нет

Тип получателя

userId

Array of string

Нет

Уникальный идентификатор получателя. Можно указать несколько значений

page

Integer

Нет

Страница

limit

Integer

Нет

Ограничение на страницу

Пример запроса:

...

Да

Email получателя

Пример запроса:

Code Block
[
  {
    "op": "replace",
    "path": "/Name",
    "value":  "string"
  },
  {
    "op": "replace",
    "path": "/Email",
    "value":  "string"
   }
],
  "page": "integer",
  "limit": "integer"
}

...

Ответ:

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

Тип

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

Описание

userIdString

succeed

String

Да

Уникальный идентификатор получателя

phoneNumber

Статус запроса

errors

Array of string

Да

Номер получателя

email

String

Да

Email получателя

fullName

String

Да

Имя получателя

type

Integer

Да

Тип получателя

layouts

String

Да

Список страниц оплаты

id

String

Да

Уникальный идентификатор

layoutId

String

Да

Короткий уникальный идентификатор, используется для вызова страницы оплаты

default

Boolean

Да

Страница оплаты по умолчанию, значения true и false

disabled

Boolean

Да

Страница оплаты удалена, значения true и false

title

String

Да

Название страницы оплаты, используется только в лк получателя

description

String

Да

Описание страницы оплаты, используется на первом экране страницы оплаты

text

String

Да

Не используется

backgroundId

String

Да

Уникальный идентификатор изображения на странице оплаты

manager

String

Да

Менеджер получателя

managerId

String

Да

Уникальный идентификатор менеджера

name

String

Да

Имя менеджера

email

String

Да

Email менеджера

placeId

String

Да

Уникальный идентификатор заведения привязанного к получателю

placeName

String

Да

Название заведения

photoId

String

Да

Уникальный идентификатор аватарки получателя

photoUrl

String

Да

Ссылка на аватарку получателя

cardFirstSix

String

Да

Первые 6 цифр карты получателя

cardLastFour

String

Да

Последние 4 цифры карты получателя

cardExpDate

String

Да

Дата окончания действия карты

payoutMethod

Integer

Да

Метод выплаты чаевых получателю

lockoutEnd

String

Да

Дата окончания блокировки получателя

phoneNumberConfirmed

Boolean

Да

Подтверждение номера телефона, значения true и false

createdDate

String

Да

Дата и время создания получателя

updatedDate

String

Да

Дата и время редактирования получателя

totalCount

Integer

Да

Количество записей

succeed

String

Да

Стату запроса

errors

Array of string

Да

Возвращатеся список ошибок, относящихся целиком к запросу

validationErrors

Array of string

Да

Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

Пример ответа:

...

Возвращатеся список ошибок, относящихся целиком к запросу

validationErrors

Array of string

Да

Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

Пример ответа:

Code Block
{
  "succeed": true,
  "errors": [
    "string"
  ],
  "validationErrors": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  }
}

Редактирование данных платежной страницы

Описание: Позволяет отредактировать данные о платежной страницы.

Адрес: https://api.cloudtips.ru/api/paymentpages/{layoutId}, где layoutId идентификатор платежной страницы получателя

Тип: PATCH

Запрос:

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

Тип

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

Описание

WorkInfo.ChannelUrl

String

Да

Ссылка на канал пользователя

Пример запроса:

Code Block
languagejson
[
  {
    "op": "replace",
    "path": "/WorkInfo/ChannelUrl",
    "value":  "string"
  }
]

Ответ:

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

Тип

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

Описание

succeed

String

Да

Статус запроса

errors

Array of string

Да

Возвращатеся список ошибок, относящихся целиком к запросу

validationErrors

Array of string

Да

Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

Пример ответа:

Code Block
{
  "succeed": true,
  "errors": [
    "string"
  ],
  "validationErrors": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  }
}

Получение списка получателей

Описание: Позволяет получить список получателей

Адрес: https://api.cloudtips.ru/api/receivers

Info

Ранее используемый https://api.cloudtips.ru/api/receivers/pages также продолжает поддерживаться

Тип: GET

Запрос:

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

Тип

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

Описание

dateFrom

String

Нет

Дата и время начала поиска

dateTo

String

Нет

Дата и время окончания поиска

phoneNumber

String

Нет

Телефонный номер получателя

name

String

Нет

Имя получателя

layoutId

String

Нет

Уникальный идентификатор страницы оплаты

placeId

String

Нет

Уникальный идентификатор заведения

type

Enum

Нет

Тип получателя

userId

Array of string

Нет

Уникальный идентификатор получателя. Можно указать несколько значений

page

Integer

Нет

Страница

limit

Integer

Нет

Ограничение на страницу

Пример запроса:

Code Block
{
  "dateFrom": "string",
  "dateTo": "string",
  "phoneNumber": "string",
  "name": "string",
  "layoutId": "string",
  "placeId": "string",
  "type": "",
  "userId": [
      "string"
    ],
  "page": "integer",
  "limit": "integer"
}

Ответ:

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

Тип

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

Описание

userId

String

Да

Уникальный идентификатор получателя

phoneNumber

String

Да

Номер получателя

email

String

Да

Email получателя

fullName

String

Да

Имя получателя

type

Integer

Да

Тип получателя

layouts

String

Да

Список страниц оплаты

id

String

Да

Уникальный идентификатор

layoutId

String

Да

Короткий уникальный идентификатор, используется для вызова страницы оплаты

default

Boolean

Да

Страница оплаты по умолчанию, значения true и false

disabled

Boolean

Да

Страница оплаты удалена, значения true и false

title

String

Да

Название страницы оплаты, используется только в лк получателя

description

String

Да

Описание страницы оплаты, используется на первом экране страницы оплаты

text

String

Да

Не используется

backgroundId

String

Да

Уникальный идентификатор изображения на странице оплаты

placeId

String

Да

Уникальный идентификатор заведения привязанного к получателю

placeName

String

Да

Название заведения

externalInfo

String

Да

Идентификатор из внешней системы

manager

String

Да

Менеджер получателя

managerId

String

Да

Уникальный идентификатор менеджера

name

String

Да

Имя менеджера

email

String

Да

Email менеджера

photoId

String

Да

Уникальный идентификатор аватарки получателя

photoUrl

String

Да

Ссылка на аватарку получателя

cardFirstSix

String

Да

Первые 6 цифр карты получателя

cardLastFour

String

Да

Последние 4 цифры карты получателя

cardExpDate

String

Да

Дата окончания действия карты

payoutMethod

Integer

Да

Метод выплаты чаевых получателю

lockoutEnd

String

Да

Дата окончания блокировки получателя

phoneNumberConfirmed

Boolean

Да

Подтверждение номера телефона, значения true и false

createdDate

String

Да

Дата и время создания получателя

updatedDate

String

Да

Дата и время редактирования получателя

totalCount

Integer

Да

Количество записей

succeed

String

Да

Стату запроса

errors

Array of string

Да

Возвращатеся список ошибок, относящихся целиком к запросу

validationErrors

Array of string

Да

Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

Пример ответа:

Code Block
{  
  {
    "items": [
      {
        "userId": "string",
        "phoneNumber": "string",
        "email": "string",
        "fullName": "string",
        "type": 0,
        "layouts": [
          {
            "id": "string",
            "shortId": "string",
            "default": true,
            "disabled": true,
            "title": "string",
            "description": "string",
            "text": "string",
            "backgroundId": "string",
            "placeId": ""string",
            "placeName": "string",
            "phoneNumberuserId": "string",
            "emailexternalInfo": "string",
        "fullName": "string", }
       "type": 0],
        "layoutsmanager": [{
          {
 "managerId": "string",
          "idname": "string",
 
          "shortIdexternalId": "string",
           "email": "defaultstring":
   true,     },
        "disabledphotoId": true,
   "string",
        "titlephotoUrl": "string",
   
        "descriptioncardFirstSix": "string",
   
        "textcardLastFour": "string",
 
          "backgroundIdcardExpDate": "string",
   
        "userIdpayoutMethod": 0,
"string"        "lockoutEnd": "2021-05-27T12:37:53.822Z",
 }         ]"phoneNumberConfirmed": true,
        "managercreatedDate": {
 "2021-05-27T12:37:53.822Z",
        "managerIdupdatedDate": "string",2021-05-27T12:37:53.822Z"
      }
   "name": "string",
      ],
    "externalIdtotalCount": 0
"string",  },
  "succeed": true,
    "emailerrors": "string"[
      "string"
 },    ],
    "placeIdvalidationErrors": "string",
 {
      "placeNameadditionalProp1": "string",
[
       "photoId": "string",
        "photoUrl": "string",
 ],
      "cardFirstSixadditionalProp2": "string", [
       "cardLastFour": "string",
      ],
      "cardExpDateadditionalProp3": "string",[
        "payoutMethodstring":
0,      ]
  "lockoutEnd": "2021-05-27T12:37:53.822Z",
        "phoneNumberConfirmed": true,
        "createdDate": "2021-05-27T12:37:53.822Z",
        "updatedDate": "2021-05-27T12:37:53.822Z"
      }
    ],
    "totalCount": 0
  },}

Изменение способа вывода чаевых

Описание: Позволяет сменить способ вывода. Если у сотрудника нет карты Тинькофф банка, то для снижения комиссии сервиса рекомендуем использовать накопление для получателя. По умолчанию включено накопление. При переключении типа накопления на мгновенный производится автоматическая выплата накопления.

Адрес: https://api.cloudtips.ru/api/receivers/{userId}/payout-method, где userId - уникальный идентификатор получателя

Тип: POST

Запрос:

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

Тип

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

Описание

payoutMethod

Integer

Да

Метод выплаты чаевых получателю:

0 - мгновенный,

1 - накопление

Пример запроса:

Code Block
{
  "payoutMethod": 0
}

Ответ:

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

Тип

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

Описание

succeed

String

Да

Стату запроса

errors

Array of string

Да

Возвращатеся список ошибок, относящихся целиком к запросу

validationErrors

Array of string

Да

Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

Пример ответа:

Code Block
{
  "succeed": true,
 
  "errors": [
 
    "string"
 
  ],

   "validationErrors": {
      "additionalProp1": [
        "string"
 
    ],
      "additionalProp2": [
 
      "string"
 
    ],
 
    "additionalProp3": [
        "string"
    ]
  ]}
}

...

Отвязка получателя от менеджера

Описание: Позволяет сменить способ вывода. Если у сотрудника нет карты Тинькофф банка, то для снижения комиссии сервиса рекомендуем использовать накопление для получателя. По умолчанию включено накопление. При переключении типа накопления на мгновенный производится автоматическая выплата накопления.отвязать получателя от менеджера если получатель перестал работать в ТСП

Адрес: https://api.cloudtips.ru/api/receivers/{userId}/payoutdetach-methodagent, где userId - уникальный идентификатор получателя

Тип: POST

Запрос:

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

Тип

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

Описание

payoutMethod

userId

Integer

String

Да

Метод выплаты чаевых получателю:

0 - мгновенный,

1 - накопление

Уникальный идентификатор получателя

Пример запроса:

...

-

Ответ:

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

Тип

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

Описание

succeed

String

Да

Стату запроса

errors

Array of string

Да

Возвращатеся список ошибок, относящихся целиком к запросу

validationErrors

Array of string

Да

Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

Пример ответа:

Code Block
{
  "succeed": true,
  "statusCode": 0,
  "errors": [
    "string"
  ],
  "validationErrors": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  }
}