czech_post_b2b_client 1.0.3 → 1.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d7c296befdf3e8a0575b0855f80ddc0bfd730db4
-  data.tar.gz: 2c9519c8d7e5a483c60cf356bafe5dd652149763
+SHA256:
+  metadata.gz: 468b92710ed75993d00a0f30f9a66a1e40ae8b23607ed92796c9682a0493f237
+  data.tar.gz: c48017f58f179a0dae607662c309a1eabb0b7370f7372521acdfb655983eff44
 SHA512:
-  metadata.gz: a66d5f3d8160159490b7197cd0e1edf0107e7cb6610d019495a8ab02650118881f94d6c8deca7ef3bce55cdcfe3573392626e10220ec158876f807556f147b81
-  data.tar.gz: f0cdc245a2c4f58432475e7cb3afe32acb707d0710e150977e823418142424f955ae3301748aeae072cf994db52654d0c544d02257bfd8bdc6e6dc7219e16a94
+  metadata.gz: 3b6dd0a6c4bb96f076cb37a42ec1dd0ce08346f28285109079831bf3fe94eb2d45d054156119b80e846b3f22ed9a18f2ded82856f2345b394e05c2c7e0560c2a
+  data.tar.gz: 2a461713e123f67b66d45a02fab03123c75f7a9b968dede63351bbadc123baa74ab7a0be8648124643008602f35d372a5fcaf86d24e768bac4165ec85ceed773

data/.rubocop.yml

@@ -14,7 +14,7 @@ AllCops:
     - "bin/*"
 Documentation:
   Enabled: false
-Metrics/LineLength:
+Layout/LineLength:
   Max: 120
 Metrics/AbcSize:
   Max: 20

data/CHANGELOG.md

@@ -2,11 +2,36 @@
 
 All changes to the gem are documented here.
 
+## [1.2.4] - 2020-10-06
+
+ - Added `configuration.log_messages_at_least_as` option, to be able debug client behaviour when app log level is higher (eg. production)
+
+## [1.2.3] - 2020-08-21
+
+ - Corrected order in XML `sequence` elements
+ - Added `schemaLocation` to root element and placed publicly accessible XSDs into Github repo
+
+## [1.2.2] - 2020-08-19
+
+ - Printing templates now include @page_dimensions
+ - Forced secure SSL ciphers for requests
+ - `examples/try_api_call.rb` refactored to be more versatile (download XSDs [:do not work], pritn_selected_combinations)
+
+## [1.2.0] - 2020-06-07
+
+ - **Breaking** Introducing new Printing templates, improved some template names and scopes
+ - Added options `custom_card_number` and `print_options` to `Configuration`
+
+## [1.1.0] - 2020-05-28
+
+ - Introducing new API documentation from Czech Post
+ - Added service `ParcelSyncSender` service which uses newly discovered `parcelsServiceSync` API endpoint
+ - Renamed `ParcelSender` to `ParcelAsyncSender` . And created deprecating clone `ParcelSender`, so no Breaking change! If You usit it calls `ParcelAsyncSender` and displays deprecation message.
 
 ## [1.0.3] - 2020-05-20
 
  - Added Czech Post service  DiscountForOnlinePosting.
- - **Breaking**: Renamed Post service size classes `CzechPostB2bClient::PostServices::Size???` to `CzechPostB2bClient::PostServices::ParcelSize???` (eg. : `CzechPostB2bClient::PostServices::ParcelSizeXL`)
+ - **Breaking**: Renamed Post service "Size" classes `CzechPostB2bClient::PostServices::Size???` to `CzechPostB2bClient::PostServices::ParcelSize???` (eg. : `CzechPostB2bClient::PostServices::ParcelSizeXL`)
   I know, that I have **breaking** in every new version, I hope You are not fast enough.
 
 ## [1.0.2] - 2020-05-08

data/README.md

@@ -1,13 +1,54 @@
+
+# FRESH NEWS
+After full usage in production (vyvolej.to, squared.one), we found that Czech POst have trouble with `parcelServiceSync` (maybe `sendParcels` too). When You try to register package with `:customs_documents`, you get `INVALID_BATCH` response with no error, but with `parcelCode`:
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<v1:b2bSyncResponse xmlns:v1="https://b2b.postaonline.cz/schema/B2BCommon-v1" xmlns:v1_1="https://b2b.postaonline.cz/schema/POLServices-v1">
+  <v1:header>
+    <v1:b2bRequestHeader>
+      <v1:idExtTransaction>1</v1:idExtTransaction>
+      <v1:timeStamp>2020-08-22T07:32:20.496Z</v1:timeStamp>
+      <v1:idContract>356936003</v1:idContract>
+    </v1:b2bRequestHeader>
+  </v1:header>
+  <v1:serviceData><v1_1:parcelServiceSyncResponse>
+      <v1_1:responseHeader>
+        <v1_1:resultHeader>
+          <v1_1:responseCode>19</v1_1:responseCode>
+          <v1_1:responseText>BATCH_INVALID</v1_1:responseText>
+        </v1_1:resultHeader>
+        <v1_1:resultParcelData>
+          <v1_1:recordNumber>52427</v1_1:recordNumber>
+          <v1_1:parcelCode>RR950819194CZ</v1_1:parcelCode>
+          <v1_1:parcelDataResponse>
+            <v1_1:responseCode>1</v1_1:responseCode>
+            <v1_1:responseText>OK</v1_1:responseText>
+          </v1_1:parcelDataResponse>
+        </v1_1:resultParcelData>
+      </v1_1:responseHeader>
+    </v1_1:parcelServiceSyncResponse></v1:serviceData>
+</v1:b2bSyncResponse>
+```
+
+*Reality is, that Parcel IS NOT registered!*
+
+They say, that this should be fixed in v1.10 release. But nobody knows, when it will be deployed. And I do not know if there is some public way how to find, which version is now in production.
+
+
 # CzechPostB2bClient
 Accessing B2B API of Czech Post for bulk processing of parcels ("B2B - WS PodáníOnline").
 
 There are these supported operations of API:
+- *parcelServiceSync* - stores data of one parcel and return package_code and optional PDF adress sheet [HTTP POST - sync response]
+                        Seems to me, that there are is no place extensive Cash On Delivery data, just `amount` and `currency`
 - *sendParcels* - stores data of parcels for async processing [HTTP POST - async response]
 - *getResultParcels* - return results of such processing [HTTP GET - sync response]
 - *getStats* - returns statistics of parcels sent in time period [HTTP GET - sync response]
 - *getParcelState* - returns all known states for listed parcels [HTTP GET - sync response]
 - *getParcelsPrinting* - returns PDF with address labels/stickers for listed parcels [HTTP GET - sync response]
 
+## Development of this gem is donated by [Squared s.r.o.](https://www.vyvolej.to)
+
 ## Installation
 ### 1) Registration at Czech Post (CP)
 The longterm and hardest part.
@@ -35,216 +76,237 @@ gem 'czech_post_b2b_client'
 
 And then execute:
 
-    $ bundle
+```
+$ bundle
+```
 
 Or install it yourself as:
 
     $ gem install czech_post_b2b_client
 
 ### 4) Setting up gem
-   Set up your `contract_id`, `customer_id` (both from CP signed contract), `certificate_path`, `private_key_path` and `private_key_password` in configuration:
-   ```
-    CzechPostB2bClient.configure do |config|
-      config.contract_id = 'contract_id'
-      config.customer_id = 'customer_id'
-      config.certificate_path = 'full_path/to/your/postsignum_certificate.pem'
-      config.private_key_path = 'full_path/to/your/postsignum_private.key'
-      config.private_key_password = 'your_password or nil'
-
-      # this actually do not work, I have to use `sending_post_office_location_number`. But it is REQUIRED!
-      config.sending_post_office_code = 12_345 # PSC of post office where parcels will be physically delivered and submitted
-
-      # and You can override defaults
-      # config.sending_post_office_location_number => 1
-      # config.namespaces #XML namespaces
-      # config.language => :cs # other languages are not supported now
-      # config.logger => ::Rails.logger or ::Logger.new(STDOUT),
-      # config.b2b_api_base_uri => 'https://b2b.postaonline.cz/services/POLService/v1'
-    end
-   ```
-
-   - `contract_id` is _"ID CČK"_ (can be found in contract; eg.: _"2511327004"_)
-   - `customer_id` is _"Technologické číslo"_ (can be found in contract; eg.: _"U123"_ or _"L03022"_; also is visible at [PodaníOnline](https://www.postaonline.cz/podanionline/PrednastaveniUdajuZasilky.action)
-
-   Because PostSignum Certificate Authority is not trusted by default, correct certificate chain is in `certs/` folder. If You have problem with them, create a issue here. Maybe they are outdated now.
+Set up your `contract_id`, `customer_id` (both from CP signed contract), `certificate_path`, `private_key_path` and `private_key_password` in configuration:
+```
+CzechPostB2bClient.configure do |config|
+  config.contract_id = 'contract_id'
+  config.customer_id = 'customer_id'
+  config.certificate_path = 'full_path/to/your/postsignum_certificate.pem'
+  config.private_key_path = 'full_path/to/your/postsignum_private.key'
+  config.private_key_password = 'your_password or nil'
+
+  # these two just save Your time, can be overwritten for each call
+  config.custom_card_number = 'ABCD123456'
+  config.print_options = { template_id: 21, # 'adresní štítek bianco - samostatný'
+                           margin_in_mm: { top: 0, left: 0 } }
+
+  # this actually do not work, I have to use `sending_post_office_location_number`. But it is REQUIRED!
+  config.sending_post_office_code = 12_345 # PSC of post office where parcels will be physically delivered and submitted
+
+  # and You can override defaults
+  # config.sending_post_office_location_number => 1
+  # config.namespaces #XML namespaces
+  # config.language => :cs # other languages are not supported now
+  # config.logger => ::Rails.logger or ::Logger.new(STDOUT),
+  # config.b2b_api_base_uri => 'https://b2b.postaonline.cz/services/POLService/v1'
+  # config.log_messages_at_least_as = :debug
+end
+```
+
+- `contract_id` is _"ID CČK"_ (can be found in contract; eg.: _"2511327004"_)
+- `customer_id` is _"Technologické číslo"_ (can be found in contract; eg.: _"U123"_ or _"L03022"_; also is visible at [PodaníOnline](https://www.postaonline.cz/podanionline/PrednastaveniUdajuZasilky.action)
+
+Because PostSignum Certificate Authority is not trusted by default, correct certificate chain is in `certs/` folder. If You have problem with them, create a issue here. Maybe they are outdated now.
 
 ## Usage
-  **You have to know which parcel type (according to CP) you sending!** Eg. 'BA' or 'RR'. See [`documents/parcel_types.md`](./documents/parcel_types.md).
-
-  **And what services You will use for each parcel**, see [`documents/services_list.md`](./documents/services_list.md) and [`documents/parcels_type_and_services_restrictions.md`](./documents/parcels_type_and_services_restrictions.md).
-
-  Hashes used is service calls bellow:
-  ```
-    short_sender_data = { address: {
-                            company_name: 'Oriflame',
-                            addition_to_name: 'perfume', # optional
-                            street: 'V olšinách',
-                            house_number: '16',
-                            city_part: 'Strašnice',
-                            city: 'Praha',
-                            post_code: 10_000,
-                          },
-                          mobile_phone: '+420777888999',
-                          email: 'rehor.jan@cpost.cz' }
-    sending_data = { contract_id: configuration.contract_id,
-                     parcels_sending_date: Date.today,
-                     sending_post_office_location_number: 1,
-                     sender: short_sender_data,
-                     cash_on_delivery: {
-                       address: short_sender_data[:address]
-                       bank_account: '123456-1234567890/1234'
-                     } }
-
-    short_addressee_data = { address: {
-                              first_name: 'Petr',
-                              last_name: 'Foton',
-                              street: 'Fischerova',
-                              house_number: '686',
-                              sequence_number: '32',
-                              city_part: 'Nové Sady',
-                              city: 'Olomouc',
-                              post_code: 77_900
-                            },
-      email: 'foton@github.com',
-      mobile_phone: '+420777888999' }
-
-    parcels = [
-      {
-        addressee: short_addressee_data,
-        params: { parcel_id: 'package_1of2',
-                  parcel_code_prefix: 'BA',
-                  weight_in_kg: 1.0,
-                  parcel_order: 1,
-                  parcels_count: 2 },
-        services: [70, 7, 'S']
-      },
-      {
-        addressee: short_addressee_data,
-        params: { parcel_id: 'package_2of2',
-                  parcel_code_prefix: 'BA',
-                  weight_in_kg: 1.6,
-                  parcel_order: 2,
-                  parcels_count: 2 },
-        services: [70,'S']
-      },
-      {
-        addressee: short_addressee_data,
-        params: { parcel_id: 'package_3',
-                  parcel_code_prefix: 'BA',
-                  weight_in_kg: 1.9 },
-        services: [7,'M']
-      }
-    ]
+**You have to know which parcel type (according to CP) you sending!** Eg. 'BA' or 'RR'. See [`documents/parcel_types.md`](./documents/parcel_types.md).
+
+**And what services You will use for each parcel**, see [`documents/services_list.md`](./documents/services_list.md) and [`documents/parcels_type_and_services_restrictions.md`](./documents/parcels_type_and_services_restrictions.md).
+
+Hashes used is service calls bellow:
+
+```
+short_sender_data = { address: {
+                        company_name: 'Oriflame',
+                        addition_to_name: 'perfume', # optional
+                        street: 'V olšinách',
+                        house_number: '16',
+                        city_part: 'Strašnice',
+                        city: 'Praha',
+                        post_code: 10_000,
+                      },
+                      mobile_phone: '+420777888999',
+                      email: 'rehor.jan@cpost.cz' }
+sending_data = { contract_id: configuration.contract_id,
+                  parcels_sending_date: Date.today,
+                  sending_post_office_location_number: 1,
+                  sender: short_sender_data,
+                  cash_on_delivery: {
+                    address: short_sender_data[:address]
+                    bank_account: '123456-1234567890/1234'
+                  } }
+
+short_addressee_data = { address: {
+                          first_name: 'Petr',
+                          last_name: 'Foton',
+                          street: 'Fischerova',
+                          house_number: '686',
+                          sequence_number: '32',
+                          city_part: 'Nové Sady',
+                          city: 'Olomouc',
+                          post_code: 77_900
+                        },
+  email: 'foton@github.com',
+  mobile_phone: '+420777888999' }
+
+parcels = [
+  {
+    addressee: short_addressee_data,
+    params: { parcel_id: 'package_1of2',
+              parcel_code_prefix: 'BA',
+              weight_in_kg: 1.0,
+              parcel_order: 1,
+              parcels_count: 2 },
+    services: [70, 7, 'S']
+  },
+  {
+    addressee: short_addressee_data,
+    params: { parcel_id: 'package_2of2',
+              parcel_code_prefix: 'BA',
+              weight_in_kg: 1.6,
+              parcel_order: 2,
+              parcels_count: 2 },
+    services: [70,'S']
+  },
+  {
+    addressee: short_addressee_data,
+    params: { parcel_id: 'package_3',
+              parcel_code_prefix: 'BA',
+              weight_in_kg: 1.9 },
+    services: [7,'M']
+  }
+]
+```
+
+
+1 ) Pack your parcel(s)
+
+2 ) If you have many parcels and treats them as bulk, use ASYNC registration process (steps 3a - 7a)[15 000 calls per day allowed]. If You want to register parcel and get  parcel_code and address sheet immediatelly (3 sec), use SYNC process (step 3b)[1 000 calls per day allowed]
+
+3a) Call `ParcelsAsyncSender`, this will setup `transmission_id` and expected time to ask for results.
+```
+psender = CzechPostB2bClient::Services::ParcelsAsyncSender.call(sending_data: sending_data, parcels: parcels)
+
+if psender.success?
+  result = psender.result
+  processing_end_time_utc = (result.processing_end_expected_at - (60 *60)).utc # API returns time in CET but marked as UTC
+  transaction_id = result.transaction_id
+else
+  puts psender.errors.full_messages
+end
 ```
+For now, `parcels` is array of complicated hashes; each parcel must have `parcel_id` key (your ID of parcel).
 
+4a) When such expected time pass, ask for results by calling `ParcelsSendProcessUpdater`. You can get error `Processing is not yet finished` or hash based on `parcel_id` keys.
+```
+pudater = CzechPostB2bClient::Services::ParcelsSendProcessUpdater.call(transmission_id: transmission_id)
+
+if pupdater.success?
+  update_my_parcels_with(pupdater.result) # => { 'parcel_1of2' => { parcel_code: 'BA12354678', states: [{ code: 1, text: 'OK' }]},
+                                          #      'parcel_2of2' => { parcel_code: 'BA12354679', states: [{ code: 1, text: 'OK' }]},
+                                          #      'parcel_3' => { parcel_code: 'BA12354680', states: [{ code: 1, text: 'OK' }]}
+else
+  puts psender.errors.full_messages # => "response_state: ResponseCode[19 BATCH_INVALID] V dávce se vyskytují chybné záznamy"
+                                    #    "parcels: Parcel[parcel_2of2] => ResponseCode[104 INVALID_WEIGHT] Hmotnost mimo povolený rozsah"
+                                    #    "parcels: Parcel[parcel_2of2] => ResponseCode[261 MISSING_SIZE_CATEGORY] Neuvedena rozměrová kategorie zásilky"
+                                    #    "parcels: Parcel[parcel_3] => ResponseCode[310 INVALID_PREFIX] Neplatný typ zásilky"
+end
+```
+`parcel_code` is CzechPost Tracking number of parcel and is used in following calls.
 
-  1) Pack your parcel(s)
-
-  2) Call `ParcelsSender`, this will store in `result` `transmission_id` and expected time to ask for results.
-      ```
-        psender = CzechPostB2bClient::Services::ParcelsSender.call(sending_data: sending_data, parcels: parcels)
-
-        if psender.success?
-          result = psender.result
-          processing_end_time_utc = (result.processing_end_expected_at - (60 *60)).utc # API returns time in CET but marked as UTC
-          transaction_id = result.transaction_id
-        else
-          puts psender.errors.full_messages
-        end
-      ```
-     For now, `parcels` is array of complicated hashes; each parcel must have `parcel_id` key (your ID of parcel).
-
-  3) When such expected time pass, ask for results by calling `ParcelsSendProcessUpdater`.
-
-     You can get error `Processing is not yet finished` or hash based on `parcel_id` keys.
-     Eg. :
-     ```
-        pudater = CzechPostB2bClient::Services::ParcelsSendProcessUpdater.call(transmission_id: transmission_id)
-
-        if pupdater.success?
-          update_my_parcels_with(pupdater.result) # => { 'parcel_1of2' => { parcel_code: 'BA12354678', states: [{ code: 1, text: 'OK' }]},
-                                                  #      'parcel_2of2' => { parcel_code: 'BA12354679', states: [{ code: 1, text: 'OK' }]},
-                                                  #      'parcel_3' => { parcel_code: 'BA12354680', states: [{ code: 1, text: 'OK' }]}
-        else
-          puts psender.errors.full_messages # => "response_state: ResponseCode[19 BATCH_INVALID] V dávce se vyskytují chybné záznamy"
-                                            #    "parcels: Parcel[parcel_2of2] => ResponseCode[104 INVALID_WEIGHT] Hmotnost mimo povolený rozsah"
-                                            #    "parcels: Parcel[parcel_2of2] => ResponseCode[261 MISSING_SIZE_CATEGORY] Neuvedena rozměrová kategorie zásilky"
-                                            #    "parcels: Parcel[parcel_3] => ResponseCode[310 INVALID_PREFIX] Neplatný typ zásilky"
-        end
-     ```
-     `parcel_code` is CzechPost ID of parcel and is used in following calls.
-
-  4) Print address sheets of parcels(s) by calling `AddressSheetsGenerator`.
-     See [template_classes](./lib/czech_post_b2b_client/printing_templates.rb) for available templates.
-     Eg. :
-     ```
-     parcel_codes = %w[RA123456789 RR123456789F RR123456789G] # beware of parcel_id!
-     options = {
-          customer_id: configuration.customer_id, # required
-          contract_number: configuration.contract_id, # not required
-          template_id: 24, # 'obalka 3 - B4'  #
-          margin_in_mm: { top: 5, left: 3 } # required
-        }
-
-      adrprinter = CzechPostB2bClient::Services::AddressSheetsGenerator.call(parcel_codes: parcel_codes, options: options )
-
-      if adrprinter.success?
-        File.write("adrsheet.pdf", adrprinter.result.pdf_content)
-      else
-        puts(adrprinter.errors.full_messages)
-      end
-     ```
-
-  5) Repeat steps 1-4 until You decide to deliver packages to post office.
-
-  6) Close your parcels submission with call `ParcelsSubmissionCloser.call(sending_data: sender_data)`.
-
-  7) _They will await You at post office with warm welcome (hopefully). Parcels which are not delivered within 60 days are removed from CzechPost systems for free :-)_
-
-  8) You can check current status of delivering with `DeliveringInspector`, which will return hash based on `parcel_code` keys.
-     Eg. :
-     ```
-      delivery_boy = CzechPostB2bClient::Services::DeliveringInspector.call(parcel_codes: parcel_codes)
-
-      if delivery_boy.success?
-        update_my_parcels_delivery_status_with(delivery_boy.result)
-        # result is like:
-        # { 'RA12345687' => { current_state: { id: '91',
-                                               date: Date.parse('2015-09-04'),
-                                               text: 'Dodání zásilky.',
-                                               post_code: '25756',
-                                               post_name: 'Neveklov'},
-                              deposited_until: Date.new(2015, 9, 2),
-                              deposited_for_days: 15,
-                              all_states: [
-                                { id: '21', date: Date.parse('2015-09-02'), text: 'Podání zásilky.', post_code: '26701', post_name: 'Králův Dvůr u Berouna' },
-                                { id: '-F', date: Date.parse('2015-09-03'), text: 'Vstup zásilky na SPU.', post_code: '22200', post_name: 'SPU Praha 022' },
-                                { id: '-I', date: Date.parse('2015-09-03'), text: 'Výstup zásilky z SPU.', post_code: '22200', post_name: 'SPU Praha 022' },
-                                { id: '-B', date: Date.parse('2015-09-03'), text: 'Přeprava zásilky k dodací poště.', post_code: nil, post_name: nil },
-                                { id: '51', date: Date.parse('2015-09-04'), text: 'Příprava zásilky k doručení.', post_code: '25607', post_name: 'Depo Benešov 70' },
-                                { id: '53', date: Date.parse('2015-09-04'), text: 'Doručování zásilky.', post_code: '25756', post_name: 'Neveklov' },
-                                { id: '91', date: Date.parse('2015-09-04'), text: 'Dodání zásilky.', post_code: '25756', post_name: 'Neveklov' }
-                              ]},
-            'BA56487125' => {...}
-          }
-      else
-        puts(delivery_boy.errors.full_messages)
-      end
-      ```
-
-  9) And You can always ask for statistics!
-      ```
-      tps = CzechPostB2bClient::Services::TimePeriodStatisticator.call(from_date: Date.today - 5, to_date: Date.today)
-      if tps.success?
-        result = tps.result
-        result.requests.total # => 26,
-        result.requests.with_errors # => 16
-        result.requests.successful # => 10
-        result.imported_parcels # => 3
-      else
-        puts(tps.errors.full_messages)
-      end
-      ```
+5a) Print address sheets of parcel(s) by calling `AddressSheetsGenerator`.
+See [template_classes](./lib/czech_post_b2b_client/printing_templates.rb) for available templates.
+```
+parcel_codes = %w[RA123456789 RR123456789F RR123456789G] # beware of parcel_id!
+options = {
+    customer_id: configuration.customer_id, # required
+    contract_number: configuration.contract_id, # not required
+    template_id: 24, # 'obalka 3 - B4'  #
+    margin_in_mm: { top: 5, left: 3 } # required
+  }
+
+adrprinter = CzechPostB2bClient::Services::AddressSheetsGenerator.call(parcel_codes: parcel_codes, options: options )
+
+if adrprinter.success?
+  File.write("adrsheet.pdf", adrprinter.result.pdf_content)
+else
+  puts(adrprinter.errors.full_messages)
+end
+```
+
+6a) Repeat steps 1-4 until You decide to deliver packages to post office.
+
+7a) Close your parcels submission with call `ParcelsSubmissionCloser.call(sending_data: sender_data)`.
+
+3b) For immediate (one) parcel registering call `ParcelsSyncSender`. You can optionally request address sheet pdf in response (see step 5a for info)
+```
+s_data = sending_data.merge(print_params: { template_id: 40, margin_in_mm: { top: 1, left: 1 }})
+psender = CzechPostB2bClient::Services::ParcelsSyncSender.call(sending_data: s_data, parcels: [parcels.first])
+
+if psender.success?
+  result = psender.result
+  update_my_parcels_with(result) # => { 'parcel_1of2' => { parcel_code: 'BA12354678', states: [{ code: 1, text: 'OK' }]},
+  File.write("adrsheet.pdf", result.pdf_content)
+else
+  puts psender.errors.full_messages
+end
+```
+`parcel_code` is CzechPost Tracking number of parcel and is used in following calls.
+
+8_) _They will await You at post office with warm welcome (hopefully). Parcels which are not delivered within 60 days are removed from CzechPost systems for free :-)_
+
+9_) You can check current status of delivering with `DeliveringInspector`, which will return hash based on `parcel_code` keys.
+```
+delivery_boy = CzechPostB2bClient::Services::DeliveringInspector.call(parcel_codes: parcel_codes)
+
+if delivery_boy.success?
+  update_my_parcels_delivery_status_with(delivery_boy.result)
+  # result is like:
+  # { 'RA12345687' => { current_state: { id: '91',
+                                          date: Date.parse('2015-09-04'),
+                                          text: 'Dodání zásilky.',
+                                          post_code: '25756',
+                                          post_name: 'Neveklov'},
+                        deposited_until: Date.new(2015, 9, 2),
+                        deposited_for_days: 15,
+                        all_states: [
+                          { id: '21', date: Date.parse('2015-09-02'), text: 'Podání zásilky.', post_code: '26701', post_name: 'Králův Dvůr u Berouna' },
+                          { id: '-F', date: Date.parse('2015-09-03'), text: 'Vstup zásilky na SPU.', post_code: '22200', post_name: 'SPU Praha 022' },
+                          { id: '-I', date: Date.parse('2015-09-03'), text: 'Výstup zásilky z SPU.', post_code: '22200', post_name: 'SPU Praha 022' },
+                          { id: '-B', date: Date.parse('2015-09-03'), text: 'Přeprava zásilky k dodací poště.', post_code: nil, post_name: nil },
+                          { id: '51', date: Date.parse('2015-09-04'), text: 'Příprava zásilky k doručení.', post_code: '25607', post_name: 'Depo Benešov 70' },
+                          { id: '53', date: Date.parse('2015-09-04'), text: 'Doručování zásilky.', post_code: '25756', post_name: 'Neveklov' },
+                          { id: '91', date: Date.parse('2015-09-04'), text: 'Dodání zásilky.', post_code: '25756', post_name: 'Neveklov' }
+                        ]},
+      'BA56487125' => {...}
+    }
+else
+  puts(delivery_boy.errors.full_messages)
+end
+```
+
+10_) And You can always ask for statistics!
+```
+tps = CzechPostB2bClient::Services::TimePeriodStatisticator.call(from_date: Date.today - 5, to_date: Date.today)
+if tps.success?
+  result = tps.result
+  result.requests.total # => 26,
+  result.requests.with_errors # => 16
+  result.requests.successful # => 10
+  result.imported_parcels # => 3
+else
+  puts(tps.errors.full_messages)
+end
+```
 
 ### Example usage
 
@@ -254,6 +316,8 @@ Or install it yourself as:
 
 ## Troubleshooting
 
+  You can validate request XML against XSD in [`documents/latest_xsds`](./documents/latest_xsds) (There are no public  files from Czech Post :-( )
+
   1) Read all stuff in [`./documents`](./documents/) and [Yard docs](./doc/index.html), maybe it helps.
   2) If You get "handshake protocol failed" You do not have correct setup for certificates. If You get any xml response (see logger in debug mode) certificates are ok.
      You can always try `TimePeriodStatisticator` for that check, it do not need any "before" actions.
@@ -261,6 +325,8 @@ Or install it yourself as:
   4) Error `11: INVALID_LOCATION` was occuring when only `sending_post_office_code` was used. Try to use `sending_post_office_location_number`.
   5) And last tip `261 MISSING_SIZE_CATEGORY` -> add correct "size service" to services (eg: 'S', 'M')
   6) Compare resulting request XML with examples in `test/request_builders`
+  7) If You get strings like `"Obdr\xC5\xBEeny \xC3\xBAdaje k z\xC3\xA1silce."` instead of `"Obdrženy údaje k zásilce."`, You need to `str.force_encoding('UTF-8')`. It happens to me, after I started to use gem in app. Something like backward influence.
+
 
 ## Development