magento 0.24.0 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cc3c4705cb31c6aab0ee3e39b0513bd9e21fa7f98fa6c0564e832a01c488b68
-  data.tar.gz: 20354ed49b5e998940775d8e3f07aea5ca0a0e2be5d482634c77528f3209e330
+  metadata.gz: b6aec96b1878cf98094666a1c656840c7cc1a8f7f08fea94ec597333b5ea32b9
+  data.tar.gz: 39959ab9be096fb11a8d0a13a48a957f5fc7c8ab78cd82014c586d3170c6e98a
 SHA512:
-  metadata.gz: 8e927a070c8b469cc0b3019ca27c9d74c51cb270b4165e3fb2343fd3c54d406d0d33507ad2aba9a53250d4c513e70eeb3c92adea579c0b2c775e23667e4fd1c8
-  data.tar.gz: f91fd2fcaca2777d599eac5eb665553adf5054eaa8a42593c2bad95226b953c43e14e1e7687e4c64c4351cc9f6e05fc35b3edd1e181fcd99976f481706e2d791
+  metadata.gz: e4387d0771f06cc23a980a730e0c3c94f7a67fd9fb4f370e89f7ab175bb21ff1ba9047eab9f56e79466b808bb2a07cda84454839d6783a28b3ef97646f47f273
+  data.tar.gz: 2ba0b2f46693f6584b5406e70442f5d3dd2235fb4ed2000fdd0a43533655f4d060989cb3493c58004a8dcc3714686b3246ff9a4f5e617e6d60e56e3de71506e8

data/.gitignore

@@ -7,7 +7,6 @@
 coverage
 InstalledFiles
 lib/bundler/man
-pkg
 rdoc
 spec/reports
 test/tmp
@@ -25,4 +24,7 @@ test/vcr_cassettes
 
 .vscode
 .byebug_history
-/manual_test
+/manual_test
+
+# rspec failure tracking
+.rspec_status

data/Gemfile

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in magento.gemspec
 gemspec
 
-gem "rake", "~> 12.0"
-gem "rspec", "~> 3.0"
 gem 'byebug', '~> 11.1', '>= 11.1.3'
+gem 'rake', '~> 12.0'
+gem 'rspec', '~> 3.0'
+gem 'vcr'
+gem 'webmock'

data/README.md

@@ -1,11 +1,83 @@
-# Magento Ruby library
-
-## Install
-
+# Magento 2 Ruby library
+
+Ruby library to consume the magento 2 api
+
+> Tested in version 2.3 of magento
+
+[Getting started](#getting-started)
+  - [Install](#install)
+  - [Setup](#setup)
+
+[Model common methods](#model-common-methods)
+  - [find](#find)
+  - [find_by](#find_by)
+  - [first](#first)
+  - [count](#count)
+  - [all](#count)
+  - [create](#create)
+  - [update](#update)
+  - [delete](#delete)
+
+[Search criteria](#search-criteria)
+  - [Select fields](#select-fields)
+  - [Filters](#filters)
+  - [Sort order](#sort-order)
+  - [Pagination](#pagination)
+- [Record Collection](#record-collection)
+
+**Additional methods**
+
+[Product](#product)
+  - [Shurtcuts](#shurtcuts)
+  - [Update stock](#update-stock)
+  - [Add media](#add-media-to-product)
+  - [Remove media](#remove-media-from-product)
+  - [Add tier price](#add-tier-price-to-product)
+  - [Remove tier price](#remove-tier-price-from-product)
+  - [Create links](#create-links-to-product)
+  - [Remove link](#remove-link-from-product)
+
+[Order](#order)
+  - [Invoice](#invoice-an-order)
+  - [Offline Refund](#create-offline-refund-for-order)
+  - [Creates new Shipment](#creates-new-shipment-for-given-order)
+  - [Cancel](#cancel-an-order)
+
+[Invoice](#invoice)
+  - [Refund](#create-refund-for-invoice)
+  - [Capture](#capture-an-invoice)
+  - [Void](#void-an-invoice)
+  - [Send email](#send-invoice-email)
+  - [Get comments](#get-invoice-comments)
+
+[Sales Rule](#sales-rule)
+  - [Generate Sales Rules and Coupons](#generate-sales-rules-and-coupons)
+
+[Customer](#customer)
+  - [Find by token](#get-customer-by-token)
+
+[Guest cart](#guest-cart)
+  - [Payment information](#payment-information)
+  - [Add Coupon](#add-coupon-to-guest-cart)
+  - [Remove Coupon](#remove-coupon-from-guest-cart)
+
+[Inventory](#invoice)
+  - [Check whether a product is salable](#check-whether-a-product-is-salable)
+  - [Check whether a product is salable for a specified quantity](#check-whether-a-product-is-salable-for-a-specified-quantity)
+
+**Helper classes**
+
+- [Create product params](#create-product-params)
+- [Create product image params](#create-product-image-params)
+- [Import products from csv file](#import-products-from-csv-file)
+
+## Getting started
+
+### Install
 Add in your Gemfile
 
 ```rb
-gem 'magento', '~> 0.24.0'
+gem 'magento', '~> 0.28.0'
 ```
 
 or run
@@ -28,96 +100,211 @@ Magento.with_config(store: :other_store) do # accepts store, url and token param
 end
 ```
 
-## Models
-```rb
-Magento::Product
-Magento::Order
-Magento::Country
-Magento::Category
-Magento::Customer
-```
+## Model common methods
+
+All classes that inherit from `Magento::Model` have the methods described below
+
+### `find`
 
-## Get details
+Get resource details with the `find` method
 
+Example:
 ```rb
 Magento::Product.find('sku-test')
 Magento::Order.find(25)
 Magento::Country.find('BR')
 ```
-\* _same pattern to all models_
 
-**Outside pattern**
+### `find_by`
 
-Get customer by token
+Returns the first resource found based on the argument passed
 
+Example:
 ```rb
-Magento::Customer.find_by_token('user_token')
+Magento::Product.find_by(name: 'Some product name')
+Magento::Customer.find_by(email: 'customer@email.com')
 ```
 
-## Shurtcut to get custom attribute value by custom attribute code in product
+### `first`
 
-Exemple:
+Returns the first resource found for the [search criteria](#search-criteria)
 
+Example:
 ```rb
-product.attr :description 
-# it is the same as
-product.custom_attributes.find { |a| a.attribute_code == 'description' }&.value
-
-# or
-product.description
+Magento::Order.where(grand_total_gt: 100).first
 ```
 
-when the custom attribute does not exists:
+### `count`
+
+Returns the total amount of the resource, also being able to use it based on the [search criteria](#search-criteria)
 
+Example:
 ```rb
-product.attr :special_price
-> nil
 
-product.special_price
-> NoMethodError: undefined method `special_price' for #<Magento::Product:...>
+Magento::Order.count
+>> 1500
+
+Magento::Order.where(status: :pending).count
+>> 48
 ```
 
+### `all`
+
+Used to get a list of a specific resource based on the [search criteria](#search-criteria).
+
+Returns a [Record Collection](#record-collection)
+
+Example:
 ```rb
-product.respond_to? :special_price
-> false
+# Default search criteria:
+#  page: 1
+#  page_size: 50
+Magento::Product.all
 
-product.respond_to? :description
-> true
+Magento::Product
+  .order(created_at: :desc)
+  .page_size(10)
+  .all
 ```
 
-## add tier price
+### `create`
 
-Add `price` on product `sku` for specified `customer_group_id`
+Creates a new resource based on reported attributes.
+
+Consult the magento documentation for available attributes for each resource:
 
-Param `quantity` is the minimun amount to apply the price
+Documentation links:
+- [Product](https://magento.redoc.ly/2.3.6-admin/tag/products#operation/catalogProductRepositoryV1SavePost)
+- [Category](https://magento.redoc.ly/2.3.6-admin/tag/categories#operation/catalogCategoryRepositoryV1SavePost)
+- [Order](https://magento.redoc.ly/2.3.6-admin/tag/orders#operation/salesOrderRepositoryV1SavePost)
+- [Customer](https://magento.redoc.ly/2.3.6-admin/tag/customers#operation/customerAccountManagementV1CreateAccountPost)
 
+Example:
 ```rb
-product = Magento::Product.find(1)
-product.add_tier_price(3.99, quantity: 1, customer_group_id: :all)
-> true
+Magento::Order.create(
+  customer_firstname: '',
+  customer_lastname: '',
+  customer_email: '',
+  # others attrbutes ...,
+  items: [
+    {
+      sku: '',
+      price: '',
+      qty_ordered: 1,
+      # others attrbutes ...,
+    }
+  ],
+  billing_address: {
+    # attrbutes...
+  },
+  payment: {
+    # attrbutes...
+  },
+  extension_attributes: {
+    # attrbutes...
+  }
+)
+```
 
-# OR
+#### `update`
 
-Magento::Product.add_tier_price(1, 3.99, quantity: 1, customer_group_id: :all)
-> true
+Update a resource attributes.
+
+Example:
+
+```rb
+Magento::Product.update('sku-teste', name: 'Updated name')
+
+# or by instance method
+
+product = Magento::Product.find('sku-teste')
+
+product.update(name: 'Updated name', status: '2')
+
+# or save after changing the object
+
+product.name = 'Updated name'
+product.save
 ```
 
-## Get List
+### `delete`
+
+Delete a especific resource.
 
 ```rb
-Magento::Product.all
+Magento::Product.delete('sku-teste')
+
+# or
+product = Magento::Product.find('sku-teste')
+product.delete
 ```
 
-#### Select fields:
+## Search Criteria
+
+They are methods used to assemble the search parameters
+
+All methods return an instance of the `Magento::Query` class. The request is only executed after calling method `all`.
+
+Example:
+
+```rb
+customers = Magento::Customer
+  .where(dob_gt: '1995-01-01')
+  .order(:dob)
+  .all
+
+# or
+
+query = Magento::Customer.where(dob_gt: '1995-01-01')
+
+query = query.order(:dob) if ordered_by_date_of_birth
+
+customers = query.all
+```
+
+### Select fields:
+
+Example:
 ```rb
 Magento::Product.select(:id, :sku, :name).all
-Magento::Product.select(:id, :sku, :name, extension_attributes: :category_links).all
-Magento::Product.select(:id, :sku, :name, extension_attributes: [:category_links, :website_ids]).all
-Magento::Product.select(:id, :sku, :name, extension_attributes: [:website_ids, { category_links: :category_id }]).all
+
+Magento::Product
+  .select(
+    :id,
+    :sku,
+    :name,
+    extension_attributes: :category_links
+  )
+  .all
+
+Magento::Product
+  .select(
+    :id,
+    :sku,
+    :name,
+    extension_attributes: [
+      :category_links,
+      :website_ids
+    ]
+  )
+  .all
+
+Magento::Product
+  .select(
+    :id,
+    :sku,
+    :name,
+    extension_attributes: [
+      { category_links: :category_id },
+      :website_ids
+    ]
+  )
+  .all
 ```
 
-#### Filters:
+### Filters
 
+Example:
 ```rb
 Magento::Product.where(visibility: 4).all
 Magento::Product.where(name_like: 'IPhone%').all
@@ -131,6 +318,7 @@ Magento::Product.where(price_gt: 10)
 Magento::Product.where(price_lt: 1, price_gt: 100).all
 
 Magento::Order.where(status_in: [:canceled, :complete]).all
+
 ```
 
 | Condition | Notes |
@@ -153,56 +341,37 @@ Magento::Order.where(status_in: [:canceled, :complete]).all
 |to         | The end of a range. Must be used with from |
 
 
-#### SortOrder:
+### Sort Order
 
+Example:
 ```rb
 Magento::Product.order(:sku).all
 Magento::Product.order(sku: :desc).all
 Magento::Product.order(status: :desc, name: :asc).all
 ```
 
-#### Pagination:
+### Pagination:
 
+Example:
 ```rb
 # Set page and quantity per page
-Magento::Product.page(1)       # Current page, Default is 1
-                .page_size(25) # Default is 50
-                .all
+Magento::Product
+  .page(1)       # Current page, Default is 1
+  .page_size(25) # Default is 50
+  .all
 
 # per is an alias to page_size
 Magento::Product.per(25).all
 ```
 
-#### Example of several options together:
-```rb
-products = Magento::Product.select(:sku, :name)
-                           .where(name_like: 'biscoito%')
-                           .page(1)
-                           .page_size(5)
-                           .all
-```
-
-## Get one
-
-```rb
-Magento::Order.where(increment_id: '000013457').first
-# or
-Magento::Order.find_by(increment_id: '000013457')
-```
-
-## Count
-```rb
-Magento::Order.count
-Magento::Order.where(status: :pending).count
-```
-
-\* _same pattern to all models_
-
-### Response
+## Record Collection
 
 The `all` method retorns a `Magento::RecordCollection` instance
 
+Example:
 ```rb
+products = Magento::Product.all
+
 products.first
 >> <Magento::Product @sku="2100", @name="Biscoito Piraque Salgadinho 100G">
 
@@ -282,106 +451,198 @@ All Methods:
 :empty?
 ```
 
-## Create
+## Product
+
+### Shurtcuts
+
+Shurtcut to get custom attribute value by custom attribute code in product
+
+Exemple:
 
 ```rb
-Magento::Order.create(
-  customer_firstname: '',
-  customer_lastname: '',
-  customer_email: '',
-  # others attrbutes ...,
-  items: [
-    {
-      sku: '',
-      price: '',
-      qty_ordered: 1,
-      # others attrbutes ...,
-    }
-  ],
-  billing_address: {
-    # attrbutes...
-  },
-  payment: {
-    # attrbutes...
-  },
-  extension_attributes: {
-    # attrbutes...
-  }
-)
+product.attr :description
+# it is the same as
+product.custom_attributes.find { |a| a.attribute_code == 'description' }&.value
+
+# or
+product.description
 ```
 
-### Update
+when the custom attribute does not exists:
 
 ```rb
-product = Magento::Product.find('sku-teste')
+product.attr :special_price
+> nil
 
-product.name = 'Updated name'
-product.save
+product.special_price
+> NoMethodError: undefined method `special_price' for #<Magento::Product:...>
+```
 
-# or
+```rb
+product.respond_to? :special_price
+> false
 
-product.update(name: 'Updated name')
+product.respond_to? :description
+> true
+```
 
-# or
+Shurtcut to get product stock and stock quantity
 
-Magento::Product.update('sku-teste', name: 'Updated name')
+```rb
+product = Magento::Product.find('sku')
+
+product.stock
+> <Magento::StockItem @item_id=7243, @product_id=1221, ...>
+
+product.stock_quantity
+> 22
 ```
 
-### Delete
+### Update stock
+
+Update product stock
 
 ```rb
-product = Magento::Product.find('sku-teste')
+product = Magento::Product.find('sku')
+product.update_stock(qty: 12, is_in_stock: true)
 
-product.delete
+# or through the class method
 
-# or
+Magento::Product.update_stock('sku', id, {
+  qty: 12,
+  is_in_stock: true
+})
+```
 
-Magento::Product.delete('sku-teste')
+> see all available attributes in: [Magento Rest Api Documentation](https://magento.redoc.ly/2.4.1-admin/tag/productsproductSkustockItemsitemId)
+
+
+### Add media to product
+
+Create new gallery entry
+
+Example:
+```rb
+product = Magento::Product.find('sku')
+
+image_params = {
+  media_type: 'image',
+  label: 'Image label',
+  position: 1,
+  content: {
+    base64_encoded_data: '/9j/4QAYRXhpZgAASUkqAAgAAAAAAAAA...',
+    type: 'image/jpg',
+    name: 'filename.jpg'
+  },
+  types: ['image']
+}
+
+product.add_media(image_params)
+
+# or through the class method
+
+Magento::Product.add_media('sku', image_params)
 ```
+> see all available attributes in: [Magento Rest Api Documentation](https://magento.redoc.ly/2.3.6-admin/#operation/catalogProductAttributeMediaGalleryManagementV1CreatePost)
 
-## GuestCart
 
-Set payment information to finish the order
+you can also use the `Magento::Params::CreateImage` helper class
+
 ```rb
-cart = Magento::GuestCart.find('gXsepZcgJbY8RCJXgGioKOO9iBCR20r7')
+params = Magento::Params::CreateImage.new(
+  title: 'Image title',
+  path: '/path/to/image.jpg', # or url
+  position: 1,
+).to_h
 
-# or use "build" to not request information from the magento API
-cart = Magento::GuestCart.build(
-  cart_id: 'aj8oUtY1Qi44Fror6UWVN7ftX1idbBKN'
-)
+product.add_media(params)
+```
 
-cart.payment_information(
-  email: 'customer@gmail.com',
-  payment: { method: 'cashondelivery' }
-)
+> see more about [Magento::Params::CreateImage](lib/magento/params/create_image.rb#L9)
 
->> "234575" # return the order id
+### Remove media from product
+
+Example:
+```rb
+product = Magento::Product.find('sku')
+
+product.add_media(madia_id)
+
+# or through the class method
+
+Magento::Product.add_media('sku', madia_id)
 ```
 
-Add coupon to cart
+### Add tier price to product
+
+Add `price` on product `sku` for specified `customer_group_id`
+
+The `quantity` params is the minimun amount to apply the price
 ```rb
-cart = Magento::GuestCart.find('gXsepZcgJbY8RCJXgGioKOO9iBCR20r7')
+product = Magento::Product.find('sku')
+product.add_tier_price(3.99, quantity: 1, customer_group_id: :all)
 
-cart.add_coupon('COAU4HXE0I')
-# You can also use the class method
-Magento::GuestCart.add_coupon('gXsepZcgJbY8RCJXgGioKOO9iBCR20r7', 'COAU4HXE0I')
+# or through the class method
 
->> true # return true on success
+Magento::Product.add_tier_price('sku', 3.99, quantity: 1, customer_group_id: :all)
 ```
 
-Delete coupon from cart
+### Remove tier price from product
+
 ```rb
-cart = Magento::GuestCart.find('gXsepZcgJbY8RCJXgGioKOO9iBCR20r7')
+product = Magento::Product.find(1)
+product.remove_tier_price(quantity: 1, customer_group_id: :all)
 
-cart.delete_coupon()
-# You can also use the class method
-Magento::GuestCart.delete_coupon('gXsepZcgJbY8RCJXgGioKOO9iBCR20r7')
+# or through the class method
 
->> true # return true on success
+Magento::Product.remove_tier_price('sku', quantity: 1, customer_group_id: :all)
+```
+
+### Create links to product
+
+Assign a product link to another product
+
+Example:
+```rb
+product = Magento::Product.find('sku')
+
+link_param = {
+  link_type: 'upsell',
+  linked_product_sku: 'linked_product_sku',
+  linked_product_type: 'simple',
+  position: 1,
+  sku: 'sku'
+}
+
+product.create_links([link_param])
+
+# or through the class method
+
+Product.create_links('sku', [link_param])
+```
+
+### Remove link from product
+
+Example:
+```rb
+product = Magento::Product.find('sku')
+
+product.remove_link(link_type: 'simple', linked_product_sku: 'linked_product_sku')
+
+# or through the class method
+
+Product.remove_link(
+  'sku',
+  link_type: 'simple',
+  linked_product_sku: 'linked_product_sku'
+)
 ```
 
-## Invoice an Order
+## Order
+
+### Invoice an Order
 
+Example:
 ```rb
 Magento::Order.invoice(order_id)
 >> 25 # return incoice id
@@ -409,21 +670,22 @@ invoice_id = order.invoice(
 
 [Complete Invoice Documentation](https://magento.redoc.ly/2.4-admin/tag/orderorderIdinvoice#operation/salesInvoiceOrderV1ExecutePost)
 
-## Create refund for invoice
+### Create offline refund for order
 
+Example:
 ```rb
-Magento::Invoice.invoice(invoice_id)
+Magento::Order.refund(order_id)
 >> 12 # return refund id
 
 # or from instance
 
-invoice = Magento::Invoice.find(invoice_id)
+order = Magento::Order.find(order_id)
 
-refund_id = invoice.refund
+order.refund
 
 # you can pass parameters too
 
-invoice.refund(
+order.refund(
   items: [
     {
       extension_attributes: {},
@@ -431,7 +693,6 @@ invoice.refund(
       qty: 0
     }
   ],
-  isOnline: true,
   notify: true,
   appendComment: true,
   comment: {
@@ -450,24 +711,93 @@ invoice.refund(
 )
 ```
 
-[Complete Refund Documentation](https://magento.redoc.ly/2.4-admin/tag/invoicescomments#operation/salesRefundInvoiceV1ExecutePost)
+[Complete Refund Documentation](https://magento.redoc.ly/2.4-admin/tag/invoicescomments#operation/salesRefundOrderV1ExecutePost)
+
+### Creates new Shipment for given Order.
+
+Example:
+```rb
+Magento::Order.ship(order_id)
+>> 25 # return shipment id
+
+# or from instance
+
+order = Magento::Order.find(order_id)
 
+order.ship
 
-## Create offline refund for order
+# you can pass parameters too
 
+order.ship(
+  capture: false,
+  appendComment: true,
+  items: [{ order_item_id: 123, qty: 1 }], # pass items to partial shipment
+  tracks: [
+    {
+      extension_attributes: { },
+      track_number: "string",
+      title: "string",
+      carrier_code: "string"
+    }
+  ]
+  notify: true
+)
+```
+
+[Complete Shipment Documentation](https://magento.redoc.ly/2.4-admin/tag/orderorderIdship#operation/salesShipOrderV1ExecutePost)
+
+
+### Cancel an Order
+
+Example:
 ```rb
-Magento::Order.refund(order_id)
+order = Magento::Order.find(order_id)
+
+order.cancel # or
+
+Magento::Order.cancel(order_id)
+```
+
+### Add a comment on given Order
+
+Example:
+```rb
+order = Magento::Order.find(order_id)
+
+order.add_comment(
+  'comment',
+  is_customer_notified: 0,
+  is_visible_on_front: 1
+)
+
+# or
+
+Magento::Order.add_comment(
+  order_id,
+  'comment',
+  is_customer_notified: 0,
+  is_visible_on_front: 1
+)
+```
+
+## Invoice
+
+### Create refund for invoice
+
+Example:
+```rb
+Magento::Invoice.invoice(invoice_id)
 >> 12 # return refund id
 
 # or from instance
 
-order = Magento::Order.find(order_id)
+invoice = Magento::Invoice.find(invoice_id)
 
-order.refund
+refund_id = invoice.refund
 
 # you can pass parameters too
 
-order.refund(
+invoice.refund(
   items: [
     {
       extension_attributes: {},
@@ -475,6 +805,7 @@ order.refund(
       qty: 0
     }
   ],
+  isOnline: true,
   notify: true,
   appendComment: true,
   comment: {
@@ -493,70 +824,52 @@ order.refund(
 )
 ```
 
-[Complete Refund Documentation](https://magento.redoc.ly/2.4-admin/tag/invoicescomments#operation/salesRefundOrderV1ExecutePost)
+[Complete Refund Documentation](https://magento.redoc.ly/2.4-admin/tag/invoicescomments#operation/salesRefundInvoiceV1ExecutePost)
 
-## Other Invoice methods
+### Capture an invoice
 
+Example:
 ```rb
 invoice = Magento::Invoice.find(invoice_id)
+invoice.capture
 
-invoice.capture # or
+# or through the class method
 Magento::Invoice.capture(invoice_id)
-
-invoice.void # or
-Magento::Invoice.void(invoice_id)
-
-invoice.send_email # or
-Magento::Invoice.send_email(invoice_id)
-
-Magento::Invoice.comments(invoice_id).all
-Magento::Invoice.comments(invoice_id).where(created_at_gt: Date.today.prev_day).all
 ```
 
-## Creates new Shipment for given Order.
+### Void an invoice
 
+Example:
 ```rb
-Magento::Order.ship(order_id)
->> 25 # return shipment id
-
-# or from instance
+invoice = Magento::Invoice.find(invoice_id)
+invoice.void
 
-order = Magento::Order.find(order_id)
+# or through the class method
+Magento::Invoice.void(invoice_id)
+```
 
-order.ship
+### Send invoice email
 
-# you can pass parameters too
+Example:
+```rb
+invoice = Magento::Invoice.find(invoice_id)
+invoice.send_email
 
-order.ship(
-  capture: false,
-  appendComment: true,
-  items: [{ order_item_id: 123, qty: 1 }], # pass items to partial shipment
-  tracks: [
-    {
-      extension_attributes: { },
-      track_number: "string",
-      title: "string",
-      carrier_code: "string"
-    }
-  ]
-  notify: true
-)
+# or through the class method
+Magento::Invoice.send_email(invoice_id)
 ```
 
-[Complete Shipment Documentation](https://magento.redoc.ly/2.4-admin/tag/orderorderIdship#operation/salesShipOrderV1ExecutePost)
-
-
-## Cancel an Order
+### Get invoice comments
 
+Example:
 ```rb
-order = Magento::Order.find(order_id)
-
-order.cancel # or
-
-Magento::Order.cancel(order_id)
+Magento::Invoice.comments(invoice_id).all
+Magento::Invoice.comments(invoice_id).where(created_at_gt: Date.today.prev_day).all
 ```
 
-## Generate Sales Rules and Coupons
+## Sales Rules
+
+### Generate Sales Rules and Coupons
 
 ```rb
 rule = Magento::SalesRule.create(
@@ -591,33 +904,71 @@ Magento::SalesRule.generate_coupon(
   }
 )
 ```
-see all params in:
-- [Magento docs Coupon](https://magento.redoc.ly/2.3.5-admin/tag/couponsgenerate#operation/salesRuleCouponManagementV1GeneratePost)
-- [Magento docs SalesRules](https://magento.redoc.ly/2.3.5-admin/tag/salesRules#operation/salesRuleRuleRepositoryV1SavePost)
-	
-See [how to add coupons to cart](#guestcart)
+> see all params in:
+[Magento docs Coupon](https://magento.redoc.ly/2.3.5-admin/tag/couponsgenerate#operation/salesRuleCouponManagementV1GeneratePost) and
+[Magento docs SalesRules](https://magento.redoc.ly/2.3.5-admin/tag/salesRules#operation/salesRuleRuleRepositoryV1SavePost)
 
-### First result
+
+## Customer
+
+### Get customer by token
 ```rb
-Magento::Product.first
->> <Magento::Product @sku="some-sku" ...>
+Magento::Customer.find_by_token('user_token')
+```
 
-Magento::Product.where(name_like: 'some name%').first
->> <Magento::Product @sku="some-sku" ...>
+## Guest Cart
+
+### Payment information
+Set payment information to finish the order
+
+Example:
+```rb
+cart = Magento::GuestCart.find('gXsepZcgJbY8RCJXgGioKOO9iBCR20r7')
+
+# or use "build" to not request information from the magento API
+cart = Magento::GuestCart.build(
+  cart_id: 'aj8oUtY1Qi44Fror6UWVN7ftX1idbBKN'
+)
+
+cart.payment_information(
+  email: 'customer@gmail.com',
+  payment: { method: 'cashondelivery' }
+)
+
+>> "234575" # return the order id
 ```
 
-### Count result
+### Add coupon to guest cart
+
+Example:
 ```rb
-Magento::Product.count
->> 7855
-Magento::Product.where(name_like: 'some name%').count
->> 15
+cart = Magento::GuestCart.find('gXsepZcgJbY8RCJXgGioKOO9iBCR20r7')
+
+cart.add_coupon('COAU4HXE0I')
+# You can also use the class method
+Magento::GuestCart.add_coupon('gXsepZcgJbY8RCJXgGioKOO9iBCR20r7', 'COAU4HXE0I')
+
+>> true # return true on success
+```
+
+### Remove coupon from guest cart
+
+Example:
+```rb
+cart = Magento::GuestCart.find('gXsepZcgJbY8RCJXgGioKOO9iBCR20r7')
+
+cart.delete_coupon()
+# You can also use the class method
+Magento::GuestCart.delete_coupon('gXsepZcgJbY8RCJXgGioKOO9iBCR20r7')
+
+>> true # return true on success
 ```
 
 ## Inventory
 
 ### Check whether a product is salable
 
+Example:
 ```rb
 Inventory.get_product_salable_quantity(sku: '4321', stock_id: 1)
 >> 1
@@ -625,6 +976,7 @@ Inventory.get_product_salable_quantity(sku: '4321', stock_id: 1)
 
 ### Check whether a product is salable for a specified quantity
 
+Example:
 ```rb
 Inventory.is_product_salable_for_requested_qty(
   sku: '4321',
@@ -643,27 +995,84 @@ Inventory.is_product_salable_for_requested_qty(
 }
 ```
 
-## Update product stock
+## **Helper classes**
+
+## Create product params
 
 ```rb
-product = Magento::Product.find('sku')
-product.update_stock(qty: 12, is_in_stock: true)
+params = Magento::Params::CreateProduct.new(
+  sku: '556-teste-builder',
+  name: 'REFRIGERANTE PET COCA-COLA 1,5L ORIGINAL',
+  description: 'Descrição do produto',
+  brand: 'Coca-Cola',
+  price: 4.99,
+  special_price: 3.49,
+  quantity: 2,
+  weight: 0.3,
+  attribute_set_id: 4,
+  images: [
+    *Magento::Params::CreateImage.new(
+      path: 'https://urltoimage.com/image.jpg',
+      title: 'REFRIGERANTE PET COCA-COLA 1,5L ORIGINAL',
+      position: 1,
+      main: true
+    ).variants,
+    Magento::Params::CreateImage.new(
+      path: '/path/to/image.jpg',
+      title: 'REFRIGERANTE PET COCA-COLA 1,5L ORIGINAL',
+      position: 2
+    )
+  ]
+)
+
+Magento::Product.create(params.to_h)
 ```
 
-or by class method
+## Create product image params
+
+Helper class to create product image params.
+
+before generating the hash, the following image treatments are performed:
+- resize image
+- remove alpha
+- leaves square
+- convert image to jpg
 
+Example:
 ```rb
-Magento::Product.update_stock(sku, id, {
-  qty: 12,
-  is_in_stock: true 
-})
+params = Magento::Params::CreateImage.new(
+  title: 'Image title',
+  path: '/path/to/image.jpg', # or url
+  position: 1,
+  size: 'small', # options: 'large'(defaut), 'medium' and 'small',
+  disabled: true, # default is false,
+  main: true, # default is false,
+).to_h
+
+Magento::Product.add_media('sku', params)
 ```
 
-see all available attributes in: https://magento.redoc.ly/2.4.1-admin/tag/productsproductSkustockItemsitemId
+The resize defaut confiruration is:
+
+```rb
+Magento.configure do |config|
+  config.product_image.small_size  = '200x200>'
+  config.product_image.medium_size = '400x400>'
+  config.product_image.large_size  = '800x800>'
+end
+```
+
+## Import products from csv file
+
+_TODO: exemple to [Magento::Import.from_csv](lib/magento/import.rb#L8)_
+
+_TODO: exemple to [Magento::Import.get_csv_template](lib/magento/import.rb#L14)_
+
 
 ___
 
-##TODO:
+
+## **TODO:**
 
 ### Search products
 ```rb
@@ -681,6 +1090,7 @@ Magento::Product.where(name_like: 'some name%').last
 
 ### Tests
 
+___
 
 ## Development
 
@@ -690,4 +1100,4 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/WallasFaria/nfce_crawler.
+Bug reports and pull requests are welcome on GitHub at https://github.com/WallasFaria/magento_ruby.