Cin7Api

This is a Cin7 API wrapper gem to perform CRUD actions to the following resources:

  • SalesOrders
  • CreditNotes
  • Payments

Installation

Add this line to your application's Gemfile:

gem 'cin7_api'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install cin7_api

Usage

Prerequisite

This Gem requires the following Cin7 API permission:

  1. SalesOrder: READ and UPDATE
  2. CreditNote: READ and UPDATE
  3. Payment: READ, UPDATE and WRITE

SalesOrder

client = Cin7API::Client.new(username: ENV["CIN7_USERNAME"], api_key: ENV["CIN7_API_KEY"])

# Retrieve a list of SalesOrders with filter params
# NOTE: Cin7 does a binary OR check on the filter params
# This query will return SalesOrders with reference "#1050" OR email "[email protected]"
client.sales_order.where(reference: "#1050", email: "[email protected]")

# Find SalesOrder by filter params
# NOTE: This will do a array#find for SalesOrder matching all the filter params
# Return nil if none is found
client.sales_order.find_by(reference: "#1050", email: "[email protected]")

# Find SalesOrder by id
# Return SalesOrder or raise Cin7API::Error
client.sales_order.find(2218)

# Update SalesOrders
# NOTE: Cin7 only allow bulk updates
# NOTE: The key has to be in lower camelCase
attributes_array = [
  {
    id: 2221,
    lineItems: [{ id: 8140, unitPrice: 100 }],
    dispatchedDate: "2022-09-16T09:00:00Z",
    invoiceDate: "2022-09-16T09:00:00Z"
  }
]
# => [#<Cin7API::Response index=0, success=true, id=2221, code="#1052", errors=[]>]
client.sales_order.update(attributes_array)

CreditNote

client = Cin7API::Client.new(username: ENV["CIN7_USERNAME"], api_key: ENV["CIN7_API_KEY"])

# Retrieve a list of CreditNotes with filter params
# NOTE: Cin7 does a binary OR check on the filter params
# This query will return CreditNotes with sales_reference "#1050" OR email "[email protected]"
client.credit_note.where(sales_reference: "#1050", email: "[email protected]")

# Find CreditNote by filter params
# NOTE: This will do a array#find for CreditNote matching all the filter params
# Return nil if none is found
client.credit_note.find_by(reference: "#1050", email: "[email protected]")

# Find CreditNote by id
# Return CreditNote or raise Cin7API::Error
client.credit_note.find(2223)

# Update CreditNote
# NOTE: Cin7 only allow bulk updates
# NOTE: The key has to be in lower camelCase
attributes_array = [
  {
    id: 2223,
    lineItems: [{ id: 8142, unitPrice: 10 }, {id: 8143, unitPrice: 10}],
    completedDate: "2022-09-10T09:00:00Z",
    creditNoteDate: "2022-09-10T09:00:00Z",
  }
]
# => [#<Cin7API::Response index=0, success=true, id=2223, code="CRN-2223", errors=[]>]
client.credit_note.update(attributes_array)

Payment

client = Cin7API::Client.new(username: ENV["CIN7_USERNAME"], api_key: ENV["CIN7_API_KEY"])

# Retrieve a list of Payments with filter params
# NOTE: Cin7 does a binary OR check on the filter params
# This query will return Payments with order_id 2223 OR order_ref "CRN-2223"
client.payment.where(order_id: 2223, order_ref: "CRN-2223")

# Find Payment by filter params
# NOTE: This will do a array#find for Payment matching all the filter params
# Return nil if none is found
client.payment.find_by(order_id: 2223, order_ref: "CRN-2223")

# Find Payment by id
# Return Payment or raise Cin7API::Error
client.payment.find(698)

# Create Payment
# NOTE: Cin7 only allow bulk creates
# NOTE: The key has to be in lower camelCase
attributes_array = [
  {
    orderType: "CreditNote",
    orderRef: "CRN-2223",
    orderId: 2223,
    method: "Not Paid",
    amount: 10,
    paymentDate: "2022-09-10T09:00:00Z"
  }
]
# => [#<Cin7API::Response index=0, success=true, id=713, code=nil, errors=[]>]
client.payment.create(attributes_array)

# Update Payment
# NOTE: Cin7 only allow bulk updates
# NOTE: The key has to be in lower camelCase
attributes_array = [{ id: 713, orderId: 2223, method: "manual", amount: 0 }]
# => [#<Cin7API::Response index=0, success=true, id=713, code=nil, errors=[]>]
client.payment.update(attributes_array)

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/cin7_api. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Cin7Api project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.