Сценарий создания заказа с доп. услугами

From PonyExpress API Wiki
Jump to: navigation, search

Описание сценария

Сценарий предполагает оформление заказа с возможностью выбора некоторых дополнительных сервисов (возврат документов, передача отправления лично в руки и др.).
Данная возможность по умолчанию не доступна. Чтобы активировать возможность передачи доп. услуг, необходимо связаться с персональным менеджером, чтобы он инициировал процесс настройки.


Получение списка дополнительных услуг

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

<?xml version="1.0" encoding="utf-8"?>
<Request xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="OrderRequest">
  <Id>1</Id>
  <Mode>Calculation</Mode>
  <OrderList>
    <Order>
      <ServiceList>
        <Service xsi:type="DeliveryService">
          <Mode>Express</Mode>
          <Sender>
            <Address>
              <Country>Россия</Country>
              <PostCode>127023</PostCode>
              <City>Москва</City>
              <StreetAddress>ул.Строителей, д.13</StreetAddress>
            </Address>
          </Sender>
          <Recipient>
            <Address>
              <Country>Россия</Country>
              <Region>Красноярcкий край</Region>
              <PostCode>660013</PostCode>
              <City>Красноярск</City>
              <StreetAddress>ул.Взлетная, д.1</StreetAddress>
            </Address>
          </Recipient>
          <CargoList>
            <Cargo>
              <Dimentions>
                <Length>350</Length>
                <Width>500</Width>
                <Height>300</Height>
              </Dimentions>
              <Weight>1400</Weight>
              <Cost>5000</Cost>
            </Cargo>
            <Cargo>
              <Dimentions>
                <Length>250</Length>
                <Width>300</Width>
                <Height>200</Height>
              </Dimentions>
              <Weight>800</Weight>
              <Cost>2000</Cost>
            </Cargo>
          </CargoList>
        </Service>
      </ServiceList>
    </Order>
  </OrderList>
</Request>

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

<?xml version="1.0" encoding="utf-8"?>
<Response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <RequestId>1</RequestId>  <OrderList>
    <Order>
      <Guid>b051922e-d93a-4af2-b7f5-45054716882f</Guid>      
      <ClientsNumber>Generated_279a3977-e940-4808-9a93-f88b7bc7020e</ClientsNumber>
      <OrderType>OnlineShop</OrderType>
      <ServiceList>
        <Service xsi:type="DeliveryService">
          <Calculation xsi:type="DeliveryCalculation">
            <CargoAmount>1</CargoAmount>
            <Weight>2200</Weight>
            <VolumeWeight>14000</VolumeWeight>
            <IsDangerous>false</IsDangerous>
            <IsOversized>false</IsOversized>            
            <IsCashBanIM>false</IsCashBanIM>
            <DeliveryRateSet>
              <DeliveryRate>
                <Mode>Express</Mode>
                <Sum>3361.7300</Sum>
                <VAT>605.1100</VAT>
                <MinTerm>1</MinTerm>
                <MaxTerm>2</MaxTerm>
                <TermUnit>WorkDay</TermUnit>
                <FuelChargePercent>11.50</FuelChargePercent>
                <DiscountPercent>0.00</DiscountPercent>
                <Description>Экспресс почта</Description>
                <OrderDT>16:00</OrderDT>
                <CargoDT>18:00</CargoDT>
                <PickupTimeFrom>09:00</PickupTimeFrom>
                <PickupTimeTo>18:00</PickupTimeTo>
                <AdditionalServices>
                  <DeliveryAdditionalService>
                    <Code>1013</Code>
                    <Name>Возврат документов</Name>
                    <Description>Возврат документов</Description>
                    <IncludingType>MayBeIncluded</IncludingType>
                    <Sum>1.0000</Sum>
                    <VAT>0.1800</VAT>
                    <Parameters>
                      <ServiceParameter xsi:type="AddressParameter" />
                    </Parameters>
                  </DeliveryAdditionalService>
                  <DeliveryAdditionalService>
                    <Code>1019</Code>
                    <Name>Обрешетка</Name>
                    <Description>Обрешетка</Description>
                    <IncludingType>MayBeIncluded</IncludingType>
                    <Sum>100.0000</Sum>
                    <VAT>18.0000</VAT>
                    <Parameters>
                      <ServiceParameter xsi:type="CountParameter"></ServiceParameter>
                    </Parameters>
                  </DeliveryAdditionalService>                  
                  <DeliveryAdditionalService>
                    <Code>1022</Code>
                    <Name>СМС-уведомление отправителя</Name>
                    <Description>СМС-уведомление отправителя</Description>
                    <IncludingType>Included</IncludingType>
                    <Sum>30.0000</Sum>
                    <VAT>5.4000</VAT>
                  </DeliveryAdditionalService>
                  <DeliveryAdditionalService>
                    <Code>1015</Code>
                    <Name>Лично в руки</Name>
                    <Description>Лично в руки</Description>
                    <IncludingType>MayBeIncluded</IncludingType>
                    <Sum>150.0000</Sum>
                    <VAT>27.0000</VAT>
                  </DeliveryAdditionalService>
                </AdditionalServices>
              </DeliveryRate>
            </DeliveryRateSet>
          </Calculation>
          <Mode>Express</Mode>          <Sender>
            <Address>
              <Country>Россия</Country>
              <PostCode>127023</PostCode>
              <City>Москва</City>
              <StreetAddress>ул.Строителей, д.13</StreetAddress>
            </Address>
          </Sender>
          <Recipient>
            <Address>
              <Country>Россия</Country>
              <Region>Красноярcкий край</Region>
              <PostCode>660013</PostCode>
              <City>Красноярск</City>
              <StreetAddress>ул.Взлетная, д.1</StreetAddress>
            </Address>
          </Recipient>
          <CargoList>
            <Cargo>
              <Dimentions>
                <Length>250</Length>                
                <Width>300</Width>                
                <Height>200</Height>              
              </Dimentions>
              <Weight>800</Weight>              
              <Cost>200000.0000</Cost>
            </Cargo>
            <Cargo>
              <Dimentions>
                <Length>350</Length>
                <Width>500</Width>
                <Height>300</Height>
              </Dimentions>
              <Weight>1400</Weight>
              <Cost>5000.0000</Cost>
            </Cargo>
          </CargoList>
        </Service>
      </ServiceList>
      <StatusList>
        <OrderStatus>
          <Description>Order is in calculating</Description>
          <Date>2017-06-28T18:53:27.97</Date>
          <Code>Calulation</Code>
        </OrderStatus>
        <OrderStatus>
          <Description>Order has been checked</Description>
          <Date>2017-06-28T18:53:28.187</Date>
          <Code>Checked</Code>
        </OrderStatus>
        <OrderStatus>
          <Description>Order has been calculated</Description>
          <Date>2017-06-28T18:53:29.383</Date>
          <Code>Calculated</Code>
        </OrderStatus>
      </StatusList>
    </Order>
  </OrderList>
</Response>

Услуги, у которых IncludingType=Included будут включены автоматически. Если IncludingType=MayBeIncluded, то это опциональная услуга, её нужно принудительно передать в запросе на создание заказа


Перерасчёт

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

                  <DeliveryAdditionalService>
                    <Code>1019</Code>
                    <Name>Обрешетка</Name>
                    <Description>Обрешетка</Description>
                    <IncludingType>MayBeIncluded</IncludingType>
                    <Sum>100.0000</Sum>
                    <VAT>18.0000</VAT>
                    <Parameters>
                      <ServiceParameter xsi:type="CountParameter"></ServiceParameter>
                    </Parameters>
                  </DeliveryAdditionalService>

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

<?xml version="1.0" encoding="utf-8"?>
<Request xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="OrderRequest">
  <Id>1</Id>
  <Mode>Calculation</Mode>
  <OrderList>
    <Order>
      <ServiceList>
        <Service xsi:type="DeliveryService">
          <Mode>Express</Mode>
          <Sender>
            <Address>
              <Country>Россия</Country>
              <PostCode>127023</PostCode>
              <City>Москва</City>
              <StreetAddress>ул.Строителей, д.13</StreetAddress>
            </Address>
          </Sender>
          <Recipient>
            <Address>
              <Country>Россия</Country>
              <Region>Красноярcкий край</Region>
              <PostCode>660013</PostCode>
              <City>Красноярск</City>
              <StreetAddress>ул.Взлетная, д.1</StreetAddress>
            </Address>
          </Recipient>
          <CargoList>
            <Cargo>
              <Dimentions>
                <Length>350</Length>
                <Width>500</Width>
                <Height>300</Height>
              </Dimentions>
              <Weight>1400</Weight>
              <Cost>5000</Cost>
            </Cargo>
            <Cargo>
              <Dimentions>
                <Length>250</Length>
                <Width>300</Width>
                <Height>200</Height>
              </Dimentions>
              <Weight>800</Weight>
              <Cost>2000</Cost>
            </Cargo>
          </CargoList>
         <AdditionalServices>  
            <DeliveryAdditionalService>
              <Code>1019</Code>
              <Parameters>
                <ServiceParameter xsi:type="CountParameter">
                  <Count>10</Count>
                </ServiceParameter>
              </Parameters>
            </DeliveryAdditionalService>           
          </AdditionalServices>
        </Service>
      </ServiceList>
    </Order>
  </OrderList>
</Request>

В ответе получим услугу с обновлённой стоимостью

                  <DeliveryAdditionalService>
                    <Code>1019</Code>
                    <Name>Обрешетка</Name>
                    <Description>Обрешетка</Description>
                    <IncludingType>Selected</IncludingType>
                    <Sum>1000.0000</Sum>
                    <VAT>180.0000</VAT>
                    <Parameters>
                      <ServiceParameter xsi:type="CountParameter">
                        <Count>10</Count>
                      </ServiceParameter>
                    </Parameters>
                  </DeliveryAdditionalService>


Создание заказа

При создании заказа все выбранные услуги необходимо разместить в блоке AdditionalServices, заполнив все необходимые параметры.

Предположим, мы хотим создать заказ с услугами:

  • Обрешётка (1019)
  • Возврат документов (1013)
  • Лично в руки (1015)

И дополнительно хотим передать услугу, которая не доступна для заказа:

  • Прозвон (1017)
<?xml version="1.0" encoding="utf-8"?>
<Request xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="OrderRequest">
  <Id>1</Id>
  <Mode>Order</Mode>
  <OrderList>
    <Order>
      <ServiceList>
        <Service xsi:type="DeliveryService">
          <Mode>Express</Mode>
          <Sender>
            <Address>
              <Country>Россия</Country>
              <PostCode>127023</PostCode>
              <City>Москва</City>
              <StreetAddress>ул.Строителей, д.13</StreetAddress>
            </Address>
          </Sender>
          <Recipient>
            <Address>
              <Country>Россия</Country>
              <Region>Красноярcкий край</Region>
              <PostCode>660013</PostCode>
              <City>Красноярск</City>
              <StreetAddress>ул.Взлетная, д.1</StreetAddress>
            </Address>
          </Recipient>
          <CargoList>
            <Cargo>
              <Dimentions>
                <Length>350</Length>
                <Width>500</Width>
                <Height>300</Height>
              </Dimentions>
              <Weight>1400</Weight>
              <Cost>5000</Cost>
            </Cargo>
            <Cargo>
              <Dimentions>
                <Length>250</Length>
                <Width>300</Width>
                <Height>200</Height>
              </Dimentions>
              <Weight>800</Weight>
              <Cost>2000</Cost>
            </Cargo>
          </CargoList>
         <AdditionalServices>  
            <DeliveryAdditionalService>
              <Code>1015</Code>
            </DeliveryAdditionalService>
            <DeliveryAdditionalService>
              <Code>1017</Code>
            </DeliveryAdditionalService>
            <DeliveryAdditionalService>
              <Code>1019</Code>
              <Parameters>
                <ServiceParameter xsi:type="CountParameter">
                  <Count>10</Count>
                </ServiceParameter>
              </Parameters>
            </DeliveryAdditionalService>           
            <DeliveryAdditionalService>
              <Code>1013</Code>
              <Parameters>
                <ServiceParameter xsi:type="AddressParameter">
                  <Country>Россия</Country>
                  <Region>Московская область</Region>
                  <District>Одинцовский</District>
                  <PostCode>111631</PostCode>
                  <City>Одинцово</City>
                  <StreetAddress>Белорусская 4 -125</StreetAddress>
                </ServiceParameter>
              </Parameters>
            </DeliveryAdditionalService>               
          </AdditionalServices>
        </Service>
      </ServiceList>
    </Order>
  </OrderList>
</Request>

В ответе вернётся стандартный Responce на создание заказа, дополненный секцией "AdditionalServices". В этой секции мы видим, что услуги, которые не были нам не доступны отклонены (IncludingType=Declined), обязательные услуги принудительно добавлены к заказу (IncludingType=Included) и так же к заказу добавлены услуги, которые мы выбрали из возможных (IncludingType=Selected)

<Response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <RequestId>1</RequestId>
  <OrderList>
    <Order>
      <Guid>8a4926c0-b078-4c7c-a4c8-8ea9fe597b38</Guid>
      <ClientsNumber>Generated_8b5bd64f-a880-491a-a280-2c6251e4cb2a</ClientsNumber>
      <PerformersNumber>MOW18109475</PerformersNumber>
      <OrderType>Regular</OrderType>
      <ServiceList>
        <Service xsi:type="DeliveryService">
          <Mode>Express</Mode>
          <Waybill>
            <Number>18-2736-0216</Number>
          </Waybill>
          <Sender>
            <Address>
              <Country>Россия</Country>
              <PostCode>127023</PostCode>
              <City>Москва</City>
              <StreetAddress>ул.Строителей, д.13</StreetAddress>
            </Address>
            <Node>MOW</Node>
          </Sender>
          <Recipient>
            <Address>
              <Country>Россия</Country>
              <Region>Красноярcкий край</Region>
              <PostCode>660013</PostCode>
              <City>Красноярск</City>
              <StreetAddress>ул.Взлетная, д.1</StreetAddress>
            </Address>
            <Node>KJA</Node>
          </Recipient>
          <CargoList>
            <Cargo>
              <Dimentions>
                <Length>350</Length>
                <Width>500</Width>
                <Height>300</Height>
              </Dimentions>
              <Weight>1400</Weight>
              <VolumeWeight>10500</VolumeWeight>
              <Cost>5000.0000</Cost>
            </Cargo>
            <Cargo>
              <Dimentions>
                <Length>250</Length>
                <Width>300</Width>
                <Height>200</Height>
              </Dimentions>
              <Weight>800</Weight>
              <VolumeWeight>3000</VolumeWeight>
              <Cost>2000.0000</Cost>
            </Cargo>
          </CargoList>
          <AdditionalServices>
            <DeliveryAdditionalService>
              <Code>1022</Code>
              <Name>СМС-уведомление отправителя</Name>
              <Description>СМС-уведомление отправителя</Description>
              <IncludingType>Included</IncludingType>
              <Sum>30.0000</Sum>
              <VAT>5.4000</VAT>
            </DeliveryAdditionalService>
            <DeliveryAdditionalService>
              <Code>1015</Code>
              <Name>Лично в руки</Name>
              <Description>Лично в руки</Description>
              <IncludingType>Selected</IncludingType>
              <Sum>150.0000</Sum>
              <VAT>27.0000</VAT>
            </DeliveryAdditionalService>
            <DeliveryAdditionalService>
              <Code>1017</Code>
              <Name>Прозвон</Name>
              <Description>Прозвон</Description>
              <IncludingType>Declined</IncludingType>
              <Sum>0.0000</Sum>
              <VAT>0.0000</VAT>
            </DeliveryAdditionalService>
          </AdditionalServices>
          <DeliveryAdditionalService>
            <Code>1019</Code>
            <Name>Обрешетка</Name>
            <Description>Обрешетка</Description>
            <IncludingType>Selected</IncludingType>
            <Sum>1000.0000</Sum>
            <VAT>180.0000</VAT>
            <Parameters>
              <ServiceParameter xsi:type="CountParameter">
                <Count>10</Count>
              </ServiceParameter>
            </Parameters>
          </DeliveryAdditionalService>
          <DeliveryAdditionalService>
            <Code>1013</Code>
            <Name>Возврат документов</Name>
            <Description>Возврат документов</Description>
            <IncludingType>Selected</IncludingType>
            <Sum>1.0000</Sum>
            <VAT>0.1800</VAT>
            <Parameters>
              <ServiceParameter xsi:type="AddressParameter">
                <Country>Россия</Country>
                <Region>Московская область</Region>
                <District>Одинцовский</District>
                <PostCode>111631</PostCode>
                <City>Одинцово</City>
                <StreetAddress>Белорусская 4 -125</StreetAddress>
              </ServiceParameter>
            </Parameters>
          </DeliveryAdditionalService>
        </Service>
      </ServiceList>
      <StatusList>
        <OrderStatus>
          <Description>Order has been received</Description>
          <Date>2017-06-29T12:09:11.203</Date>
          <Code>Received</Code>
        </OrderStatus>
        <OrderStatus>
          <Description>Order has been checked</Description>
          <Date>2017-06-29T12:09:12.057</Date>
          <Code>Checked</Code>
        </OrderStatus>
        <OrderStatus>
          <Description>Order is in processing</Description>
          <Date>2017-06-29T12:09:13.273</Date>
          <Code>Processing</Code>
        </OrderStatus>
      </StatusList>
    </Order>
  </OrderList>
</Response>