API сторонних разработчиков

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

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

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

API-доступ

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

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 реализована на стороне партнера и вызывается Slevomat.

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

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

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

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

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

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

Slevomat включает в себя функциональность для вызова API на стороне партнера и просмотра ответа. Корневой URL, указанный партнером, когда API становится доступным, добавляется к-test , так что при тестировании API вызывается, например,

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

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

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

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/new-order

   – Новый порядок

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/update-shipping-dates 

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

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/mark-delivered 

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

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/ready-for-pickup 

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

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/confirm-delivery 

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

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/reject-delivery 

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

• https://www.sle­vomat.cz/test-zbozi-partner-api/v1/order/<or­derId>/cancel 

   – Отмена

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

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

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

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

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

Новый заказ

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

Заказы всегда имеют уникальныйslevomatId . Если API получает дубликатslevomatId , запрос должен быть проигнорирован API партнера (первый запрос был оценен как неудачный Slevomat и поэтому повторен), а ответ также должен быть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": "721896899157", "created": "2021–08–25T15:14:24+02:00", "items": [ { "slevomatId": "960", "productId": "22", "variantId": "105", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "7577400222", "productId": "1752", "variantId": "9855", "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": "Petr Novák", "company": null, "street": "Strašnická 8", "city": "Praha", "postalCode": "100 00", "phone": "+420777888999" }, "delivery": { "type": "address", "name": "PPL", "expectedShip­pingDate": "2021–08–27", "expectedDeli­veryDate": "2021–08–30", "price": 100.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

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

{ "slevomatId": "124146766678", "created": "2021–09–01T12:49:37+02:00", "items": [ { "slevomatId": "863", "productId": "64", "variantId": "14", "internalId": null, "name": "Sandále vel. 42", "amount": 1, "unitPrice": 250.0 }, { "slevomatId": "2364201450", "productId": "7057", "variantId": "5802", "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–02", "expectedDeli­veryDate": "2021–09–02", "price": 0.0 }, "status": 1, "customer": { "email": "petr.novak@e­xample.com" }, "weight": 1.2 }

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

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

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

POST /update-shipping-dates

{ "expectedShip­pingDate": "2021–08–25", "slevomatIds": [ "123456", "45454544" ] }

Отмена

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

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

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

Записка об аннулировании (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 и заказ был автоматически переведен в статус «Готово к личному выдаче» на стороне Slevomat.

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

{}

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

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

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

{}

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

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

Корневой URL API:

 https://www.slevomat.cz/zbozi-api/v1

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

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

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

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

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

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

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

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

https://www.slevomat.cz/zbozi-api/v1-test

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

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

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

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

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

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

Записка об аннулировании (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–08–25" }

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

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

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

Журнал изменений