Державне підприємство спеціального зв'язку
Київ пл. Вокзальна, 3

ДПСЗ API

Введення

Цей документ описує REST API системи електронної комерції DPSZ

Документ включає:

  • Основний опис системи

  • Опис REST API форматів обміну даними JSON та XML

  • Підтримувані типи повідомлень

Команда розробників рекомендує враховувати наступне, щодо впровадження інтерфейсів для інтеграції:

  • REST API для формату JSON вважається кращим і настійно рекомендується

  • REST API для формату XML реалізований для забезпечення сумісності з програмним забезпеченням яке було створене давно і не підтримує формат JSON

HTTP

Система DPSZ максимально наближено до стандартних конвенцій HTTP та REST

HTTP Методи

Table 1. HTTP Verbs
Verb Usage

POST

Метод HTTP POST надсилає дані на сервер. Тип тіла запиту вказується в заголовку Content-Type.

HTTP Коди статусів

Table 2. HTTP Status Codes
Status Code Usage

200

Стандартна відповідь на успішні запити HTTP. Фактична відповідь буде залежати від використовуваного методу запиту. У запиті GET відповідь міститиме сутність, що відповідає запитуваному ресурсу. У запиті POST відповідь буде містити сутність, яка описує або містить результат дії.

400

Неправильний запит. Сервер не може або не обробляє запит через те, що сприймається як помилка клієнта (наприклад, неправильний синтаксис запиту, неправильне обрамлення повідомлення запиту або оманливе маршрутизація запиту).

404

Не знайдено. Запитаний ресурс не вдалося знайти, але він може бути знову доступний у майбутньому.

500

Внутрішня помилка. Сервер зіткнувся з несподіваною умовою, яка завадила йому виконати запит.

502

Поганий шлюз. Сервер діяв як шлюз або проксі та отримав недійсну відповідь від залежного сервера.

  Усі типи помилок повертають тіло з типом змісту text/plain. Будьте уважними

REST інтерфейс

Кінцева точка REST має наступний формат

Де ENDPOINT_NAME - це ім’я інтерфейсу REST, який ви хочете використовувати. Ви можете знайти доступні REST інтерфейси нижче.

Наприклад, якщо ви хочете використовувати Cost of Delivery (Вартість доставки), формат буде таким:

Вартість доставки

Інтерфейс за допомогою якого можно розрахувати вартість доставки

Endpoint
http://api.dpsz.ua/v1/delivery
Table 3. Параметри запиту
Name Type Description

weight

double

Вага пакунку

includeTax

boolean

Чи потрібно включати НДС, якщо це поле встановити true то система врахує 20% НДС в кінцеву сумму

includeAssessment

double

Оголошена оціночна вартість.

includeCod

double

Накладений платіж (яку сумму очікує відправник від одержувача)

needToPack

boolean

Чи включити послугу пакування посилок

needBeDeliveryToRecipient

boolean

Чи потрібна доставка до одержувача?

needBePickUpFromSender

boolean

Чи потрібно забрати пакунок у відправника?

  Усі параметри обов’язкові. Якщо ви не хочете надсилати суму C.O.D (наприклад), ви повинні встановити це поле в нуль (0,0), а для булевих типів полів - false.

Приклади запитів

JSON Request
POST http://api.dpsz.ua/v1/delivery
Content-Type: application/json
JSON Body
{
  "weight": 225.5,
  "includeTax": false,
  "includeAssessment": 225.2,
  "includeCod": 2234.4,
  "needToPack": false,
  "needBeDeliveryToRecipient": false,
  "needBePickUpFromSender": false
}
XML Request
POST http://api.dpsz.ua/v1/delivery
Content-Type: application/xml
XML Body
<inputData>
<weight>225.5</weight>
<includeTax>true</includeTax>
<includeAssessment>225.2</includeAssessment>
<includeCod>2234.4</includeCod>
<needToPack>true</needToPack>
<needBeDeliveryToRecipient>true</needBeDeliveryToRecipient>
<needBePickUpFromSender>true</needBePickUpFromSender>
</inputData>