Дата последней модификации страницы: 08.12.2022

В документе приведено API портала 1С:ИТС для взаимодействия с инстансом сервиса Фреш. Более подробное описание возможностей интеграции – https://fresh-integration.1c.ru/api/swagger-ui.html

Содержание

1. Тарифы

1.1. Метод получения информации о доступных тарифах ИТС для инстанса сервиса Фреш

Описание

Метод, возвращающий информацию о доступных тарифах портала 1С:ИТС для конкретного инстанса Фреш.

Классификатор тарифов портала 1С:ИТС передается в инстанс сервиса Фреш для того, чтобы тарифы из этого классификатора включать в тарифы сервиса Фреш. Т.е. партнер, продавая тариф сервиса Фреш, может сразу «заложить» в нем стоимость тарифа портала 1С:ИТС. Для абонента это будет выглядеть как покупка единого тарифа, содержащего в себе и услуги партнера, и сервисы портала 1С:ИТС. При продаже тарифа сервиса Фреш данные о содержащемся в нем тарифе портала 1С:ИТС должны быть переданы на портал через специальный программный интерфейс.

Входные параметры

  • freshInstanceGuid – guid инстанса сервиса Фреш

Способ вызова

  • GET {basePath}/freshInstance/{freshInstanceGuid}/tariffs

Пример запроса
GET {basePath}/freshInstance/f0ff2f3b-9149-49b0-bbd0-ce812efb4365/tariffs/
Пример ответа
{
  "tariffs": [
    {
      "guid": "9b50604d-7747-48ef-ac65-76dbcbb39bc5",
      "name": "1C:ИТС Аренда",
      "free" : true,
      "monthCounts": [3, 6, 12],
      "dayCounts" : [1, 2, 3],
      "optionTypes": [
        {
          "guid": "0b6d3008-8482-4a6f-b0be-c1e1a5f0a412",
          "name": "Обмен электронными документами",
          "nick": "1c-buh-phone-license-unlimited-service",
          "service": {
            "guid": "b4bfea69-c0ae-4fdd-a7a0-2882e96aa162",
            "name": "https://1cbn.ru"
          }
        },
        {
          "guid": "7d2f4726-9d27-427e-9d3e-307db44ad985",
          "name": "Получение обновлений прикладных решений",
          "nick": "1c-buh-phone-license-unlimited-service",
          "service": {
            "guid": "9a81b026-eac7-40ac-a774-da62d32a3c97",
            "name": "1С:Обновление программ"
          }
        }
      ]
    }
  ]
}

Успех

  • 200 – информация о доступных тарифах портала 1С:ИТС для инстанса сервиса Фреш

Ошибки

  • 500 – ошибка на сервере. Информация об ошибке в текстовом виде содержится в возвращаемом объекте в поле text.
  • 401 – необходима авторизация
  • 404 – такой инстанс сервиса Фреш не найден

2. Абоненты

2.1. Метод добавления информации по абоненту

Описание

Метод для добавления нового абонента в систему портала 1С:ИТС.

Входные параметры

  • guid – идентификатор абонента
  • name – название абонента

Способ вызова

  • POST {basePath}/subscribers/

Пример запроса
POST {basePath}/subscribers/

{
  "guid": "f0ff2f3b-9149-49b0-bbd0-ce812efb4365",
  "name": "Название абонента
}

Успех

  • 201 – абонент успешно создан в системе

Ошибки

  • 500 – ошибка на сервере
  • 401 – необходима авторизация
  • 422 – некорректный набор параметров (дополнительная информация в response)

Пример результата в случае ошибки 422
{
  "text": "Поле, содержащее название абонента, не должно быть пустым"
}

2.2. Метод изменения информации по абоненту

Описание

Метод для изменения информации по абоненту.

Входные параметры

  • guid – идентификатор абонента
  • name – название абонента

Способ вызова

  • PUT {basePath}/subscribers/{guid}

Пример запроса
PUT {basePath}/subscribers/f0ff2f3b-9149-49b0-bbd0-ce812efb43653

{
   "guid" :  "f0ff2f3b-9149-49b0-bbd0-ce812efb4365" ,
   "name" :  "Новое название абонента"
}

Успех

  • 200 – информация об абоненте успешно обновлена

Ошибки

  • 422 – некорректный набор параметров (дополнительная информация в response)
  • 401 – необходима авторизация
  • 403 – абонент не принадлежит инстансу сервиса Фреш. Операция невозможна
  • 404 – абонент не найден на сервере
  • 500 – ошибка на сервере. Информация об ошибке в текстовом виде содержится в возвращаемом объекте в поле text.

Пример результата, в случае ошибки 404
{
   "text" : "Абонент с guid f0ff2f3b-9149-49b0-bbd0-ce812efb4365 не найден в системе"
}

2.3. Метод удаления информации об абоненте

Описание

Метод для удаления информации об абоненте.

Входные параметры

  • guid – идентификатор абонента

Способ вызова

  • DELETE {basePath}/subscribers/{guid}

Пример
DELETE {basePath}/subscribers/f0ff2f3b-9149-49b0-bbd0-ce812efb4365

Успех

  • 204 – информация об абоненте успешно удалена

Ошибки

  • 500 – ошибка на сервере
  • 401 – необходима авторизация
  • 404 – абонент не найден на сервере
  • 403 – абонент не принадлежит вашему инстансу сервиса Фреш. Операция невозможна

Пример результата, в случае ошибки 404
{
  "text" :  "Абонент с guid f0ff2f3b-9149-49b0-bbd0-ce812efb4365 не найден в системе"
}

3. Пользователи абонентов

3.1. Метод добавления информации по пользователю абонента

Описание

Метод отвечает за добавление информации по пользователю абонента.

Если по ходу работы инстанс сервиса Фреш добавляет информацию по пользователю, то он должен оповестить об этом портал 1С:ИТС.

Входные параметры

  • guid – идентификатор пользователя сервиса
  • login – логин пользователя сервиса
  • role – роль пользователя:
    • User – пользователь абонента
    • SubscriberOwner – владелец абонента
  • subscriber_guid – идентификатор абонента
  • email – адрес электронной почты пользователя
  • fullName – полное имя пользователя, для отображения
    • firstName – имя
    • lastName – фамилия (не обязательно)
    • middleName – отчество (не обязательно)

Способ вызова

  • POST {basePath}/subscribers/{subscriber_guid}/users/

Пример запроса
POST {basePath}/subscribers/be0adc4f-a691-486b-9a49-a674e8d9f494/users/,

{
  "guid": "9dd94c9d-3d3c-4e77-85ac-53c5175164fc",
  "login": "subscriberUserLogin",
  "role": "User",
  "email": " subscriberUser@yopmail.com",
  "fullName": {
    "firstName": "Mikhail",
    "lastName": "Popov"}
}

Успех

  • 201 – пользователь абонента успешно создан в системе

Ошибки

  • 500 – ошибка на сервере
  • 401 – необходима авторизация
  • 422 – некорректный набор параметров (дополнительная информация в response)
  • 404 – абонент, для которого добавляется пользователь, не найден в системе

Пример результата в случае ошибки 422
{
   "text" :  "Поле, содержащее guid пользователя абонента не должно быть пустым"
}

3.2. Метод изменения информации по пользователю абонента

Описание

Метод отвечает за изменение информации по пользователю абонента.

Если по ходу работы инстанс  сервиса Фреш изменяет какую-либо информацию по пользователю, то он должен оповестить об этом портал 1С:ИТС.

Входные параметры

  • guid – идентификатор пользователя абонента
  • login – логин пользователя абонента
  • role – роль пользователя:
    • User – пользователь абонента 
    • SubscriberOwner – владелец абонента
  • subscriber_guid – идентификатор абонента
  • email – адрес электронной почты пользователя
  • fullName – полное имя пользователя, для отображения
    • firstName – имя
    • lastName – фамилия (не обязательно)
    • middleName – отчество (не обязательно)

Способ вызова

  • PUT {basePath}/subscribers/{subscriber_guid}/users/{guid}

Пример запроса
PUT {basePath}/subscribers/be0adc4f-a691-486b-9a49-a674e8d9f494/users/9dd94c9d-3d3c-4e77-85ac-53c5175164fc

{
  "guid": "9dd94c9d-3d3c-4e77-85ac-53c5175164fc",
  "login": "subscriberUserLogin",
  "role": "User",
  "email": " subscriberUser@yopmail.com",
  "fullName": {
    "firstName": "Mikhail",
    "lastName": "Popov"
  }
}

Успех

  • 200 – пользователь абонента успешно обновлён в системе

Ошибки

  • 500 – ошибка на сервере
  • 401 – необходима авторизация
  • 422 – некорректный набор параметров (дополнительная информация в response)
  • 404 – ресурс не найден в системе (дополнительная информация в response)

Пример результата в случае ошибки 404, если не найден пользователь
{
   "text" : "Пользователь абонента с guid 9dd94c9d-3d3c-4e77-85ac-53c5175164fc не найден для абонента be0adc4f-a691-486b-9a49-a674e8d9f494"
}

3.3. Метод удаления информации по пользователю абонента

Описание

Метод отвечает за удаление информации по пользователю абонента.

Если по ходу работы инстанс сервиса Фреш удаляет пользователя абонента, то он должен оповестить об этом портал 1С:ИТС.

Входные параметры

  • guid – идентификатор пользователя абонента
  • subscriber_guid – идентификатор абонента

Способ вызова

  • DELETE {basePath}/subscribers/{subscriber_guid}/users/{guid}

Пример запроса
DELETE {basePath}/subscribers/be0adc4f-a691-486b-9a49-a674e8d9f494/users/9dd94c9d-3d3c-4e77-85ac-53c5175164fc

Успех

  • 204 – пользователь абонента успешно удалён в системе

Ошибки

  • 500 – ошибка на сервере
  • 401 – необходима авторизация
  • 422 – некорректный набор параметров (дополнительная информация в response)
  • 404 – ресурс не найден (дополнительная информация в response)

Пример результата в случае ошибки 404
{
  "text" :  "Абонент с guid 9dd94c9d-3d3c-4e77-85ac-53c5175164fc не найден для абонента be0adc4f-a691-486b-9a49-a674e8d9f494"
}

4. Подписки на тарифы

4.1. Метод оформления покупки тарифов

Описание

Метод, через который осуществляется оформление покупки тарифа портала 1С:ИТС инстансом сервиса Фреш.

Входные параметры

  • subscriberGuid – идентификатор абонента 
  • partnerСode – код партнёрской организации
  • tariffPurchaseGuid – идентификатор подписки (генерируется на стороне сервиса Фреш)
  • number – номер подписки на тариф
  • startDate – дата начала действия тарифов в заявке
  • period – величина периода на которых оформляются тарифы (целое число)
  • periodType – тип периода {DAYS, MONTHS}
  • firmName – наименование фирмы
  • inn – ИНН. Для России поле обязательно, правильность проверяется по алгоритму. Для Украины и Казахстана проверяется только факт заполнения. Если клиент физическое лицо и у него нет ИНН, используется "заглушка" вида "Ф" + регистрационный номер
  • kpp – КПП. Только для российских юридических лиц
  • responsible – ответственный
  • city – город (не обязательно)
  • areaCode – телефонный код города (не обязательно)
  • phone – телефон
  • email – электронная почта
  • version – версия объекта (техническое поле)
  • itsTariffListInfo – информация о тарифах ИТС
  • tariffGuid – идентификатор тарифа

Способ вызова

  • POST {basePath}/subscribers/{subscriberGuid}/tariffsPurchases/

Пример запроса
POST {basePath}/subscribers/9dd94c9d-3d3c-4e77-85ac-53c5175164fc/tariffsPurchases/

{
  "tariffPurchaseGuid": "f0ff2f3b-9149-49b0-bbd0-ce812efb4365",
  "partnerCode": 234901,
  "number": "TP-123435",
  "startDate": "10.10.2016",
  "period": 6,
  "periodType" : "MONTHS",
  "legalEntity": {
    "firmName": "Наименование фирмы",
    "inn": 5702001741,
    "kpp": 525601001
  },
  "responsible": "Ответственный",
  "phone": "8-800-000-00-00",
  "email": "example@domain.com",
  "itsTariffListInfo": [
    {"tariffGuid": "a650f6a7-2313-4f85-b8ff-809bc1dc79bb"},
    {"tariffGuid": "43cb2fb7-4f35-4e2d-9853-0d93abe0f976"}
  ]
}

Успех

  • 201 – оформление покупки успешно совершено. Пока не получен данный код, действие не может считаться завершённым на стороне сервиса Фреш.
  • 202 – запрос на оформление покупки тарифа принят. Возвращается в случае, если портал 1С:ИТС успешно принял запрос, но потенциально по каким-то причинам нам может понадобиться время на его обработку. При таком коде предполагается повторный запрос со стороны сервиса Фреш.

Ошибки

  • 500 – ошибка при оформлении покупки тарифа. Информация об ошибке в текстовом виде содержится в возвращаемом объекте в поле text.
  • 401 – Необходима авторизация
  • 404 – абонент с таким идентификатором не найден
  • 422 – переданы некорректные данные (информация в сообщении)

Пример результата в случае ошибки 404
{
  "text": "Абонент с идентификатором 9dd94c9d-3d3c-4e77-85ac-53c5175164fc не найден в системе"
}

4.2. Метод изменения информации о покупке тарифов

Описание

Метод, через который осуществляется изменения информации о покупке тарифа портала 1С:ИТС в инстансе сервиса Фреш.

Входные параметры

  • Аналогично покупке

Способ вызова

  • PUT {basePath}/subscribers/{subscriberGuid}/tariffsPurchases/{tariffPurchaseGuid}

Пример запроса
PUT {basePath}/subscribers/9dd94c9d-3d3c-4e77-85ac-53c5175164fc/tariffsPurchases/f0ff2f3b-9149-49b0-bbd0-ce812efb4365

{
  "tariffPurchaseGuid": "f0ff2f3b-9149-49b0-bbd0-ce812efb4365",
  "partnerCode": 234901,
  "number": "TP-123435",
  "startDate": "10.10.2016",
  "period": 6,
  "periodType" : "MONTHS",
  "legalEntity": {
    "firmName": "Наименование фирмы",
    "inn": 5702001741,
    "kpp": 525601001
  },
  "responsible": "Ответственный",
  "phone": "8-800-000-00-00",
  "email": "example@domain.com",
  "itsTariffListInfo": [
    {"tariffGuid": "a650f6a7-2313-4f85-b8ff-809bc1dc79bb"},
    {"tariffGuid": "43cb2fb7-4f35-4e2d-9853-0d93abe0f976"}
  ]
}

4.3. Метод удаления информации о покупке тарифов

Описание

Метод, через который осуществляется удаление информации о покупке тарифа портала 1С:ИТС в инстансе сервиса Фреш.

Входные параметры

  • subscriberGuid – идентификатор абонента
  • tariffPurchaseGuid- идентификатор подписки, который сгенерируется на стороне сервиса Фреш

Способ вызова

  • DELETE {basePath}/subscribers/{subscriberGuid}/tariffsPurchases/{tariffPurchaseGuid}

Пример запроса
DELETE {basePath}/subscribers/9dd94c9d-3d3c-4e77-85ac-53c5175164fc/tariffsPurchases/f0ff2f3b-9149-49b0-bbd0-ce812efb4365

Успех

  • 204 – информация о покупке тарифов ИТС успешно удалена

Ошибки

  • 500 – ошибка на сервере
  • 401 – Необходима авторизация
  • 404 – ресурс не найден (дополнительная информация в сообщении)

Пример результата в случае ошибки 404
{
  "text": "Абонент с идентификатором 9dd94c9d-3d3c-4e77-85ac-53c5175164fc не найден в системе"
}

Успех

  • 200 – изменение информации о покупке тарифов успешно совершено

Ошибки

  • 500 – ошибка на сервере
  • 401 – Необходима авторизация
  • 404 – ресурс не найден (дополнительная информация в сообщении)
  • 422 – переданы некорректные данные (информация в сообщении)

Пример результата в случае ошибки 422
{
  "text": "Информация о покупке f0ff2f3b-9149-49b0-bbd0-ce812efb4365 не найдена"
}

5. Получение тикета

5.1. Метод получения тикета

Описание

Метод возвращает тикет пользователя, с которым приложение в сервисе Фреш будет обращаться к порталу 1С:ИТС.

Входные параметры

  • subscriberGuid – идентификатор абонента (обязательное поле)
  • userGuid – идентификатор пользователя
  • openUrl – URL, на который необходимо осуществить переход для проверки тикета на Портале 1С:ИТС (опциональное поле)

Результат

  • userTicket – тикет аутентификации для пользователя

Способ вызова

  • POST {basePath}/auth/tickets/

Пример запроса
POST {basePath}/auth/tickets/

{
  "userGuid": "f0ff2f3b-9149-49b0-bbd0-ce812efb4365",
  "subscriberGuid": "9bc4fc06-7c81-4813-a14d-526ee7cce954",
  "openUrl": "https://1cfresh.com"}
}

Успех

  • 201 – тикет успешно сгенерирован

Пример результата в случае успеха
{
  "userTicket": "ab4749ca-9c6d-4c3b-8cfa-e4c746be0f54"
}

Ошибки

  • 500 – ошибка на сервере
  • 422 – некорректный набор параметров (дополнительная информация в response)
  • 401 – необходима авторизация
  • 403 – такой инстанс сервиса Фреш не зарегистрирован или не имеет доступа к данной операции
  • 404 – пользователь с таким guid не найден в системе

Пример результата в случае ошибки 404
{
  "text": "Пользователь с guid f0ff2f3b-9149-49b0-bbd0-ce812efb4365 не найден в системе"
}

6. Проверки со стороны Портала 1С:ИТС

На каждый запрос идет проверка по логину и паролю от конкретного экземпляра сервиса Фреш.

Объект

Валидация запроса

Проверки

Создание

ИзменениеУдаление

Абонент

Заполнены:

  • guid
  • name
  • code
  1. Такого абонента ещё нет
  1. Идентификатор из URL соответствует идентификатору внутри тела запроса
  2. Такой абонент существует
  3. Абонент принадлежит экземпляру сервиса Фреш под которым совершают запрос
  1. Такой абонент существует
  2. Абонент принадлежит экземпляру сервиса Фреш под которым совершают запрос

Пользователь

Заполнены:

  • guid
  • login
  • role
  • fullName
  • firstName
  1. Такой абонент существует
  2. Логин пользователя уникальный
  3. Такой пользователя ещё не привязан к этому абоненту
  1. Идентификатор из URL соответствует идентификатору внутри тела запроса
  2. Такой абонент существует
  3. Такой пользователь существует
  4. Пользователь принадлежит абоненту из запроса
  1. Такой абонент существует
  2. Такой пользователь существует
  3. Пользователь принадлежит абоненту из запроса

Заявка на покупку тарифа

Заполнены:

  • tariffPurchaseGuid
  • partnerCode : минимум 1
  • number
  • registrationDate
  • legalEntity
    • firmName
    • inn : 10 или 12 цифр
    • kpp : 9 цифр 
  • responsible
  • phone
  • email : формат email
  • startDate
  • monthCount: минимум 1
  • version
  • itsTariffListInfo
  • tariffGuid
  1. Такой абонент из запроса существует
  2. Абонент принадлежит экземпляру сервиса Фреш под которым совершается действие
  3. Такой заявки не существует
  4. Тарифов из заявки на соответствие разрешённому количеству месяцев
  1. Такой абонент из запроса существует
  2. Такая заявка существует
  3. Абонент принадлежит экземпляру сервиса Фреш под которым совершается действие
  4. Заявку можно изменять(была успешно создана, была успешно обновлена, была ошибка обновления, была ошибка удаления)
  5. Все тарифы из заявки соответствуют разрешённому количеству месяцев
  6. Заявка принадлежит абоненту из запроса
  7. Не изменился набор тарифов в заявке
  1. Такой абонент из запроса существует
  2. Такая заявка существует
  3. Абонент принадлежит экземпляру сервиса Фреш под которым совершается действие
  4. Заявку можно удалять(была успешно создана, была успешно обновлена, была ошибка обновления, была ошибка удаления) 
  5. Заявка принадлежит абоненту из запроса