# Концепция технической интеграции безопасной сделки в ZZap

## 1. Создание и оплата

Покупатель также как сейчас отправляет заказ продавцу. После отправки заказа вы показываете покупателю кнопку с текстом вроде «Оформить безопасную сделку».

По клику на кнопку вы отправляете: id заказа, информацию о товарах, id продавца, координаты продавца, имя и телефон покупателя в наш API

POST запрос ориентировочно будет принимать следующую структуру в json:

{
    "id": строка, обязательный,
    "items": [ обязательный, не пустой
        {
            "id": строка, обязательный
            "name": строка, обязательный
            "description": строка или null
            "price": число в рублях, обязательный
            "quantity": число, обязательный
            "weight": число в килограммах, больше нуля
            "height": число в сантиметрах, больше нуля
            "width": число в сантиметрах, больше нуля
            "length": число в сантиметрах, больше нуля
        }
    ],
    "seller": { обязательный
        "id": не пустая строка, обязательный
        "name": не пустая строка, обязательный
        "phone": не пустая строка, только цифры, валидный номер телефона, обязательный
        "email": строка
    },
    "buyer": {
        "id": не пустая строка
        "name": не пустая строка, обязательный
        "phone": не пустая строка, только цифры, валидный номер телефона, обязательный
        "email": строка
    },
    "delivery": {
        "from": {
            "location": { 
                "region": строка или null
                "city": строка или null
                "address": строка или null
                "lat": число в градусах, от -90 до +90 (с юга на север, 0 - экватор)
                "lng": число в градусах, от -180 до +180 (с запада на восток, 0 - гринвич)
            }
        }
    }
}

Для определения города продавца необходимо передать в струтуру delivery.from.location координаты lat, lng. Если координаты отсутсвуют, то не будет расчитана предварительная стоимость доставки. Продавец сможет указать город отправления в интерфейсе обработки заказа.

В случае успешного ответа нужно открыть пользователю в iframe url `https://zzap.nalogka.ru/order/{id заказа}/create?s={подпись}&failed_url={адрес страницы ошибки в процессе оформления или оплаты}` (точный адрес уточним позднее), в которому покупатель увидит интерфейс вида:


Интерфейс предварительный. Вероятно что него еще будут вноситься изменения.

Пользователь выбирает город получения и пункт выдачи.

Видит предварительную стоимость доставки (в случае если нам удалось определить город отправителя), стоимость товаров, размер комиссии и сумму к оплате онлайн.

Покупатель заполняет необходимые данные и переходит на оплату прямо в iframe.

В случае успешной оплаты покупатель внутри iframe'а перенаправляется на страницу с информацией о заказе.

В случае неудачи, также внутри iframe'а, перенаправляется на служебную страницу, адрес которой был передан в failed_url. Это позволит вам обработать ситуацию по своему усмотрению: вывести текст ошибки в iframe или закрыть iframe и показать ошибку через alert.

# 2. Обработка заказа продавцом

Продавцу в интерфейсе ZZap необходимо показать iframe в которому будет открыт url `https://zzap.nalogka.ru/order/{id заказа}/processing?s={подпись}` (точный адрес уточним позднее). В этом iframe продавцу будет доступен интерфейс состоящий из трех шагов:

**1. Подтверждение**

**2. Доставка**


**3. Выплата**


## 3. Отслеживание статуса

Предполагается что будет iframe который будет выводить состояние заказа. Содержимое должно запрашиваться по адресу `https://zzap.nalogka.ru/order/{id заказа}/status?s={подпись}` (точный адрес уточним позднее).

В окне коротельно будем выводить текстом статус заказа, инфо о доставке (цена сроки, номер накладной если создан, трекинг если едет и т.п.) плюс кнопку отмены для покупателя.

В интерфейсе ZZap, там где потребуется, можно будет добавить кнопку по нажатию на которую будет открываться iframe с информацией по заказу.

## Безопасность

Аутентификация запросов будет происходить путем сравнения подписи, вычисляемой по следующему алгоритму:

1. Конкатенируем:
1.1 путь и параметры URL запроса (например /some/url?param1=1&param2=val), из списка исключаем параметр с именем s;
1.2 тело запроса (с точностью до байта, т.е. пробельные символы в начале и в конце тела имеют значение);
1.3 секрет (выдается нами и указывается у нас в конфиге приложения).
2. От полученной строки вычисляем hash по алгоритму sha256.

Подпись передается в hex-представлении в заголовке X-Nalogka-Signature (для API запросов) или в параметре запроса с именем s (для открытия страниц в браузере).

## Вебхуки

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