Как работает API калькулятор

Изменено Ср, 6 Апр, 2022 на 12:01 PM

Все примеры запросов в этой инструкции в формате Php для использования методом cURL в PHP

Перед тем как отправить запрос Вам необходимо пройти авторизацию.

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

При этом заголовок Accept необходимо сохранить.

Информацию о ваших API ключах можете найти здесь

$username = 'public key';   // ваш открытый ключ
$password = 'secret key';   // ваш закрытый ключ
$url = 'http://panel.orderadmin.ru/api/раздел/подраздел?';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_POST,true);
curl_setopt($ch, CURLOPT_USERPWD, $username . ':' . $password);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(   
    'Accept: application/json',
    'Content-Type: application/json')                                                           
);

Перед тем как отправить запрос к калькулятору, необходимо предварительно знать отправителя(sender) и место(locality), кем и куда будем отправлять заказ -> из метода /api/delivery-services/senders и /api/locations/localities -> по инструкции вставить ссылку ( или соответствующего раздела в интерфейсе).

Например:

1. Нам необходим id отправителя с названием "Основной аккаунт (ООО "НоВиКо")":

$request = [
    'filter' => [ 
         [      
            'type'  => 'ilike',  // Используем тип 'ilike' для получения частичных совпадений строк
            'field' => 'name',   //  Сущность - поиск по имени
            'value' => '%Новико%'  //  Значение сущности - имя отправителя
         ],      
    ],
];

Итоговый URL: https://cdek.orderadmin.ru/api/delivery-services/senders?filter[0][type]=ilike&filter[0][field]=name&filter[0][value]=%Новико%

В ответ получаем результат поиска с отправителями, у которых есть "Новико" в имени:

- отправитель "Основной аккаунт (ООО "НоВиКо")" с id = 139

[
    'senders' => 
   [
      0 => 
        'id' => 85,
        'state' => 'active',
        'name' => 'ООО «НоВиКо» (2%, с возвратом)',
        'serviceSelectionAdapter' => NULL,
        'settings' => 
      1 => 
      [
        'id' => 115,
        'state' => 'active',
        'name' => 'ООО "НоВиКо" (клиент)',
        'serviceSelectionAdapter' => NULL,
        'settings' => 
      2 => 
      [
        'id' => 1,
        'state' => 'active',
        'name' => 'ООО «НоВиКо» (Reworker)',
        'serviceSelectionAdapter' => NULL,
        'settings' => 
      3 => 
      [
        'id' => 139,
        'state' => 'active',
        'name' => 'Основной аккаунт (ООО "НоВиКо")',
        'serviceSelectionAdapter' => NULL,
        'settings' => 
        ],
      ],
    ],
  ],
  'page_count' => 1,
  'page_size' => 25,
  'total_items' => 4,
  'page' => 1,
]

2. Поиск id местоположения. Например, нам необходимо id села Дальнее, Сахалинская область

$request =  [
        'filter'  =>  [
                [
                    'type'  => 'eq' ,       // Тип для получения конкретных данных(равно)
                    'field'  => 'name',  //  Поле - поиск по названию
                    'value' =>  'Дальнее'    // Значения - Значение сущности    
                ],    
                      [
                    'type'  => 'eq' ,       // Тип для получения конкретных данных(равно)
                    'field'  => 'state',  //  Поле - поиск по состоянию
                    'value' =>  'active'    // Значения - Значение сущности    
                ],    
       ] ,
    ];

Итоговый URL: https://cdek.orderadmin.ru/api/locations/localities?filter[0][type]=eq&filter[0][field]=name&filter[0][value]=Дальнее&filter[1][type]=eq&filter[1][field]=state&filter[1][value]=active

В ответ получаем все активные местоположения с названием Дальнее (наше местоположение с id = 189634)

[
    'localities' => 
      0 => 
        'id' => 6548,
        'state' => 'active',
        'name' => 'Дальнее',
        'type' => 'Село',
        'extId' => '2ea4a2b8-f45e-4d94-800c-83e1615755f7',
        'postcode' => '692550',
          'area' => 
            'id' => 2923,
            'state' => 'active',
            'name' => 'Михайловский Район',
            'lft' => 1679,
            'rgt' => 1680,
            'root' => 2111,
            'level' => 2,
            'updated' => 
      1 => 
         [],
      2 => 
         [],
      3 => 
         [],
      4 => 
         [],
      5 => 
         [],
      6 => 
        'id' => 185659,
        'state' => 'active',
        'name' => 'Дальнее',
        'type' => 'аул(село)',
        'extId' => 'A208905',
        'postcode' => NULL,
          'country' => 
            'state' => 'active',
            'code' => 'KZ',
            'name' => 'Қазақстан',
            'nativeLocale' => 'ru_RU',
            'type' => NULL,
            'id' => 158,
      7 => 
        'id' => 189634,
        'state' => 'active',
        'name' => 'Дальнее',
        'type' => 'село',
        'extId' => 'b0ad38f6-a757-49a9-b28b-972a650a4063',
        'postcode' => '693904',
          'area' => 
            'id' => 2291,
            'state' => 'active',
            'name' => 'Сахалинская Область',
            'lft' => 2894,
            'rgt' => 2929,
            'root' => 2111,
            'level' => 1,
            'updated' =>
      ]

3. Запросу для расчета стоимости доставки

Используем метод запроса POST

Request URL: https://cdek.orderadmin.ru/api/delivery-services/calculator -> Калькулятор работает обращаясь напрямую к API

параметр 'from' => 'От' система берет из Отправителя

$request= [
  'sender' => '139',               // id Отправителя 
  'to' =>                              // направление 'до'
   [
    'id' => '189634',                       // указываем id -> Местоположения
    'postcode' => '693904',                // почтовый индекс, необязательно
  ],
  'estimatedCost' => '1000',            // оценочная стоимость
  'payment' => '1000',                     // оплата
  'weight' => '1000',                         // обязательный параметр в граммах
  'width' => '100',                          // габариты (ширина) в мм
  'height' => '100',                      // габариты (высота) в мм
  'length' => '100',                             // габариты (длина) в мм
]

Получаем ответ:

{
    "deliveryServices": [
        {
            "id": 1,
            "name": "Cdek",
            "logo": "/img/delivery-services/cdek.png"
        }
    ],
    "rates": [
        {
            "id": 39,
            "name": "Экспресс лайт склад-дверь",
            "description": "Классическая экспресс-доставка по России документов и грузов",
            "type": "courier",
            "deliveryPrice": 2099.87,
            "currency": "RUB",
            "deliveryTime": {
                "min": 7,
                "max": 10
            },
            "deliveryService": {
                "id": 1,
                "name": "Cdek"
            },
            "cache": true,
            "price": 2099.87
        },
        {
            "id": 37,
            "name": "Экспресс лайт дверь-дверь",
            "description": "Классическая экспресс-доставка по России документов и грузов до 30 кг",
            "type": "courier",
            "deliveryPrice": 2172.75,
            "currency": "RUB",
            "deliveryTime": {
                "min": 7,
                "max": 10
            },
            "deliveryService": {
                "id": 1,
                "name": "Cdek"
            },
            "cache": true,
            "price": 2172.75
        }
    ]
}

Если калькулятор не находит местоположение, то возвращает ошибку

{
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "title": "Not Found",
    "status": 404,
    "detail": "Место назначение не установлено"
}

Все методы работают по одному принципу:

GET без ID - список сущностей (например, все службы доставки: https://cdek.orderadmin.ru/api/delivery-services)

GET с ID - одна сущность со встроенными под сущностями

POST - создание

PATCH - обновление

3. В каком формате нужно передавать weight?

- Граммы;

4. В каком формате нужно передавать единицы измерения?
- Миллиметры;

5. Что означают payment и estimatedCost?
- payment - наложенный платеж, estimatedCost - оценочная стоимость;

6. Что нужно передать в поле "debug" для включения отладки? И что будет в отладочной информации?
- Отключается многопоточный калькулятор, если передать true, еще можно увидеть причину отсутствия расчета;

7. Как будут отличаться результаты расчета, если не передать все или какие-то конкретные необязательные поля?
- Расчет будет не точным или, если параметр критичный, его вообще не будет;

8. Почему поле "from" необязательное?
- Потому что данные поля можно указать в "sender" (как в примере выше);

9. В каком формате нужно заполнять информацию в поле "from"?
- В таком же как и "to", в вашем случае лучше указать отправителя.

10. Возможно ли определение адреса получателя по почтовому индексу?
- Наша система по индексу может определить город, но не более, т.к. вокруг почтового отделения масса улиц может быть и еще больше домов.

Поддержка | VK | Telegram | Сайт | Оцените нашу работу

Статья помогла?