Получатель

1 Создание получателя
- 1.1 Возможные ошибки
2 Привязка получателя к заведению
3 Загрузки фотографии получателя
4 Удаление фотографии получателя
5 Редактирование данных получателя
6 Редактирование данных платежной страницы
7 Получение списка получателей
8 Изменение способа вывода чаевых
9 Отвязка получателя от менеджера

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

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

Адрес: 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)	Нет	Необходимо ли отправлять уведомление, только что зарегистрированному получателю

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

{
  "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	Да	Уникальный идентификатор страниц оплаты получателя
layoutStatus	Enum	Да	Статус получателя
succeed	String	Да	Стату запроса
errors	Array of string	Да	Возвращатеся список ошибок, относящихся целиком к запросу
validationErrors	Array of string	Да	Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "succeed": false,
  "errors": [],
  "validationErrors": {
    "PhoneNumber": [
      "Некоторые из указанных номеров уже в скоупе: {номера телефонов через запятую}"
    ]
  }
}

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

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

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

{
  UserId: string
}

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

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

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

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

{
  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	Да	Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

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

{
  "data": {
     "photoUrl": "string",
     "photold": "string"
  },
  "succeed": true,
  "errors": [
    "string"
  ],
  "validationErrors": {
    "additionalProp1": [
      "string"
    ]
  }
}

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

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

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

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

-

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

-

Ответ:

Наименование	Тип	Обязательность	Описание

Наименование	Тип	Обязательность	Описание
succeed	String	Да	Стату запроса
errors	Array of string	Да	Возвращатеся список ошибок, относящихся целиком к запросу
validationErrors	Array of string	Да	Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

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

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

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

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

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

Тип: PATCH

Запрос:

Наименование	Тип	Обязательность	Описание

Наименование	Тип	Обязательность	Описание
Name	String	Да	Имя получателя
Email	String	Да	Email получателя

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

[
  {
    "op": "replace",
    "path": "/Name",
    "value":  "string"
  },
  {
    "op": "replace",
    "path": "/Email",
    "value":  "string"
  }
]

Ответ:

Наименование	Тип	Обязательность	Описание

Наименование	Тип	Обязательность	Описание
succeed	String	Да	Статус запроса
errors	Array of string	Да	Возвращатеся список ошибок, относящихся целиком к запросу
validationErrors	Array of string	Да	Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

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

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

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

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

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

Тип: PATCH

Запрос:

Наименование	Тип	Обязательность	Описание

Наименование	Тип	Обязательность	Описание
WorkInfo.ChannelUrl	String	Да	Ссылка на канал пользователя

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

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

Ответ:

Наименование	Тип	Обязательность	Описание

Наименование	Тип	Обязательность	Описание
succeed	String	Да	Статус запроса
errors	Array of string	Да	Возвращатеся список ошибок, относящихся целиком к запросу
validationErrors	Array of string	Да	Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

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

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

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

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

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

Ранее используемый 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	Нет	Ограничение на страницу

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

{
  "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	Да	Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

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

{  
  {
    "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",
            "userId": "string"
            "externalInfo": "string"
          }
        ],
        "manager": {
          "managerId": "string",
          "name": "string",
          "externalId": "string",
          "email": "string"
        },
        "photoId": "string",
        "photoUrl": "string",
        "cardFirstSix": "string",
        "cardLastFour": "string",
        "cardExpDate": "string",
        "payoutMethod": 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
  },
  "succeed": true,
    "errors": [
      "string"
    ],
    "validationErrors": {
      "additionalProp1": [
        "string"
      ],
      "additionalProp2": [
        "string"
      ],
      "additionalProp3": [
        "string"
      ]
}

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

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

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

Тип: POST

Запрос:

Наименование	Тип	Обязательность	Описание

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

Тип

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

Описание

payoutMethod

Integer

Да

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

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

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

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

{
  "payoutMethod": 0
}

Ответ:

Наименование	Тип	Обязательность	Описание

Наименование	Тип	Обязательность	Описание
succeed	String	Да	Стату запроса
errors	Array of string	Да	Возвращатеся список ошибок, относящихся целиком к запросу
validationErrors	Array of string	Да	Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

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

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

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

Описание: Позволяет отвязать получателя от менеджера если получатель перестал работать в ТСП

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

Тип: POST

Запрос:

Наименование	Тип	Обязательность	Описание

Наименование	Тип	Обязательность	Описание
userId	String	Да	Уникальный идентификатор получателя

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

-

Ответ:

Наименование	Тип	Обязательность	Описание

Наименование	Тип	Обязательность	Описание
succeed	String	Да	Стату запроса
errors	Array of string	Да	Возвращатеся список ошибок, относящихся целиком к запросу
validationErrors	Array of string	Да	Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

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

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

CloudTips API

Получатель

Analytics

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

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

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

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

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

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

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

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

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

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

Related content