Примеры схем интеграции партнеров

1 Схема интеграции партнеров с одним заведением
2 Схема интеграции для множества заведений

Схема интеграции партнеров с одним заведением

Схема взаимодействия при интеграции с одним заведением

Описание шагов:

Партнер отправляет запрос на создание необходимых пользователей в заведении
В ответ получает информацию по созданным пользователям
Партнеру необходимо провалидировать полученную информацию из п.2 на корректность
Для получения платежной ссылки партнер отправляет запрос с необходимыми параметрами
Платежная ссылка создается и передается для использования партнеру
Партнер валидирует ответ из п.5

Добавление получателей

Для добавления получателей вызывается запрос (с авторизацией)

Адрес: api/receivers/create-many

Тип: POST

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

{
  "placeId": "string",
  "externalInfo": {
    "companyId": "string"
  },
  "receivers": [
    {
      "phoneNumber": "string",
      "name": "string",
      "externalId": "string"
    }
  ]
}

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

Наименование	Тип	Обязательность	Описание
placeId	string	да	идентификатор заведения, выданный CloudTips
externalInfo.CompanyId	string	да	идентификатор компании, выданный CloudTips
receivers	array	да	массив получателей чаевых для создания
receivers[].PhoneNumber	string	да	номер телефона получателя
receivers[].externalId	string	да	идентификатор получателя в системе партнера
receivers[].name	string	нет	имя получателя

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

{
  "succeed": true,
  "errors": [
    "string"
  ],
  "validationErrors": {
    "additionalProp1": [
      "string"
    ]
  },
  "data": {
    "created": [
      {
        "phoneNumber": "string",
        "name": "string",
        "userId": "string",
        "layoutId": "string"
      }
    ],
    "skipped": [
      {
        "phoneNumber": "string",
        "name": "string",
        "userId": "string",
        "layoutId": "string"
      }
    ]
  }
}

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

Наименование	Тип	Обязательность	Описание
created	array	да	массив созданных получателей
created[].phoneNumber	string	да	номер телефона получателя
created[].name	string	да	имя получателя
created[].userId	string	да	идентификатор получателя в CloudTips
created[].layoutId	string	да	идентификатор платежной ссылки в CloudTips
skipped	array	да	массив получателей, которые уже были созданы
created[].phoneNumber	string	да	номер телефона получателя
created[].name	string	да	имя получателя
created[].userId	string	да	идентификатор получателя в CloudTips
created[].layoutId	string	да	идентификатор платежной ссылки в CloudTips
succeed	String	Да	Стату запроса
errors	Array of string	Да	Возвращатеся список ошибок, относящихся целиком к запросу
validationErrors	Array of string	Да	Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

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

Для того, чтобы получить ссылку, по которой будет происходить оплата, необходимо вызвать запрос (доступен без авторизации):

Адрес: api/paymentpages/external/{companyCode}/{placeExternalId}/{receiverExternalId}

Тип: GET

Поля запроса:

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

Наименование	Тип	Обязательность	Описание
companyCode	string	да	идентификатор компании, выданный CloudTips
placeExternalId	string	да	идентификатор заведения, выданный CloudTips
receiverExternalId	string	да	идентификатор получателя в системе партнера

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

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

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

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

Схема интеграции для множества заведений

Схема взаимодействия при интеграции множества заведений

Описание шагов:

Партнер отправляет запрос на создание необходимых пользователей в заведении
В ответ получает информацию по созданным пользователям
Партнеру необходимо провалидировать полученную информацию из п.2 на корректность
Если в п.3 валидация проходит корректно, партнер отправляет запрос на синхронизацию сотрудников
Партнер получает ответ от запроса синхронизации
Партнер валидирует ответ из п.5
Для получения платежной ссылки партнер отправляет запрос с необходимыми параметрами
Платежная ссылка создается и передается для использования партнеру
Партнер валидирует ответ из п.8

Добавление получателей

Для добавления получателей вызывается запрос (с авторизацией)

Адрес: api/receivers/create-many

Тип: POST

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

{
  "placeId": "string",
  "externalInfo": {
    "companyId": "string"
  },
  "receivers": [
    {
      "phoneNumber": "string",
      "name": "string",
      "externalId": "string"
    }
  ]
}

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

Наименование	Тип	Обязательность	Описание
placeId	string	да	идентификатор заведения, выданный CloudTips
externalInfo.CompanyId	string	да	идентификатор компании, выданный CloudTips
receivers	array	да	массив получателей чаевых для создания
receivers[].PhoneNumber	string	да	номер телефона получателя
receivers[].externalId	string	да	идентификатор получателя в системе партнера
receivers[].name	string	нет	имя получателя

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

{
  "succeed": true,
  "errors": [
    "string"
  ],
  "validationErrors": {
    "additionalProp1": [
      "string"
    ]
  },
  "data": {
    "created": [
      {
        "phoneNumber": "string",
        "name": "string",
        "userId": "string",
        "layoutId": "string"
      }
    ],
    "skipped": [
      {
        "phoneNumber": "string",
        "name": "string",
        "userId": "string",
        "layoutId": "string"
      }
    ]
  }
}

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

Наименование	Тип	Обязательность	Описание
created	array	да	массив созданных получателей
created[].phoneNumber	string	да	номер телефона получателя
created[].name	string	да	имя получателя
created[].userId	string	да	идентификатор получателя в CloudTips
created[].layoutId	string	да	идентификатор платежной ссылки в CloudTips
skipped	array	да	массив получателей, которые уже были созданы
created[].phoneNumber	string	да	номер телефона получателя
created[].name	string	да	имя получателя
created[].userId	string	да	идентификатор получателя в CloudTips
created[].layoutId	string	да	идентификатор платежной ссылки в CloudTips
succeed	String	Да	Стату запроса
errors	Array of string	Да	Возвращатеся список ошибок, относящихся целиком к запросу
validationErrors	Array of string	Да	Поле представлено в формате ключ-значение и содержит ошибки, которые отнести к конкретному полю запроса

Синхронизация сотрудников в заведениях

Для синхронизации заведений и получателей, необходимо использовать запрос (с авторизацией)

Что делает данный роут:

создает заведение, если оно ранее не было создано
актуализирует в заведении получателей по ExternalId

Адрес: api/places/sync

Тип: POST

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

{
  "companyId": "string",
  "places": [
    {
      "externalId": "string",
      "placeName": "string",
      "employeeExternalInfos": [
        {
          "externalId": "string"
        }
      ]
    }
  ]
}

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

Наименование	Тип	Обязательность	Описание
companyId	string	да	идентификатор компании, выданный CloudTips
places	array	да	массив заведений и сотрудников
places[].externalId	string	да	идентификатор заведения в системе партнера
places[].placeName	string	да	имя заведения (должно быть уникально)
places[].employeeExternalInfo	array	да	массив сотрудников заведения
places[].employeeExternalInfo[].externalId	string	да	идентификатор сотрудника в системе партнера

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

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

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

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

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

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

Адрес: api/paymentpages/external/{companyCode}/{placeExternalId}/{receiverExternalId}

Тип: GET

Поля запроса:

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

Наименование	Тип	Обязательность	Описание
companyCode	string	да	идентификатор компании, выданный CloudTips
placeExternalId	string	да	идентификатор заведения, выданный CloudTips
receiverExternalId	string	да	идентификатор получателя в системе партнера

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

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

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

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

CloudTips API

Примеры схем интеграции партнеров

Analytics

Схема интеграции партнеров с одним заведением

Схема взаимодействия при интеграции с одним заведением

Добавление получателей

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

Схема интеграции для множества заведений

Схема взаимодействия при интеграции множества заведений

Добавление получателей

Синхронизация сотрудников в заведениях

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

Related content