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

API используется для передачи информации о заказах между системой Discount Machine и системой бизнес-партнёра. API требует реализации двусторонней связи: система Discount Machine обращается к API партнёра, а партнёр обращается к API Discount Machine.

Заказы, экспортированные в партнёрский API, больше нельзя изменять в партнёрском интерфейсе Zlavomat, их можно только просматривать. Экспортированные заказы теперь можно изменять только через API.

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

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

Доступ к API осуществляется на вкладке «Настройки» вашего партнёрского интерфейса. Для получения данных необходимо ввести корневой URL партнёрской части API в направлении Zlavomat → Партнёр, например.

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." ] }

Типы данных

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

Коммуникационная дисконтная машина ⇒ Партнер

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

Необходимый корневой URL-адрес API будет предоставлен партнером. Он должен быть в следующем формате:

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

Авторизация запросов

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

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

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

Скидочный автомат включает в себя функцию вызова API на стороне партнёра и отображения ответа. Корневой URL-адрес, указанный партнёром при предоставлении API, прикреплён к-test , поэтому в рамках тестирования 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

   – Отмена

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

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

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

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

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

Новый заказ

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

Заказы всегда уникальныzlavomatId Если в API поступает дубликатzlavomatId , API-интерфейс партнера должен проигнорировать запрос (первый запрос, сделанный Zľavomat, был оценен как неудачный, и поэтому мы повторяем его) и также ответить 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 .

POST /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 }

POST /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" ] }

Отмена

Отмены заказов могут быть созданы как на стороне Zlavomat, так и в системе-партнёре. Эта конечная точка отвечает за создание отмен на стороне 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 а на стороне Zlavomat заказ автоматически перешел в статус «Готов к личному самовывозу»

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

{}

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

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

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

{}

Коммуникационный партнер ⇒ Дисконтный автомат

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

Корневой 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). В этом отношении он работает идентично реальному API.

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

Создать отмену

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

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

Записка об отмене (note ) является необязательным.

POST /order/$slevomatId/cancel

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

Изменение статуса заказа на «Обработка»

POST /order/$slevomatId/mark-pending

{}

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

При заказе параметр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/mark-getting-ready-for-pickup

{ "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" }