czech_post_b2b_client 1.1.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 07426ba1b8f688f648faebda86173b514127a3b9
-  data.tar.gz: 8cfd179622eaa1aac8b0043acf01089a9d66e1b9
+  metadata.gz: 195b8ec3ce8eb8a50a8e930a2629917fb7a452d9
+  data.tar.gz: b78e4f92cc14b98265ab6d595fa7c2011ec32208
 SHA512:
-  metadata.gz: 538d4a70a50d9b48d3740e67eadcdd82ea8965acd321cbb9bb690ed7cb987966bc03f757ccff7115d67287a581f6dd53a0e948ea14a70168a95e89bb1236c330
-  data.tar.gz: 5549ec8f20778309738add18ec827a4b20cb449a307e1825e7bd1b2891608129ef1f806e4e73eb101e700640a57d76e0f79f7c0275a291a993f9addcab80bb49
+  metadata.gz: 54ef2187484cf754ee7fd92f903e3252472da1d30af90927ee64af447bea861df97581342af4dfe9d7193a123bd1a4c2d4f35ea2253836eb74bd2b4c1d05092b
+  data.tar.gz: b72195f63bb3153ae95473211f68756ea162599e4f617e7b77d5e93ca35b3eb5eb5bfc4fa83cdd496a4a4b7d2b8bece76eb8b255e3f77c4a4bbe16510e3dd510

data/CHANGELOG.md

@@ -2,11 +2,21 @@
 
 All changes to the gem are documented here.
 
+## [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

@@ -38,216 +38,236 @@ 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'
+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).
 
-  1) Pack your parcel(s)
-
-  2) Call `ParcelsAsyncSender`, this will store in `result` `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).
-
-  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
-      ```
+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.
+
+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
 
@@ -264,6 +284,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