cin7_core_api 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 237cda18aeb79904a6fed79dc9deaa53240aff6d45f659d0163f14188af06126
-  data.tar.gz: 3ba7316e959ec28916abb55e3036e0550d68ce626be3c0ac08fc80eda8a8bfb8
+  metadata.gz: bebb9103f8de0eff128f3225cb97eeacca8137b6501f09051858053e79443cf6
+  data.tar.gz: 27a765beb403a6279b6d74d25952688b304252e3308b22b47ada21f46c920401
 SHA512:
-  metadata.gz: caff2995e25a658cd0aaf75513389850a0347a8aa4fc0f38ee3b99015a2e02a9bccd758edecedb4187f06fbd2360bb25ae6ce944a10b1a7fc6fc454f1c02910c
-  data.tar.gz: 932d8ea1d610710377946799c1224e099b3e4d6b5cf6b99d5ac32b01e28d7a07cb7bdd563291246430126f01e07f295dd8a1d70d235708ea8a8ed2f527d0b563
+  metadata.gz: d007332b45d5a02e5810eabd256b24c77156e34fd737c3d68cf671608a9a149978380b21c9398be56d72430fa0ad3beaf28d56015c404b564a3bb838d98f1cb1
+  data.tar.gz: 3be8c44fc59d964e1fea08eede44326e6a38eff0885f7426c11986f23a383901c6215181b1fcca04f17306c667e2ce300336661e24e72e4d3a55d3f93529d5aa

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.3.0] - 2026-10-02
+
+- Add explicit credit-note creation/undo and Advanced Sale fulfilment, pick, pack and shipment resources with readback and distinct POST/PUT semantics.
+- Add sale-header creation plus product, stock availability and carrier reads so sandbox preparation uses resource methods throughout.
+- Preserve caller-supplied task IDs, monetary values, restock and shipment collections; do not select eligibility, append lines or restore inventory implicitly.
+
 ## [0.2.1] - 2026-10-02
 
 - Keep decompression failures and malformed UTF-8 responses, including invalid decoded JSON strings, inside the sanitized error contract, preserving uncertain-write recovery without retries.

data/README.md

@@ -9,7 +9,7 @@ Version `0.2.0` adds explicit payment, order, invoice, journal, and webhook oper
 Add the gem to your Gemfile:
 
 ```ruby
-gem "cin7_core_api", "0.2.1"
+gem "cin7_core_api", "0.3.0"
 ```
 
 Then run:
@@ -22,6 +22,38 @@ Ruby 3.3 or newer is required.
 
 Version `0.2.1` adds response-decoding safety and callback-identity fixes. Published `0.2.0` remains unchanged. Check RubyGems for publication availability; to evaluate a reviewed source before publication, pin its full commit SHA from this repository.
 
+Version `0.3.0` adds the explicit native correction and sandbox preparation resources below. It includes the `0.2.1` safety fixes.
+
+## Native correction and sandbox preparation
+
+These methods use the same sanitized errors and never retry. Payloads use Cin7 String field names. `sale_id:` identifies the parent sale; `task_id:` identifies the particular credit-note or fulfilment task.
+
+| Resource method | HTTP contract |
+| --- | --- |
+| `sales.create(payload:)` | POST `sale`; create a header with caller-selected customer, sale type and options |
+| `credit_notes.create(payload:)` | POST `sale/creditnote`; explicit `SaleID` and `TaskID` |
+| `credit_notes.undo(task_id:)` | DELETE `sale/creditnote` with `TaskID` and `Void=false` |
+| `fulfilments.for_sale(sale_id:, include_product_info: false)` | GET `sale/fulfilment`; preserve its `Fulfilments` response collection |
+| `fulfilments.create(payload:)` | POST `sale/fulfilment`; explicit `SaleID` |
+| `fulfilments.undo(task_id:)` | DELETE `sale/fulfilment` with `TaskID` and `Void=false` |
+| `picks.for_task(task_id:, include_product_info: false)` | GET `sale/fulfilment/pick` |
+| `packs.for_task(task_id:, include_product_info: false)` | GET `sale/fulfilment/pack` |
+| `shipments.for_task(task_id:)` | GET `sale/fulfilment/ship` |
+| `picks.create/update(payload:)` | POST/PUT `sale/fulfilment/pick`; explicit `TaskID` |
+| `packs.create/update(payload:)` | POST/PUT `sale/fulfilment/pack`; explicit `TaskID` |
+| `shipments.create/update(payload:)` | POST/PUT `sale/fulfilment/ship`; explicit `TaskID` |
+| `products.list(**filters)` | GET `product`; supports documented product discovery filters |
+| `product_availability.list(**filters)` | GET `ref/productavailability`; `page`, `limit`, `id`, `name`, `sku`, `location`, `batch`, `category` |
+| `carriers.list(**filters)` | GET `ref/carrier`; `page`, `limit`, `carrier_id`, `description` |
+
+Cin7 documents credit-note **POST**, not PUT. Use `create` for an explicit new task or a draft/not-available task; it does not overwrite an authorised note by itself. For a new note, the caller may supply the documented empty GUID `TaskID`; the gem never chooses or inserts it. Forward complete `Lines`, `AdditionalCharges` and `Restock` collections deliberately.
+
+The provider's credit-note DELETE eligibility is unusually narrow and duplicated in its Blueprint: Advanced Sale with credit-note `TaskID = SaleID`. Its applicability to connector-created secondary notes is unproven. Exposing `undo` does not establish that a particular paid, taxed or restocked note can be rebuilt safely. The caller must inspect state, preserve payouts and inventory ownership, check the actual rejection/readback and recover uncertain outcomes before proceeding.
+
+Fulfilment `create` can convert a Simple Sale to Advanced Sale. Pack and shipment **POST may append lines**, while **PUT replaces** eligible draft/not-available documents. Shipment PUT must include all required packed boxes. The caller must preserve quantities, locations, batches, boxes and shipment identity and verify inventory after any restoration. The gem does not authorise a previously fulfilled sale correction or run pick/pack/ship automatically.
+
+The `products` filters are `id`, `page`, `limit`, `name`, `sku`, `modified_since`, `include_deprecated`, `include_bom`, `include_suppliers`, `include_movements`, `include_attachments`, `include_reorder_levels`, and `include_custom_prices`. Nil filters are omitted, boolean false is retained, and unsupported filters fail before dispatch.
+
 ## Authentication
 
 Create a client using the Account ID and API Application Key from CIN7 Core's API setup page:

data/lib/cin7_core_api/client.rb

@@ -89,6 +89,34 @@ module Cin7CoreAPI
       @webhooks ||= Resources::Webhooks.new(connection)
     end
 
+    def fulfilments
+      @fulfilments ||= Resources::Fulfilments.new(connection)
+    end
+
+    def picks
+      @picks ||= Resources::Picks.new(connection)
+    end
+
+    def packs
+      @packs ||= Resources::Packs.new(connection)
+    end
+
+    def shipments
+      @shipments ||= Resources::Shipments.new(connection)
+    end
+
+    def products
+      @products ||= Resources::Products.new(connection)
+    end
+
+    def product_availability
+      @product_availability ||= Resources::ProductAvailability.new(connection)
+    end
+
+    def carriers
+      @carriers ||= Resources::Carriers.new(connection)
+    end
+
     def inspect
       "#<#{self.class}>"
     end

data/lib/cin7_core_api/resources/carriers.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Carriers < Base
+      PARAMETERS = {page: "Page", limit: "Limit", carrier_id: "CarrierID", description: "Description"}.freeze
+
+      def list(**filters)
+        get("ref/carrier", params: filters, parameter_map: PARAMETERS)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/credit_notes.rb

@@ -29,6 +29,16 @@ module Cin7CoreAPI
         require_parameter!(:sale_id, sale_id)
         get("sale/creditnote", params: options.merge(sale_id: sale_id), parameter_map: FOR_SALE_PARAMETERS)
       end
+
+      def create(payload:)
+        validate_payload!(payload, "SaleID", "TaskID")
+        connection.post("sale/creditnote", payload: payload)
+      end
+
+      def undo(task_id:)
+        require_parameter!(:task_id, task_id)
+        connection.delete("sale/creditnote", params: {"TaskID" => task_id, "Void" => false})
+      end
     end
   end
 end

data/lib/cin7_core_api/resources/fulfilments.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Fulfilments < Base
+      PARAMETERS = {sale_id: "SaleID", include_product_info: "IncludeProductInfo"}.freeze
+
+      def for_sale(sale_id:, **options)
+        require_parameter!(:sale_id, sale_id)
+        get("sale/fulfilment", params: options.merge(sale_id: sale_id), parameter_map: PARAMETERS)
+      end
+
+      def create(payload:)
+        validate_payload!(payload, "SaleID")
+        connection.post("sale/fulfilment", payload: payload)
+      end
+
+      def undo(task_id:)
+        require_parameter!(:task_id, task_id)
+        connection.delete("sale/fulfilment", params: {"TaskID" => task_id, "Void" => false})
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/packs.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Packs < Base
+      PARAMETERS = {task_id: "TaskID", include_product_info: "IncludeProductInfo"}.freeze
+
+      def for_task(task_id:, **options)
+        require_parameter!(:task_id, task_id)
+        get("sale/fulfilment/pack", params: options.merge(task_id: task_id), parameter_map: PARAMETERS)
+      end
+
+      def create(payload:)
+        validate_payload!(payload, "TaskID")
+        connection.post("sale/fulfilment/pack", payload: payload)
+      end
+
+      def update(payload:)
+        validate_payload!(payload, "TaskID")
+        connection.put("sale/fulfilment/pack", payload: payload)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/picks.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Picks < Base
+      PARAMETERS = {task_id: "TaskID", include_product_info: "IncludeProductInfo"}.freeze
+
+      def for_task(task_id:, **options)
+        require_parameter!(:task_id, task_id)
+        get("sale/fulfilment/pick", params: options.merge(task_id: task_id), parameter_map: PARAMETERS)
+      end
+
+      def create(payload:)
+        validate_payload!(payload, "TaskID")
+        connection.post("sale/fulfilment/pick", payload: payload)
+      end
+
+      def update(payload:)
+        validate_payload!(payload, "TaskID")
+        connection.put("sale/fulfilment/pick", payload: payload)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/product_availability.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class ProductAvailability < Base
+      PARAMETERS = {
+        page: "Page", limit: "Limit", id: "ID", name: "Name", sku: "Sku",
+        location: "Location", batch: "Batch", category: "Category"
+      }.freeze
+
+      def list(**filters)
+        get("ref/productavailability", params: filters, parameter_map: PARAMETERS)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/products.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Products < Base
+      PARAMETERS = {
+        id: "ID", page: "Page", limit: "Limit", name: "Name", sku: "Sku", modified_since: "ModifiedSince",
+        include_deprecated: "IncludeDeprecated", include_bom: "IncludeBOM", include_suppliers: "IncludeSuppliers",
+        include_movements: "IncludeMovements", include_attachments: "IncludeAttachments",
+        include_reorder_levels: "IncludeReorderLevels", include_custom_prices: "IncludeCustomPrices"
+      }.freeze
+
+      def list(**filters)
+        get("product", params: filters, parameter_map: PARAMETERS)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/sales.rb

@@ -41,6 +41,11 @@ module Cin7CoreAPI
         get("sale", params: options.merge(id: id), parameter_map: RETRIEVE_PARAMETERS)
       end
 
+      def create(payload:)
+        validate_payload!(payload)
+        connection.post("sale", payload: payload)
+      end
+
       def update(payload:)
         validate_payload!(payload, "ID")
         connection.put("sale", payload: payload)

data/lib/cin7_core_api/resources/shipments.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Shipments < Base
+      def for_task(task_id:)
+        require_parameter!(:task_id, task_id)
+        get("sale/fulfilment/ship", params: {task_id: task_id}, parameter_map: {task_id: "TaskID"})
+      end
+
+      def create(payload:)
+        validate_payload!(payload, "TaskID")
+        connection.post("sale/fulfilment/ship", payload: payload)
+      end
+
+      def update(payload:)
+        validate_payload!(payload, "TaskID")
+        connection.put("sale/fulfilment/ship", payload: payload)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cin7CoreAPI
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/lib/cin7_core_api.rb

@@ -21,6 +21,13 @@ require_relative "cin7_core_api/resources/manual_journals"
 require_relative "cin7_core_api/resources/journals"
 require_relative "cin7_core_api/resources/tax_rules"
 require_relative "cin7_core_api/resources/webhooks"
+require_relative "cin7_core_api/resources/fulfilments"
+require_relative "cin7_core_api/resources/picks"
+require_relative "cin7_core_api/resources/packs"
+require_relative "cin7_core_api/resources/shipments"
+require_relative "cin7_core_api/resources/products"
+require_relative "cin7_core_api/resources/product_availability"
+require_relative "cin7_core_api/resources/carriers"
 require_relative "cin7_core_api/client"
 
 module Cin7CoreAPI

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cin7_core_api
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - PostCo
@@ -123,17 +123,24 @@ files:
 - lib/cin7_core_api/resources/accounts.rb
 - lib/cin7_core_api/resources/bank_accounts.rb
 - lib/cin7_core_api/resources/base.rb
+- lib/cin7_core_api/resources/carriers.rb
 - lib/cin7_core_api/resources/credit_notes.rb
 - lib/cin7_core_api/resources/customer_credits.rb
 - lib/cin7_core_api/resources/customers.rb
+- lib/cin7_core_api/resources/fulfilments.rb
 - lib/cin7_core_api/resources/invoices.rb
 - lib/cin7_core_api/resources/journals.rb
 - lib/cin7_core_api/resources/locations.rb
 - lib/cin7_core_api/resources/manual_journals.rb
 - lib/cin7_core_api/resources/me.rb
 - lib/cin7_core_api/resources/orders.rb
+- lib/cin7_core_api/resources/packs.rb
 - lib/cin7_core_api/resources/payments.rb
+- lib/cin7_core_api/resources/picks.rb
+- lib/cin7_core_api/resources/product_availability.rb
+- lib/cin7_core_api/resources/products.rb
 - lib/cin7_core_api/resources/sales.rb
+- lib/cin7_core_api/resources/shipments.rb
 - lib/cin7_core_api/resources/tax_rules.rb
 - lib/cin7_core_api/resources/webhooks.rb
 - lib/cin7_core_api/response.rb