English | العربية

Laravel Zoho Books

This Laravel package simplifies integration with Zoho Books Accounting System, streamlining API interactions for easier accounting management.

Requirements

Features

• Authentication end points
• Contact end points
• Contact Person end points
• Estimate end points
• Sales Order end points

• Bank Account end points
• Bank Rule end points
• Bank Transaction end points
• Base Currency Adjustment end points
• Bill end points
• Chart Of Account end points
• Credit Note end points
• Currency end points
• Customer Payment end points
• Custom Module end points
• Expense end points
• Invoice end points
• Item end points
• Journal end points
• Opening Balance end points
• Project end points
• Purchase Order end points
• Recurring Bill end points
• Recurring Expense end points
• Recurring Invoice end points
• Retainer Invoice end points
• Task end points
• Tax end points
• Time Entry end points
• User end points
• Vendor Credit end points
• Vendor Payment end points
• Zoho Crm Integration end points

Installation

Install the package by using composer:

composer require sumer5020/laravel-zoho-books

Publish the assets

Publish all assets

php artisan vendor:publish --provider=Sumer5020\ZohoBooks\ZohoBooksServiceProvider

Publish the configuration only:

php artisan vendor:publish --tag=zohoBooks.config

Publish the migrations only:

php artisan vendor:publish --tag=zohoBooks.migrations

# Migrate the database
php artisan migrate

Add this into your .env and add your details that come from https://accounts.zoho.com/developerconsole

ZOHO_BOOKS_CLIENT_ID=
ZOHO_BOOKS_CLIENT_SECRET=
ZOHO_BOOKS_ACCESS_CODE=
ZOHO_BOOKS_REDIRECT_URI=

After that Run php artisan zoho:init command to initialize your credentials and insert token, refresh_token and expires_in into zoho_tokens table.

[!WARNING] We used Self Client to generate server-to-server access code. you must run the artisan command before the access code expired.

[!NOTE] The expires_in is for the token, The refresh_token is lifetime until you revoke it.

[!NOTE] In order to reduce the number of database requests and improve the performance you need to cache this token credentials with expire time equals the token expire time.

Usage

Setup 🚀

After publish

Add the ZohoBooksFacade in your controller or any class you need to use the package functionality on it

use Sumer5020\ZohoBooks\Facades\ZohoBooksFacade;
# or
use ZohoBooks;

Authenticate and Set Up

1. Initialize Your Credentials

   After running the php artisan zoho:init command, the access and refresh tokens will be stored in the zoho_tokens table. You can retrieve these tokens when making API calls.

2. Refresh access token

   To refresh expired access token, use:

   $token = ZohoBooksFacade::authentications()->refreshAccessToken($refresh_token);
   

3. Revoke access token

   To revoke the access token, use:

   $status = ZohoBooksFacade::authentications()->revokeRefreshAccessToken($access_token, $refresh_token);
   

[!NOTE] Once you have the access token, you can use it to call various Zoho Books API endpoints. The package provides a clean interface for each entity.

Working with Contacts

1. Create a Contact

   To create a new contact, use:

   $contactData = new CreateContactDto([
       'contact_name' => '...',
       'company_name' => '...',
       // ... other fields
   ]);
   
   $response = ZohoBooksFacade::contacts()->create($token, $organizationId, $contactData);
   

2. Update a Contact

   To update an existing contact:

   $updateContactData = new UpdateContactDto([
       'contact_name' => '...',
       // ... other fields
   ]);
   
   $response = ZohoBooksFacade::contacts()->update($token, $organizationId, $updateContactData);
   

3. List Contacts

   To list contacts with pagination:

   $paginationDto = new PaginationDto(['page' => 1, 'per_page' => 10]);
   $response = ZohoBooksFacade::contacts()->list($token, $organizationId, $paginationDto);
   

4. Get a Specific Contact

   To retrieve a specific contact's details:

   $contactId = '...';
   $response = ZohoBooksFacade::contacts()->get($token, $organizationId, $contactId);
   

5. Delete a Contact

   To delete a contact:

   $response = ZohoBooksFacade::contacts()->delete($token, $organizationId, $contactId);
   

Working with Contact Persons

1. Create a Contact Person

   To create a new contact person, use:

    $contactPersonData = new CreateContactPersonDto([
        'contact_id' => '...',
        'first_name' => '...',
        'last_name' => '...',
        // ... other fields
    ]);
   
    $response = ZohoBooksFacade::contactPersons()->create($token, $organizationId, $contactPersonData);
   

2. Update a Contact Person

   To update an existing contact person, use:

    $updateContactPersonData = new UpdateContactPersonDto([
        'contact_id' => '...',
        'contact_person_id' => '...',
        'first_name' => '...',
        // ... other fields
    ]);
   
    $response = ZohoBooksFacade::contactPersons()->update($token, $organizationId, $updateContactPersonData);
   

3. List Contacts Person

   To list person, use with pagination:

    $paginationDto = new PaginationDto(['page' => 1, 'per_page' => 10]);
    $response = ZohoBooksFacade::contactPersons()->list($token, $organizationId, $contactId, $paginationDto);
   

4. Get a Specific Contact Person

   To retrieve a specific contact person details, use:

    $getContactPersonDto = new GetContactPersonDto(['contact_id' => '...', 'contact_person_id' => '...']);
    $response = ZohoBooksFacade::contactPersons()->get($token, $organizationId, $getContactPersonDto);
   

5. Delete a Contact Person

   To delete a contact person, use:

    $response = ZohoBooksFacade::contactPersons()->delete($token, $organizationId, $contactPersonId);
   

Working with Estimates

1. Create an Estimate

   To create an estimate:

   $estimateData = new CreateEstimateDto([
       'customer_id' => '...',
       'currency_id' => '...',
       // ... other fields
   ]);
   
   $response = ZohoBooksFacade::Estimates()->create($token, $organizationId, $estimateData);
   

2. Update an Estimate

   To update an existing estimate:

   $updateEstimateData = new UpdateEstimateDto([
       'estimate_id' => '...',
       'customer_id' => '...',
       // ... other fields
   ]);
   
   $response = ZohoBooksFacade::Estimates()->update($token, $organizationId, $updateEstimateData);
   

3. List Estimates

   To list estimates:

   $paginationDto = new PaginationDto(['page' => 1, 'per_page' => 10]);
   $response = ZohoBooksFacade::Estimates()->list($token, $organizationId, $paginationDto);
   

4. Get Estimate Details

   To get details of a specific estimate:

   $estimateId = 'estimate_id_here';
   $response = ZohoBooksFacade::Estimates()->get($token, $organizationId, $estimateId);
   

5. Delete an Estimate

   To delete an estimate:

   $response = ZohoBooksFacade::Estimates()->delete($token, $organizationId, $estimateId);
   

Working with Sales Orders

1. Create a Sales Order

   To create a new sales order:

   $salesOrderData = new CreateSalesOrderDto([
       'customer_id' => '...',
       'currency_id' => '...',
       // ... other fields
   ]);
   
   $response = ZohoBooksFacade::salesOrders()->create($token, $organizationId, $salesOrderData);
   

2. Update a Sales Order

   To update an existing sales order:

   $updateSalesOrderData = new UpdateSalesOrderDto([
       'salesorder_id' => '...',
       'customer_id' => '...',
       // ... other fields
   ]);
   
   $response = ZohoBooksFacade::salesOrders()->update($token, $organizationId, $updateSalesOrderData);
   

3. List Sales Orders

   To list sales orders:

   $paginationDto = new PaginationDto(['page' => 1, 'per_page' => 10]);
   $response = ZohoBooksFacade::salesOrders()->list($token, $organizationId, $paginationDto);
   

4. Get a Specific Sales Order

   To retrieve details of a sales order:

   $salesOrderId = '...';
   $response = ZohoBooksFacade::salesOrders()->get($token, $organizationId, $salesOrderId);
   

5. Delete a Sales Order

   To delete a sales order:

   $response = ZohoBooksFacade::salesOrders()->delete($token, $organizationId, $salesOrderId);
   

Error Handling

When making API calls, exceptions may be thrown if something goes wrong. Make sure to handle exceptions properly:

try {
    // Your API call
} catch (Exception $e) {
    // Handle the exception
    echo 'Error: ' . $e->getMessage();
}

Usage Table

License

The MIT License (MIT). Please see MIT license File for more information.