API сторонних товаров

API используется для передачи информации о заказах между Discountomat и системой торгового партнера. API требует реализации двусторонней коммуникации – API партнера вызывается системой Discount, а партнер вызывает API Discount.

С заказами, экспортированными в API партнера, больше невозможно манипулировать в интерфейсе партнера, только просматривать. Манипулирование экспортированными заказами может осуществляться только через API.

Все запросы должны быть сделаны по протоколу HTTPS, а все данные должны быть в формате JSON.

API-доступность

Вы можете получить доступ к API из вкладки «Настройки» в вашем интерфейсе партнера. Для получения данных вам необходимо ввести корневой код URL партнерской части API для использования в направлении Zlevomat → Партнер, например

https://example.com/slevomat-zbozi-api

Данные доступа будут отображаться только при обращении к API, внимательно прочтите и сохраните их.

После доступа к API система вводит в него вновь созданные заказы и начинает экспортировать заказы в систему.

Первоначальный экспорт данных

Для переполнения существующих заказов на момент предоставления API можно использовать однократный экспорт в CSV в партнерском интерфейсе.

В тот момент, когда у вас в собственной системе есть существующие заказы (созданные до доступа к API) и вы хотите начать работать с ними через API, воспользуйтесь функцией «Начать работу с отмеченными заказами через API» в меню «Массовые действия с заказами».

Описание распространенных HTTP-ответов

• 200 OK – запрос успешно обработан
• 204 No Content – запрос успешно обработан, ответ не имеет содержания
• 400 Bad Request – запрос недействителен – могут отсутствовать или быть указаны недопустимые параметры по сравнению со спецификацией
• 403 Forbidden – авторизация клиента не удалась
• 404 Not Found – конечная точка или запрошенные данные не найдены
• 405 Method Not Allowed – конечная точка не поддерживает этот метод протокола HTTP
• 422 Unprocessable Entity – ожидаемая ошибка при обработке запроса (см. раздел Состояния ошибок )
• 500 Internal Server Error – произошла ошибка на сервере страницы
• 502 Bad Gateway – произошла ошибка на стороне сервера
• 503 Service Unavailable – сервер находится в режиме обслуживания (возможно, происходит развертывание новой версии или запланированный простой)
• 504 Gateway Timeout – произошла ошибка на стороне сервера

Ответы HTTP 5×x не могут использовать формат JSON.

В случае4xx ошибки, ошибка в исходящем запросе, и ее необходимо исправить перед повторной попыткой.

Ошибки5xx указывают на ошибки сервера и запрос может быть повторен без его изменения. В случае503 , звонящий должен уважатьRetry-After заголовок ответа и следующая попытка повторится только по истечении времени, указанного в заголовке.

Порядок состояний

Заказ всегда находится в одном из следующих состояний:

Клиент информируется о любых изменениях статуса по электронной почте.

Заказ не обязательно должен пройти все статусы для успешной доставки, можно перейти сразу из статуса «Новый оплаченный заказ» в статус «В пути»/«Готов к выдаче», а затем в статус «Доставлен клиенту — ожидает подтверждения клиента». Использование всех статусов, однако, приводит к лучшему информированию клиента о ходе обработки заказа, и мы рекомендуем это.

Состояния ошибок

В случае HTTP-кодов 4×x ответ всегда содержит ключstatus (см. список кодов ниже) и полеmessages с текстовыми описаниями ошибок.

Пример:

{ "status": 3, "messages": [ "Order #1234 was not found." ] }

Типы данных

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

Связь Discountomat ⇒ Партнер

Эта часть API реализована на стороне партнера и используется вызовами Zlevomat.

Требуемый корневой URL-адрес API предоставляется партнером и должен иметь вид

https://www.example.com/slevomat-zbozi-api/v1

Запросить авторизацию

Когда API включен, партнер получаетpartner_api_se­cret , в результате чего входящие запросы проверяются на предмет того, что они действительно исходят от Discount.

Этот параметр передается в заголовке HTTP.X-PartnerApiSecret .

Тестовый интерфейс

Discountomat включает в себя функционал для вызова API на стороне партнера и отображения ответа. На корневой URL, указанный партнером при доступе к API-test прикрепляется к URL-адресу партнера, поэтому при тестировании он называется API, например

https://example.com/slevomat-zbozi-api-test

чтобы избежать смешивания тестовых данных с реальными заказами.

Тестирование API партнера осуществляется с помощью POST-запросов на следующие адреса:

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/new-order

   – Новый заказ

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/update-shipping-dates

   – Массовое обновление ожидаемых дат отгрузки

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/mark-delivered

   – Измените статус заказа на «Доставлено клиенту — ожидается подтверждение от клиента»

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/ready-for-pickup

   – Измените статус заказа на «Готово к личному самовывозу»

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/confirm-delivery 

   – Подтверждение доставки

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/reject-delivery

   – Отказ в принятии

• https://www.zlavomat.sk/test-zbozi-partner-api/v1/order/<orderId>/cancel

   – Отмена

Заменить<orderId> часть URL с любым номером заказа, с этим номером заказа запросы передаются API-партнеру.

Запросы к этому тестовому интерфейсу должны быть авторизованы с помощью заголовковX-PartnerToken иX-ApiSecret .

При выполнении тестового вызова API партнера система отправляет заголовокX-PartnerApiSecret заголовок так же, как и в реальной эксплуатации.

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

В случае отправки отмены заказа, тело POST-запроса включите в поле JSONitems (в том же формате, что и отправленный API), который будет проверен интерфейсом тестирования и отправлен в API-партнер. API перешлет его в том же формате.

Новый заказ

Запрос содержит данные вновь созданного заказа.

Заказы всегда имеют уникальныйzlavomatId . Если API дубликатzlavomatId прибывает, запрос следует проигнорировать (первый преобразованный запрос был оценен Discountomat как неудачный, поэтому мы повторяем его) и также ответить HTTP 204.

created это дата в формате ISO 8601, поэтомуYYYY-MM-DD'T'HH:mm:ss­+zz:zz .

productId содержит идентификатор события, variantId идентификатор купленного варианта.

НеобязательныйinternalId обозначает внутренний идентификатор, введенный при варианте действия, когда он создается в интерфейсе партнера. Служит для идентификации продукта в системе партнера.

ВbillingAddress (адрес для выставления счета) обязательно только имя (name ) заказчика.

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

Ключdelivery .type может принимать значенияaddress (доставка по адресу) илиpickup (личная коллекция).delivery .name содержит наименование транспорта или наименование операции.

delivery .expec­tedShippingDa­te (ожидаемая дата отгрузки) иdelivery .expec­tedDeliveryDa­te (предполагаемая дата доставки) — данные в форматеYYYY-MM-DD .

Ключweight содержит вес заказа в килограммах. В случае, если мы не знаем вес всех товаров в заказе, он принимает значениеnull .

ОТПРАВИТЬ /order/$slevomatId

{ "slevomatId": "480058070336", "created": "2021–09–06T16:39:02+02:00", "items": [ { "slevomatId": "7767", "productId": "25", "variantId": "194", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "4764573102", "productId": "3065", "variantId": "385", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": null, "street": null, "city": null, "postalCode": null, "country": null }, "shippingAddress": { "name": "Petr Novák", "company": null, "street": "Strašnická 8", "city": "Praha", "postalCode": "100 00", "phone": "+420777888999" }, "delivery": { "type": "address", "name": "PPL", "expectedShip­pingDate": "2021–09–08", "expectedDeli­veryDate": "2021–09–11", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

ОТПРАВИТЬ /order/$slevomatId

{ "slevomatId": "286238184713", "created": "2021–09–06T16:39:02+02:00", "items": [ { "slevomatId": "3461", "productId": "9", "variantId": "136", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "2320086446", "productId": "2855", "variantId": "7027", "internalId": null, "name": "Ručník modrý", "amount": 10, "unitPrice": 100.0 } ], "billingAddress": { "name": "Petr Novák", "company": "Novák a syn", "street": "Vodičkova 32", "city": "Praha 1", "postalCode": "110 00", "country": "Česko" }, "shippingAddress": { "name": "Provozovna Jahodová", "company": null, "street": "Jahodová 33", "city": "Praha 10", "postalCode": "100 00", "phone": "+420222888999", "deliveryPremise": { "id": 45445, "name": "Provozovna Jahodová" } }, "delivery": { "type": "pickup", "name": "Osobní odběr na provozovně", "expectedShip­pingDate": "2021–09–07", "expectedDeli­veryDate": "2021–09–07", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

Массовое обновление ожидаемых дат отгрузки

Если менеджер по сделкам по запросу партнера обновляет даты отправки массовых данных по выбранным заказам, система информирует API партнера об этом обновлении.

Отправляемые данные содержат поле идентификатора заказа и новую ожидаемую дату отправки.

POST /update-shipping-dates

{ "expectedShip­pingDate": "2021–09–06", "slevomatIds": [ "123456", "45454544" ] }

Аннулирования

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

Он создает отмену позиций заказа в указанном количестве. Если отменяется весь заказ, все позиции перечисляются с соответствующим количеством.

Отдельные позиции также могут быть аннулированы частично (например, 1 шт. из двух).

Аннулирование уведомления (note ) является необязательным.

POST /order/$slevo­matId/cancel

{ "items": [ { "slevomatId": "1212", "amount": 1 }, { "slevomatId": "4545454", "amount": 2 } ], "note": "storno v zákonné lhůtě" }

Подтверждение доставки

После того, как вы отметите заказ как «Доставленный клиенту», мы запросим у клиента подтверждение того, что он действительно получил его. Когда заказ будет отмечен как полученный, будет вызвана эта конечная точка.

POST /order/$slevo­matId/confirm-delivery

{}

Отказ от принятия

POST /order/$slevo­matId/reject-delivery

{ "rejectionReason": "Důvod odmítnutí zákazníkem" }

Измените статус заказа на «Готово к выдаче»

Эта конечная точка будет вызвана, если предыдущая конечная точка имела статус «Готово к личному сбору» и была установлена с помощьюautoMarkRea­dyForPickuptrue и на странице «Скидки» заказ автоматически перешел в статус «Готов к личному самовывозу»

POST /order/$slevo­matId/delivery-ready-for-pickup

{}

Измените статус заказа на «Доставлен клиенту — ожидается подтверждение клиента»

Эта конечная точка будет вызвана, если предыдущий статус «В пути», «Готово к личному самовывозу» или «Готово к личному самовывозу» был установлен с помощьюautoMarkDeli­veredtrue и на странице «Скидки» заказ автоматически перешел в статус «Доставлен клиенту — ожидает подтверждения клиента».

POST /order/$slevo­matId/mark-delivered

{}

Коммуникационный партнер ⇒ Zľavomat

Эта часть API реализована на стороне Discountomat и называется партнерской системой.

Корневой URL API:

https://www.zlavomat.sk/zbozi-api/v1

PHP-библиотека

Для реализации этой части API возможно использование подготовленной библиотеки PHP. Библиотека в настоящее время требует PHP версии 5.4 или выше и предполагает использование инструмента Composer.

Инструкции по использованию библиотеки и исходный код находятся на GitHub .

Запросы на авторизацию

Когда API включен, партнер получаетpartner_token иapi_secret , которые используются для аутентификации вызова API Zlavomat.

Эти параметры передаются в заголовках.X-PartnerToken иX-ApiSecret .

Тестовый интерфейс

Корневой URL-адрес тестового интерфейса:

https://www.zlavomat.sk/zbozi-api/v1-test

На нем можно вызывать все действия, как и на другом интерфейсе.

Тестовый интерфейс проверяет авторизацию запросов (корректность партнерского токена и секрета API) и валидность входящих тел запросов (JSON). В этом отношении он ведет себя идентично crisp API.

Однако тестовый интерфейс не работает с реальными заказами. Таким образом, он не проверяет, переходит ли заказ между правильными состояниями и содержит ли элементы с заданными идентификаторами. После того, как авторизация и валидация проходят формы запроса, тестовый интерфейс всегда отвечает успешным кодом 200 или 204.

Создание отмены

Создать отмену позиций заказа в указанном количестве. Если есть отмена заказа целиком, все позиции перечисляются с соответствующим количеством.

Отдельные позиции также могут быть отменены частично (например, 1 позиция из двух).

Аннулирование уведомления (note ) является необязательным.

ОТПРАВИТЬ /order/$slevomatId/отмена

{ "items": [ { "slevomatId": 45454, "amount": 15 } ], "note": "nepovinná poznámka" }

Изменить статус заказа на «В процессе»

POST /order/$slevomatId/отметить-ожидание

{}

Изменить статус заказа на «В пути»

При размещении заказа, autoMarkDelivered параметр используется для определения того, следует ли по истечении установленного периода отгрузки («Время от отгрузки до доставки») автоматически переходить в статус «Доставлено клиенту — ожидается подтверждение клиента».

Ответ содержит обновленную предполагаемую дату доставки.

POST /order/$slevomatId/mark-en-route

{ "autoMarkDeli­vered": true }

Ответ 200

{ "expectedDeli­veryDate": "2021–08–25" }

Измените статус заказа на «Готово к личному самовывозу»

Когда заказ проходит черезautoMarkReady­ForPickup параметр, указывающий, следует ли автоматически переводить время от отправки до доставки для данного типа пункта выдачи в статус «Готово к выдаче». для личного выноса.

При заказе необходимоautoMarkDelivered Параметр определяет, должен ли по истечении установленного количества дней для самовывоза для данного типа пункта выдачи пункт выдачи автоматически переходить из статуса «Готово к личному самовывозу» в статус «Доставлено клиенту — ожидает подтверждения от клиента».

Сочетание параметровautoMarkReady­ForPickup ложный иautoMarkDelivered true не допускается. В этом случае возвращается код ошибки 9.

В ответе указана обновленная предполагаемая дата доставки.

POST /order/$slevomatId/отметить-готовность-к-самовывозу

{ "autoMarkReady­ForPickup": true, "autoMarkDeli­vered": true }

Ответ 200

{ "expectedDeli­veryDate": "2021–09–06" }

Измените статус заказа на «Готово к самовывозу»

При размещении заказа, autoMarkDelivered параметр используется для определения того, следует ли по истечении заданного количества дней для самовывоза для данного типа самовывоза автоматически перевести пункт выдачи в статус «Доставлено клиенту — ожидает подтверждения клиента».

POST /order/$slevo­matId/mark-ready-for-pickup

{ "autoMarkDeli­vered": true }

Измените статус заказа на «Доставлено клиенту — ожидает подтверждения клиента»

POST /order/$slevo­matId/mark-delivered

{}

Изменить адрес доставки

Адрес доставки можно изменить только при доставке по адресу (т.е. изменить место получения нельзя).

Все клавиши, кромеcompany требуются.

Допустимые значения дляstate Ключевыми являютсяcz (Чешская Республика) иsk (Словакия).

POST /order/$slevo­matId/update-shipping-address

{ "name": "Karel Novák", "street": "Pod horou 34", "city": "Pardubice", "postalCode": "530 00", "state": "CZ", "phone": "+420777888999", "company": "Knihkupectví Novák" }