{"id":22743101,"url":"https://github.com/rikas/zoho_hub","last_synced_at":"2025-04-10T00:19:09.141Z","repository":{"id":32750991,"uuid":"141684482","full_name":"rikas/zoho_hub","owner":"rikas","description":"Zoho CRM API V2 Wrapper","archived":false,"fork":false,"pushed_at":"2024-07-16T08:02:36.000Z","size":241,"stargazers_count":25,"open_issues_count":8,"forks_count":30,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-02T16:25:28.629Z","etag":null,"topics":["api","api-client","zoho"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rikas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-20T08:19:39.000Z","updated_at":"2024-09-21T08:18:23.000Z","dependencies_parsed_at":"2024-12-11T01:16:42.188Z","dependency_job_id":"10a8bdd0-4b06-47bc-9516-cb659424f45f","html_url":"https://github.com/rikas/zoho_hub","commit_stats":{"total_commits":187,"total_committers":11,"mean_commits":17.0,"dds":0.2727272727272727,"last_synced_commit":"a8d7b21117a4f5e9a2ec14d13b533224630b2d1a"},"previous_names":[],"tags_count":59,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rikas%2Fzoho_hub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rikas%2Fzoho_hub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rikas%2Fzoho_hub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rikas%2Fzoho_hub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rikas","download_url":"https://codeload.github.com/rikas/zoho_hub/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248131435,"owners_count":21052845,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-client","zoho"],"created_at":"2024-12-11T01:16:33.078Z","updated_at":"2025-04-10T00:19:09.114Z","avatar_url":"https://github.com/rikas.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ZohoHub\n\n[![Gem Version](https://badge.fury.io/rb/zoho_hub.svg)](https://badge.fury.io/rb/zoho_hub)\n\nSimple wrapper around Zoho CRM version2, using\n[OAuth 2.0 protocol](https://www.zoho.com/crm/help/developer/api/oauth-overview.html) for authentication.\n\nThis gem reads your Module configuration and builds the corresponding classes for you, using some\nreflection mechanisms. You should then be able to use simple classes with an API close to\nActiveRecord, to do CRUD operations.\n\n**NOTE: this gem is WIP, please try to use it and open an issue if you run into limitations / problems**\n\n## Table of Contents\n\n- [ZohoHub](#zohohub)\n  - [Table of Contents](#table-of-contents)\n  - [Installation](#installation)\n  - [Setup process](#setup-process)\n    - [1. Register your application](#1-register-your-application)\n      - [1.1 Zoho Accounts URL](#11-zoho-accounts-url)\n      - [1.2 Authorized Redirect URI](#12-authorized-redirect-uri)\n    - [2. Configure ZohoHub with your credentials](#2-configure-zohohub-with-your-credentials)\n    - [3. Authorization request](#3-authorization-request)\n      - [3.1 Redirection based authentication](#31-redirection-based-authentication)\n      - [3.2 Self-Client Authorization](#32-self-client-authorization)\n      - [3.3 More on scopes](#33-more-on-scopes)\n      - [3.4 Offline access](#34-offline-access)\n    - [4. Access token](#4-access-token)\n    - [5. Refresh token](#5-refresh-token)\n    - [6. Basic ZohoHub flow](#6-basic-zohohub-flow)\n    - [7. BaseRecord and record classes](#7-baserecord-and-record-classes)\n      - [7.1 Reflection](#71-reflection)\n      - [7.2 Subclassing BaseRecord](#72-subclassing-baserecord)\n  - [8 Notifications](#8-notifications)\n    - [8.1 Enable notifications](#81-enable-notifications)\n    - [8.2 List notifications](#82-list-notifications)\n    - [8.3 Caveats](#83-caveats)\n  - [Tips and suggestions](#tips-and-suggestions)\n  - [Examples](#examples)\n    - [Setup auth token and request CurrentUser](#setup-auth-token-and-request-currentuser)\n  - [Development](#development)\n  - [Contributing](#contributing)\n  - [License](#license)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'zoho_hub'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install zoho_hub\n\n## Setup process\n\n### 1. Register your application\n\nIf you want to access your Zoho CRM account from your application you first need to create your\napplication as described here: https://www.zoho.com/crm/help/developer/api/register-client.html.\n\nThis will give you a **Client ID** and a **secret**, that you'll use in\n[step 2](#2-configure-zohohub-with-your-credentials).\n\n#### 1.1 Zoho Accounts URL\n\nRegistration and authorization requests are made to Zoho's domain-specific Accounts URL which\nvaries depending on your region:\n\n- China: https://accounts.zoho.com.cn\n- EU: https://accounts.zoho.eu\n- India: https://accounts.zoho.in\n- US: https://accounts.zoho.com\n\nZohoHub uses the EU Account URL by default, but this can be overriden in a `ZohoHub.configure` block\nvia the `api_domain` method ([step 2](#2-configure-zohohub-with-your-credentials).)\n\n#### 1.2 Authorized Redirect URI\n\nPer Zoho's API documentation, providing a **redirect URI** is optional. Doing so allows a user of\nyour application to be redirected back to your app (to the **redirect URI**) with a **grant token**\nupon successful authentication.\n\nIf you don't provide a **redirect URI**, you'll need to use the\n[self-client option](https://www.zoho.com/crm/help/developer/api/auth-request.html#self-client) for\nauthorization (see [3.2](#32-self-client-authorization).)\n\n---\n\n### 2. Configure ZohoHub with your credentials\n\n\u003e **Note:** Treat these credentials like an important password. It is _strongly_ recommended to not\n\u003e paste them anywhere in plain text. Do _not_ add them to version control; keep them out of your\n\u003e code directly by referencing them via environment variables. Use something like the dotenv gem or\n\u003e encrypted credentials in Rails to keep them as secret and secure as possible.\n\nYou need to have a configuration block like the one below (in Rails add a `zoho_hub.rb` in your\n`config/initializers` directory):\n\n```ruby\nZohoHub.configure do |config|\n  config.client_id    = 'YOUR_ZOHO_CLIENT_ID' # obtained in 1.\n  config.secret       = 'YOUR_ZOHO_SECRET'    # obtained in 1.\n  config.redirect_uri = 'YOUR_ZOHO_OAUTH_REDIRECT_URL'\n  config.api_domain   = 'https://accounts.zoho.com' # can be omitted if in the EU\n  # config.debug      = true # this will be VERY verbose, but helps to identify bugs / problems\nend\n```\n\n---\n\n### 3. Authorization request\n\nIn order to access data in Zoho CRM you need to authorize ZohoHub to access your account. To do so\nyou have to request a specific URL with the right **scope** and **access_type**. Successful\nauthorization will provide a **grant token** which will be used to generate **access** and\n**refresh tokens**.\n\n#### 3.1 Redirection based authentication\n\nTo get the right URL you can use this simple line of code:\n\n```ruby\nZohoHub::Auth.auth_url\n# =\u003e \"https://accounts.zoho.eu/oauth/v2/auth?access_type=offline\u0026client_id=\u0026redirect_uri=\u0026response_type=code\u0026scope=ZohoCRM.modules.custom.all,ZohoCRM.settings.all,ZohoCRM.modules.contacts.all,ZohoCRM.modules.all\"\n```\n\nIf you request this generated URL you should see a screen like this one, where you have to click on\n\"Accept\":\n\n![](https://duaw26jehqd4r.cloudfront.net/items/1h1i3C1N0k0i02092F0S/Screen%20Shot%202018-11-25%20at%2019.18.38.png)\n\nYou will then be redirected to the **redirect URI** you provided with additional query parameters\nas follows (the value after `code=` is the **grant token**):\n\n```\n{redirect_uri}?code={grant_token}\u0026location=us\u0026accounts-server=https%3A%2F%2Faccounts.zoho.com\n```\n\n#### 3.2 Self-Client Authorization\n\nIf you don't have a **redirect URI** or you want your application to be able to authorize with Zoho\nprogrammatically (without a user required to be present and click the \"Accept\" prompt), Zoho\nprovides a\n[self-client option](https://www.zoho.com/crm/help/developer/api/auth-request.html#self-client)\nfor authentication which will provide a **grant token**.\n\n#### 3.3 More on scopes\n\nYou can change the default scope (what data can be accessed by your application). This is the list\nprovided as the default scope:\n\n```\nZohoCRM.modules.custom.all\nZohoCRM.settings.all\nZohoCRM.modules.contacts.all\nZohoCRM.modules.all\n```\n\nTo get the URL for a different scope you can provide a `scope` argument:\n\n```ruby\nZohoHub::Auth.auth_url(scopes: ['ZohoCRM.modules.custom.all', 'ZohoCRM.modules.all'])\n# =\u003e \"https://accounts.zoho.eu/oauth/v2/auth?access_type=offline\u0026client_id=\u0026redirect_uri=\u0026response_type=code\u0026scope=ZohoCRM.modules.custom.all,ZohoCRM.modules.all\"\n```\n\nRefer to\n[Zoho's API documentation on scopes](https://www.zoho.com/crm/help/developer/api/oauth-overview.html#scopes)\nfor detailed information.\n\n#### 3.4 Offline access\n\nBy design the **access tokens** returned by the OAuth flow expire after a period of time (1 hour by\ndefault), as a safety mechanism. This means that any application that wants to work with a user's\ndata needs the user to have recently gone through the OAuth flow, aka be online.\n\nWhen you request offline access the Zoho API returns a **refresh token**. **Refresh tokens** give\nyour application the ability to request data on behalf of the user when the user is not present and\nin front of your application.\n\n**By default `ZohoHub::Auth.auth_url` will request offline access**\n\nYou can force \"online\" access by using `#auth_url` with a `access_type` argument:\n\n```ruby\nZohoHub::Auth.auth_url(access_type: 'online')\n# =\u003e \"https://accounts.zoho.eu/oauth/v2/auth?access_type=online\u0026client_id=\u0026redirect_uri=\u0026response_type=code\u0026scope=ZohoCRM.modules.custom.all,ZohoCRM.settings.all,ZohoCRM.modules.contacts.all,ZohoCRM.modules.all\"\n```\n\n---\n\n### 4. Access token\n\nSee Zoho's API documentation for generating an initial **access token**:\nhttps://www.zoho.com/crm/help/developer/api/access-refresh.html\n\nTo use an **access token** in a manual request, include it as a request header as\n`Authorization: Zoho-oauthtoken {access_token}` (without the braces.)\n\nTo use an **access token** with ZohoHub, pass it to the `ZohoHub.setup_connection` method as the\n`access_token` parameter.\n\n---\n\n### 5. Refresh token\n\nThis gem automatically refresh the access token.\n\nIf you want automatic refresh, use the `refresh_token` argument as in the next chapter.\n\n---\n\n### 6. Basic ZohoHub flow\n\nOnce ZohoHub has been configured with your credentials (section 2) and you have a fresh **access\ntoken**, setup a ZohoHub connection:\n\n```ruby\nZohoHub.setup_connection access_token: 'ACCESS_TOKEN',\n                         expires_in: 'EXPIRES_IN_SEC',\n                         api_domain: 'API_DOMAIN',\n                         refresh_token: 'REFRESH_TOKEN'\n```\n\nNow you can issue requests to Zoho's API with the Connection object, e.g.:\n\n```ruby\n# request a (paginated) list of all Lead records\nZohoHub.connection.get 'Leads'\n```\n\nA successful request will receive a response like the sample here:\nhttps://www.zoho.com/crm/help/developer/api/get-records.html.\n\n---\n\n### 7. BaseRecord and record classes\n\nAt this point, ZohoHub is starting to do some of the heavy lifting, but using `ZohoHub.connection`\nstill gets tedious after just a handful of requests. But we can improve that by allowing ZohoHub\nto build our record classes or by manually defining them ourselves.\n\n#### 7.1 Reflection\n\nTODO\n\n#### 7.2 Subclassing BaseRecord\n\nSee `lib/zoho_hub/base_record.rb` and any of the classes in `examples/models/` for reference.\n\nFor any Zoho module with which you want to interact via ZohoHub, make a class of the same name that\ninherits from `ZohoHub::BaseRecord`. For example, to build a class for the Leads module:\n\n```ruby\n# lead.rb\n\nclass Lead \u003c ZohoHub::BaseRecord\n  ...\nend\n```\n\nSpecify this module's fields as attributes:\n\n```ruby\n# lead.rb\n\nclass Lead \u003c ZohoHub::BaseRecord\n  attributes :id, :first_name, :last_name, :phone, :email, :source, # etc.\nend\n```\n\nNow you can issue requests more easily with your record class, e.g.:\n\n```ruby\n# Request a (paginated) list of all Lead records\nLead.all\n\n# Get the Lead instance with a specific ID\nLead.find('78265000003433063')\n```\n\nAnd even create new Lead entries in Zoho:\n\n```ruby\nlead = Lead.new(\n  first_name: 'First name',\n  last_name: 'Last name',\n  phone: '+35197736281',\n  email: 'myemail@gmail.com',\n  source: 'Homepage'\n)\n\n# Creates the new lead\nlead.save\n\n# Or in one step:\nlead = Lead.create(first_name: 'First name', ...)\n```\n\nUpdating records:\n\n```ruby\nLead.update(id: lead.id, first_name: \"...\", last_name: \"...\")\n\n# Or\nlead.update(first_name: \"...\", last_name: \"...\")\n\n# Or update up to 100 records in one call:\nleads = [{ id: id1, phone: \"123\" }, { id: id2, first_name: \"...\" }]\nLead.update_all(leads)\n```\n\nBlueprint transition:\n\n```ruby\nLead.blueprint_transition(lead.id, transition_id)\n\n# Or\nlead.blueprint_transition(transition_id)\n```\n\nAdding notes:\n\n```ruby\nLead.add_note(id: lead.id, title: 'Note title', content: 'Note content')\n```\n\nRelated records:\n\n```ruby\nProduct.all_related(parent_module: 'Lead', parent_id: lead.id)\nProduct.add_related(\n  parent_module: 'Lead',\n  parent_id: lead.id,\n  related_id: product.id\n)\nProduct.remove_related(\n  parent_module: 'Lead',\n  parent_id: lead.id,\n  related_id: product.id\n)\nProduct.update_related(...)\n```\n\nAttachments (`ZohoHub::Attachment` is defined in the gem):\n\n```ruby\nLead.related_attachments(parent_id: lead.id)\n# -\u003e Array of Attachments\n\nattachment = Lead.download_attachment(parent_id: lead.id, attachment_id:attachment.id)\n# -\u003e Attachment (attachment.file contains the file as a Tempfile)\n\n#NB: Lead.upload_attachment not implemented yet\n```\n\n## 8 Notifications\n\nZoho allows you to receive a notification when a record of a module changes. Supported operation types are create, delete, edit, all.\n\n### 8.1 Enable notifications\n\nIn order to receive notifications, you have to enable them first.\n\n```ruby\n# Enable notifications for a given channel:\nnotification_url = 'https://example.org/api/notifications' # Zoho will send notifications by POST to this url\ntoken = '123abc' # Zoho will send this token back to you, so you can ensure that the notification is from Zoho\nchannel_id = 1 # Choose a channel to handle the response\nevents = %w[Leads.create Deals.edit Contacts.delete Sales_Orders.all] # Which events to receive notifications for\nchannel_expiry = (DateTime.now + 1.day).iso8601 # choose a date when the channel should expire. 24h is the maximum, default is one hour\n\nZohoHub::Notifications.enable(notification_url, channel_id, events, channel_expiry, token)\n```\n\nAfter enabling notifications, Zoho will execute a POST request to the provided notification_url every time the requested event occurs.\n\nFor a list of an in-depth description of the response, check the [Zoho documentation](https://www.zoho.com/crm/developer/docs/api/notifications/overview.html)\n\n### 8.2 List notifications\n\nYou can also retrieve all notifications that are currently enabled and that you are receiving uppdates for.\n\n```ruby\n# Get all enabled notifications\nZohoHub::Notifications.all\n```\n\n### 8.3 Caveats\n\n- Zoho does not notify you when records are merged.\n- Since Zoho does not tell you what changed, you will have to request the record by yourself. Due to this you can miss changes, when they occur quickly after another. This is especially important for status changes, as you might miss state changes.\n\n## Tips and suggestions\n\n- Using a tool such as Postman or curl to issue HTTP requests and verify responses in isolation\n  can be a great sanity check during setup.\n- Downloading ZohoHub code (as opposed to the gem) and running `bin/console` is a great way to\n  learn how the code works and test aspects of setup and Zoho's API in isolation.\n- [The Zoho API Documentation](https://www.zoho.com/crm/help/developer/api/overview.html) is your\n  friend - especially the sample HTTP requests and responses in the various sections under \"Rest\n  API\" on the left.\n- If you're manually implementing your record classes (rather than using the reflection mechanism),\n  the files in `/examples/models/` can help you get started.\n- Requests can be issued to Zoho CRM's\n  [Sandbox](https://help.zoho.com/portal/kb/articles/using-sandbox)\n  by configuring `https://crmsandbox.zoho.com/crm` (or regional equivalent) as the `api_domain`.\n\n## Examples\n\n### Setup auth token and request CurrentUser\n\n\u003e This example assumes use of the dotenv gem and is written directly into\n\u003e ZohoHub's root directory (rather than using ZohoHub as a gem) for simplicity.\n\n1. Edit `bin/console` to comment out refreshing the token and setting up the connection:\n\n```ruby\n# bin/console\n\n...\n# puts 'Refreshing token...'\n# token_params = ZohoHub::Auth.refresh_token(ENV['ZOHO_REFRESH_TOKEN'])\n# ZohoHub.setup_connection(token_params)\n...\n```\n\n2. [Register your application](#1-register-your-application) to obtain a **client ID** and\n   **secret**. (Leave the [Zoho API Credentials page](https://accounts.zoho.com/developerconsole) open;\n   you'll need it in step 5.)\n3. Determine your [Zoho Accounts URL](#11-zoho-accounts-url).\n4. Add your registration and account URL information to a `.env` file:\n\n```\n# .env\n\nZOHO_CLIENT_ID=YOUR_CLIENT_ID\nZOHO_SECRET=YOUR_SECRET\nZOHO_API_DOMAIN=YOUR_ZOHO_ACCOUNTS_URL\n```\n\n5. On the [Zoho API Credentials page](https://accounts.zoho.com/developerconsole) from step 1, click\n   the three vertical dots and select `Self client`.\n6. Paste this into the `Scope` field: `ZohoCRM.users.ALL`, choose an expiration time, and click\n   `View Code`; this is your **Grant token**.\n7. Run the ZohoHub console from your terminal: `bin/console`\n8. Issue a token request with the **grant token** (notice the quotes around the token value):\n\n```ruby\nZohoHub::Auth.get_token('paste_your_grant_token_here')\n```\n\nThis should return a response with an **access token**, e.g.:\n\n```ruby\n=\u003e {:access_token=\u003e\"ACCESS_TOKEN_VALUE\",\n :expires_in_sec=\u003e3600,\n :api_domain=\u003e\"https://www.zohoapis.com\",\n :token_type=\u003e\"Bearer\"\n }\n```\n\nexit the console with `exit`.\n\n9. Add the access token to your `.env` file:\n\n```\n# .env\n\nZOHO_CLIENT_ID=YOUR_CLIENT_ID\nZOHO_SECRET=YOUR_SECRET\nZOHO_API_DOMAIN=YOUR_ZOHO_ACCOUNTS_URL\nZOHO_ACCESS_TOKEN=YOUR_ACCESS_TOKEN\n```\n\n10. Edit `bin/console` to add a new `setup_connection` after the previously commented out one:\n\n```ruby\n# bin/console\n\n...\n# ZohoHub.setup_connection(token_params)\n\nZohoHub.setup_connection(access_token: ENV['ZOHO_ACCESS_TOKEN'])\n...\n```\n\n11. Start the console again: `bin/console`.\n\n12. Issue a request for the current user: `ZohoHub.connection.get 'users?type=CurrentUser'`\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run\nthe tests. You can also run `bin/console` for an interactive prompt that will allow you to\nexperiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`.\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/rikas/zoho_hub.\n\n## License\n\nThe gem is available as open source under the terms of the\n[MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frikas%2Fzoho_hub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frikas%2Fzoho_hub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frikas%2Fzoho_hub/lists"}