ZohoBooks Java Client Library

The Java library for integrating with the Zoho Books API.

Installation

Maven users

Add the below dependency to your pom.xml.

<dependency>
  <groupId>com.zoho.books</groupId>
  <artifactId>books-java</artifactId>
  <version>1.0</version>
</dependency>

Documentation

API Reference

Usage

In order to access the Zoho Books APIs, users need to have a valid Zoho account and a valid Auth Token.

Sign up for a Zoho Account:

---

For setting up a Zoho account, access the Zoho Books Sign Up page and enter the requisite details - email address and password.

Generate Auth Token:

---

To generate the Auth Token, you need to send an authentication request to Zoho Accounts in a prescribed URL format. Refer here

Java Wrappers - Sample

How to access Zoho Books APIs through Java wrapper classes?

---

Below is a sample code for accessing the Zoho Books' Organization through Java wrapper classes. Please import these classes:

    import com.zoho.books.exception.BooksException;

    import com.zoho.books.service.ZohoBooks;

    import com.zoho.books.api.OrganizationsApi;

    import com.zoho.books.model.Organization;
    import com.zoho.books.model.OrganizationList;
    import com.zoho.books.model.Address;

    public class Sample
    {

	public static void main(String args[]) throws Exception
	{ 

Once you're done with importing the requisite classes, you'll have to proceed to create an instance of OrganisationsAPI.

Create OrganisationsAPI instance:

---

Now, there are two ways of creating an instance of OrganisationsApi.

1.) Pass the AuthToken and create a new OrganisationsApi instance.

Sample code:

		OrganizationsApi organizationsApi = new OrganizationsApi(authtoken);

2.) Pass the AuthToken and organisations id to first create an instance of ZohoBooks, and then proceed to get the instance of Organisations API.

Sample code:

		ZohoBooks service = new ZohoBooks();        
		service.initialize("{auth_token}", "{organization_id}");        
		OrganizationsApi organizationsApi = service.getOrganizationsApi();

Create a new organization:

---

First time users signing up for Zoho Books need to create a new organization. Please follow the steps listed below:

Step 1: Create a new Organization object and set the relevant information in it.

		Organization organization = new Organization();

		organization.setName("ZOHO");
		organization.setFiscalYearStartMonth("january");
		organization.setCurrencyCode("USD");
		organization.setTimeZone("Asia/Calcutta");
		organization.setDateFormat("dd MMM yyyy");
		organization.setLanguageCode("en");
		organization.setTaxBasis("accrual");
		organization.setTaxType("tax");

Step 2: Create an Address object and set the address details in it. Once done, set the Address object into the Organization object.

		Address address = new Address();

		address.setStreetAddress1("9390 Research Blvd");
		address.setStreetAddress2("Bldg II, Suite 440");
		address.setCity("Austin");
		address.setState("Texas");
		address.setCountry("U.S.A");
		address.setZip("78759");

		organization.setAddress(address);

		try
		{

Step 3: Finally, pass the Organization object into the create() method to set up a new organization.

			Organization newOrganization = organizationsApi.create(organization);

Get the list of organizations:

---

If you wish to get the list of all your Zoho Books organizations, you need to call the getOrganizations() method in the format below:

			OrganizationList orgList = organizationsApi.getOrganizations();

It returns the OrganizationList object as a response.

Similarly, if you wish to parse the organization id from the List of Organization objects, you need to send a request in the prescribed format below:

			String orgId = orgList.get(0).getOrganizationId();

Get details of an organization:

---

In order to get the details of a organization, you need to call the get() method by passing organization_id as a parameter.

			Organization org = organizationsApi.get(orgId);

Update an existing organization:

---

Follow the steps listed below to update details of an existing organization.

Step 1: Select the the particular organization and fetch its Organization object by calling the get() method.

			Organization org = organizationsApi.get(orgId);

Step 2: Say you want to update the date format and tax basis details of that organization. Sample below:

			org.setDateFormat("yyyy mmm dd");            
			org.setTaxBasis("cash");

Now, pass the Organization object into the update() method to change the date format and taxbasis details.

			Organization updateOrg = organizationsApi.update(org);

Similarly, if you want to fetch the organization name from the Organization object, you can make use of the sample code below:

			System.out.println(updateOrg.getName());
			
		}

Catch Exceptions:

---

If there is any error encountered while calling the Java Wrappers of Zoho Books API, the respective class will throw the BooksException. Use the below mentioned code to catch the BooksException:

		catch(BooksException be)
		{
			System.out.println("Code : "+ be.getCode() +" Message : "+ be.getMessage());
		}

	}
    }

For a full set of examples, click here.