No release in over a year
Ruby API Client for Zaikio's Procurement Platform
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies
 Project Readme

Zaikio::Procurement

Ruby API Client for Zaikio's Procurement Consumer Platform.

Installation

1. Add this line to your application's Gemfile:

gem 'zaikio-procurement'

And then execute:

$ bundle

Or install it yourself as:

$ gem install zaikio-procurement

2. Configure the gem:

# config/initializers/zaikio_procurement.rb

Zaikio::Procurement.configure do |config|
  config.environment = :production # sandbox or production
end

Usage

The Procurement Client has an ORM like design.

For the requests to work, a valid JSON Web token with the correct OAuth Scopes must always be provided. Please refer to zaikio-oauth_client.

If you want to know which actions are available and which scopes are required, please refer to the Procurement Consumer API V2 Reference.

As an organization

token = "..." # Your valid JWT for an organization
Zaikio::Procurement.with_token(token) do

  # Fetch Data
  Zaikio::Procurement::MaterialRequirement.all
  Zaikio::Procurement::MaterialRequirement.find("7cbf51bd-35a8-47a1-84a2-57aa63140234")

  # Associations
  material_requirement = Zaikio::Procurement::MaterialRequirement.find("7cbf51bd-35a8-47a1-84a2-57aa63140234")
  material_requirement.availability
  material_requirement.pricing
  material_requirement.order

  # Search for a variant
  search = Zaikio::Procurement::VariantSearch.new(type: "sheet_substrate", query: "Soap", grain: "short", paper_weight: 80)
  # You can either pass a single value or a comma separated list of types, e.g. type: "sheet_substrate,plate"
  # Use all to include all available Variant types in the response

  search.results # Returns a list of matching variants
  search.available_filters # Returns a list of available filters that can be used to further narrow down the results

  # Filter and search material requirements
  # Available filters can be found here:  https://docs.zaikio.com/api/procurement_consumers/consumers_v2.html#/MaterialRequirements/get_material_requirements
  Zaikio::Procurement::MaterialRequirement.where(query: "Sappi", filters: { article_category: "sheet_substrate", status: "ordered" })

  ### Create new resources

  # Create a ContractRequest
  supplier = Zaikio::Procurement::Supplier.find("5fd82941-ba2f-4d0b-971a-7050fbbafcef")
  supplier.contract_requests.create(
    customer_number: "1968353479",
    contact_first_name: "Frank",
    contact_last_name: "Gallikanokus",
    contact_email: "fgalli@example.com",
    contact_phone: "+3333333333333",
    references: ["my reference"])

  # Create a MaterialRequirement
  Zaikio::Procurement::MaterialRequirement.create(
    amount: 200,
    job_client: "Awesome Client",
    job_description: "Awesome print product",
    job_link: "https://www.example.com",
    job_reference: "my job reference",
    material_required_at: "2022-08-03",
    supplier_id: "b2a0f1ab-7610-451e-acc7-633284300521",
    variant_id: "31924842-b38b-47b2-90b0-68f8f42f37d6",
    references: ["my requirement reference"],
    visible_in_web: true)

  # Create an Order
  Zaikio::Procurement::Order.create(
    material_requirement_ids: ["9f98e841-1502-4d7b-9b8a-0cf9b8072875"],
    references: ["my order reference"],
    copy_material_requirement_references_to_line_items: true)

  ### Update resources
  material_requirement = Zaikio::Procurement::MaterialRequirement.find("058a5513-925e-4d0c-923d-fa1ed4bfb3ce")
  material_requirement.update(amount: 1000)

  ### Deleting resources
  material_requirement = Zaikio::Procurement::MaterialRequirement.find("2f5a99c2-9734-4aac-9cee-911b061d3a5a")
  material_requirement.destroy

  ### Custom methods

  # Placing an order and submitting it to the supplier
  order = Zaikio::Procurement::Order.find("8eaeb37a-d7aa-424a-aac1-1ade4b4030e2")
  order.place

  # Cancel a placed order
  order = Zaikio::Procurement::Order.find("3d36c6c5-b979-4073-8fcc-78a6cf1bc8bd")
  order.cancel

  # Archive a canceled or completed material requirement
  material_requirement = Zaikio::Procurement::MaterialRequirement.find("2f5a99c2-9734-4aac-9cee-911b061d3a5a")
  material_requirement.archive

  # Refreshing the order conditions (price, stock and delivery date) of the material requirement
  material_requirement = Zaikio::Procurement::MaterialRequirement.find("2f5a99c2-9734-4aac-9cee-911b061d3a5a")
  material_requirement.refresh
end

Error Handling

If an unexpected error occurs with an API call (i.e. an error that has no status code 2xx, 404 or 422) then a Zaikio::ConnectionError is thrown automatically (for 404 there will be a Zaikio::ResourceNotFound).

This can be easily caught using the with_fallback method. We recommend to always work with fallbacks.

Zaikio::Directory.with_token(token) do
  Zaikio::Procurement::MaterialRequirement.with_fallback.find("7cbf51bd-35a8-47a1-84a2-57aa63140234") # => nil
  Zaikio::Procurement::MaterialRequirement.with_fallback.all # Automatically uses empty array as fallback
end