AndrewNovikof/Gift API.md

## Gift API.md

      
    Raw
  

              Gift API.md
            
          
    Система "Предоставление сертификатов"

Краткое описание основных понятий

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

Цена - стоимость сервиса (впоследствии стоимости сертификата) (устанавливается из личного кабинета партнера)
Заголовок - название сервиса (устанавливается из личного кабинета партнера)
Описание - любая информация о предоставляемом сервисе (устанавливается из личного кабинета партнера)
URL активации - ссылка на страницу активации сертификата в системе партнера (устанавливается из личного кабинета партнера)

Опция - настройка доступных возможностей Сервиса. Один сервис может включать любое количество опций. Каждая опция относится Только к одному партнеру. Обладает следующими параметрами:

Ключ - ключ доступа к опции (устанавливается из личного кабинета партнера)
Значение - значение опции (устанавливается из личного кабинета партнера)

Заказ - событие покупки Сертификатов. Заказ может иметь несколько сертификатов Одного сервиса. Обладает следующими изменяемыми параметрами:

ID дизайна сертификатов. (устанавливается из личного кабинета партнера)
Статус заказа - может принимать два значения "Оплаечен", "Не оплачен". (устанавливается при создании и оплате)

Сертификат - частный случай Сервиса. 12-значный номер, уникальный в системе. Обладает следующими изменяемыми параметрами:

Описание - любая подпись к сертификату: поздравление, пожелание и т.д.
Статус сертификата - может принимать два значения "Активирован", "Не активирован". (устанавливается при создании и активации)
Токен доступа - идентификатор, по которому можно посмотреть сертификат (устанавливаеися при генерации сертификата)
Сумма погашения - сумма, которую оплатили при погашении сертификата (устанавливается при активации)


REST API методы


Domain
Method
URI


POST
api/certificate/pre-activation/


POST
api/certificate/activate/


GET/POST
api/certificate/check/


POST
api/certificate/new-order/


GET/POST
api/certificate/check-order/


POST
api/certificate/upload


POST
api/certificate/intervention


###Результат обработки запроса возвращается в виде JSON cтроки.
###1. Регистрация заказа. DOMEN/api/certificate/new-order/

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


Параметр
Тип
Описание


'count'
Number
Количество сертификатов в заказе
Обязательный


'service_id'
Number
ID сервиса (смотреть в ЛК)
Обязательный


'phone'
Number
Телефон клиента (10 символов без кода страны, код страны +7 по умолчанию)
Обязательный


'email'
String
Почтовый ящик клиента
Обязательный


'api_key'
String
Ключ доступа клиента
Обязательный


'return_url'
String
Ссылка, куда будет произведен редирект после регистрации заказа
Обязательный


'design_id'
Number
ID дизайна сертификата
Обязательный


Выходные параметры - json-строка

При успешном выполнении операции:
{
    "status": "ok",
    "formUrl": "https:\/\/3dsec.sberbank.ru\/payment\/merchants\/kinohod\/payment_ru.html?mdOrder=544a8b7f-7820-4dc2-8bee-621b4906c790"
}

При возникновении ошибки валидации:
{
    "status": "error",
    "error": "Validation Errors",
    "errors": {
        "email": [ "The email field is required." ],
        "phone_lenght": [ "The phone lenght must be 11 characters." ] 
    }
}  

При возникновении ошибок со Сбербанк API:
{
    "status": "error"
    "error": "Ошибочное значение параметра запроса"
    "errors": "Доступ запрещён"
}


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

curl -XPOST 
-H "Content-Type: application/json; charset=utf-8" 
-d  "count": 1, 
    "service_id": 1,
    "phone": 9851850935,
    "email": some_email@mail.ru,
    "api_key": 446asd71d6874ads,
    "return_url": http://some_url.ru

http://DOMEN/api/certificate/new-order


#ВАЖНО
##чтобы по адресу "return_url" находился Обработчик получающий переменную orderId и отправляющий эту переменную в следующий метод:
###2. Проверка состояния и Активация заказа / Генерация сертификатов. DOMEN/api/certificate/check-order/
###Метод выполняет следующие функции:
Возвращет состояние заказа
Генерирует сертификаты
Активирует заказ как "Оплаченный"
Отправляет уведоления по SMS и на почту

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


Параметр
Тип
Описание


'orderId'
String
Номер заказа, полченный при редиректе с формы Сбербанка
Обязательный


'api_key'
String
Ключ доступа клиента
Обязательный


Выходные параметры - json-строка

При успешном выполнении операции:
{
    status: "ok",
    order_status: 2,
    description: "Проведена полная авторизация суммы заказа. Заказ оплачен"
}

При возникновении ошибки валидации:
{
    status: "error",
    error: "Validation Errors",
    errors: [
        "The order id field is required."
    ]
}

При возникновении ошибок со Сбербанк API:
{
    status: "error",
    error: "Платеж отклонен",
    order_status: 6,
    description: "Авторизация отклонена"    
}


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

curl -XPOST 
-H "Content-Type: application/json; charset=utf-8" 
-d  "orderId" : some_email@mail.ru,
    "api_key" : 446asd71d6874ads

http://DOMEN/api/certificate/check-order


3. "ПредАктивация" сертификата


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


Параметр
Тип
Описание


'certificate'
Number
Номер сертификата
Обязательный


'api_key'
String
Ключ доступа клиента
Обязательный


Выходные параметры - json-строка

При успешном выполнении операции:
{ 
	status: "ok",
    pre_activation_string: "323e444c169bfbf87e386734e088e1d5"
}

При возникновении ошибки:
{
    status: "error",
    error: "Сертификат активирован"
}   


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

curl -XPOST 
-H "Content-Type: application/json; charset=utf-8" 
-d  "certificate": 523315498453, 
    "api_key": 4f5sa4f6dfds41f3dsf,

http://DOMEN/api/certificate/pre-activation


4. Активация сертификата. DOMEN/api/certificate/activate/


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


Параметр
Тип
Описание


'certificate'
Number
Номер сертификата
Обязательный


'api_key'
String
Ключ доступа клиента
Обязательный


'sum'
Number
Cумма погашения
Обязательный


'pre_activation_string'
String
Ключ активации полученный при  ПредАктивации
Обязательный


Выходные параметры - json-строка

При успешном выполнении операции:
{ 
	"status": "ok" 
}

При возникновении ошибки:
{
	"status": "error", 
	"error": "Сертификат не найден или уже активирован"
}     


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

curl -XPOST 
-H "Content-Type: application/json; charset=utf-8" 
-d  "certificate": 523315498453, 
    "api_key": 4f5sa4f6dfds41f3dsf,
    "sum": 2500

http://DOMEN/api/certificate/activate


5. Получение информации о сертификате. DOMEN/api/certificate/check/


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


Параметр
Тип
Описание


'certificate'
Number
Номер сертификата
Обязательный


'api_key'
String
Ключ доступа клиента
Обязательный


'full'
Boolean
Все или не все данные  Разрешенные значения:  true, false, 1, 0, "1" и "0".
Обязательный


Выходные параметры - json-строка:

При успешном выполнении операции при флаге 'full', установленным в 1:
{
	"status": "ok",
	"info": {
		"status_id": 2,
		"status_name": "Активирован",
		"owner": null,
		"cost": 500,
		"activation_sum": 1500
	}
}

При успешном выполнении операции при флаге 'full', установленным в 0:
{
	"status": "ok",
	"info": {
		"status_id": 2,
		"status_name": "Активирован"
	}
}

При возникновении ошибки валидации:
{
	"status": "error",
	"error": "Validation Errors",
	"errors": [
	    "The full field is required."
    ]
}

При не соответствии Ключа/Номера сертификата/Принадлежности партнера к сертификату:
{
	"status": "error",
	"error": "not found"
}


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

https://DOMEN/api/certificate/check?certificate=566953368911&api_key=12as3456&full=1


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

curl -XPOST 
-H "Content-Type: application/json; charset=utf-8" 
-d  "certificate": 566953368911, 
    "api_key": 12as3456,
    "full": 1

http://DOMEN/api/certificate/check


6. Загрузка дизайнов. DOMEN/api/certificate/upload/


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


Параметр
Тип
Описание


'file'
image
Изображение размером не более 5мб в формате jpeg, png, bmp, gif или svg.
Обязательный


Выходные параметры - json-строка

При успешном выполнении операции:
{
    status: "ok",
    design_id: 10,
    file_url: "http://DOMEN/assets/img/widget/card-designs/da2add5ef921e681c88e22bcf51d8c70.jpg"
}

При возникновении ошибки:
{
    status: "error",
    error: "Validation Errors",
    errors: [
        "The image must be an image."
    ]
}  


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

curl -XPOST 
-H Content-Type:multipart/form-data; boundary=----WebKitFormBoundarycojxNfAIFn6vt6qn
-d ------WebKitFormBoundarycojxNfAIFn6vt6qn
   Content-Disposition: form-data; name="image"; filename="foo-bar.jpg"
   Content-Type: image/jpeg 
   ------WebKitFormBoundarycojxNfAIFn6vt6qn--


http://DOMEN/api/certificate/upload


7. Работа с загруженным изображением. DOMEN/api/certificate/intervention/


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


Параметр
Тип
Описание


'design_data'
json
{"x": Координаты верхнего левого угла по x в пикселях, "y": Координаты верхнего левого угла по y в пикселях, "width": Количество пикселей по оси х, "height": Количество пикселей по оси y, "rotate": угол поворота в градусах, "scaleX": -1 - отразить по x / 1 - не отражать, "scaleY": -1 - отразить по y / 1 - не отражать}
Обязательный


'design_id'
int
ID файла, который был загружен
Обязательный


'design_description'
string
Описание длинной не более 25 символов
Не обязательный


design_meta
json
Дополнительные данные   {"background":"#c06f8c"}
Не обязательынй


Типы дополнительных данных


Параметр
Описание
Значение по умолчанию


background
Цвет фона письма и PDF файла сертификата.
#BDBDBD


font_color
Цвет шрифта
#FFFFFF


link_color
Цвет ссылок
#FFFFFF


Выходные параметры - json-строка

При успешном выполнении операции:
{
    status: "ok",
    design_id: 10,
    file_url: "http://DOMEN/assets/img/widget/card-designs/da2add5ef921e681c88e22bcf51d8c70.jpg"
}

При возникновении ошибки:
{
    status: "error",
    error: "Validation Errors",
    errors: [
        "The image must be an image."
    ]
}  


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

curl -XPOST 
-H "Content-Type: application/json; charset=utf-8" 
-d design_id:91
   design_data[x]:14.469565217391242
   design_data[y]:0
   design_data[width]:995.0608695652176
   design_data[height]:768.0000000000001
   design_data[rotate]:0
   design_data[scaleX]:1
   design_data[scaleY]:1
   design_meta:{"background":"#c06f8c"}
   design_description:ыфвыфв

http://DOMEN/api/certificate/upload
Domain	Method	URI
	POST	api/certificate/pre-activation/
	POST	api/certificate/activate/
	GET/POST	api/certificate/check/
	POST	api/certificate/new-order/
	GET/POST	api/certificate/check-order/
	POST	api/certificate/upload
	POST	api/certificate/intervention
Параметр	Тип	Описание
'count'	Number	Количество сертификатов в заказе	Обязательный
'service_id'	Number	ID сервиса (смотреть в ЛК)	Обязательный
'phone'	Number	Телефон клиента (10 символов без кода страны, код страны +7 по умолчанию)	Обязательный
'email'	String	Почтовый ящик клиента	Обязательный
'api_key'	String	Ключ доступа клиента	Обязательный
'return_url'	String	Ссылка, куда будет произведен редирект после регистрации заказа	Обязательный
'design_id'	Number	ID дизайна сертификата	Обязательный
Параметр	Тип	Описание
'orderId'	String	Номер заказа, полченный при редиректе с формы Сбербанка	Обязательный
'api_key'	String	Ключ доступа клиента	Обязательный
Параметр	Тип	Описание
'certificate'	Number	Номер сертификата	Обязательный
'api_key'	String	Ключ доступа клиента	Обязательный
Параметр	Тип	Описание
'design_data'	json	{"x": Координаты верхнего левого угла по x в пикселях, "y": Координаты верхнего левого угла по y в пикселях, "width": Количество пикселей по оси х, "height": Количество пикселей по оси y, "rotate": угол поворота в градусах, "scaleX": -1 - отразить по x / 1 - не отражать, "scaleY": -1 - отразить по y / 1 - не отражать}	Обязательный
'design_id'	int	ID файла, который был загружен	Обязательный
'design_description'	string	Описание длинной не более 25 символов	Не обязательный
design_meta	json	Дополнительные данные {"background":"#c06f8c"}	Не обязательынй
Параметр	Описание	Значение по умолчанию
background	Цвет фона письма и PDF файла сертификата.	#BDBDBD
font_color	Цвет шрифта	#FFFFFF
link_color	Цвет ссылок	#FFFFFF