Zendesk Extension for Magento

This extension makes Zendesk work seamlessly with Magento to enable stores to deliver great customer support. Features include:

• Enable Single Sign-on with Zendesk
• Create support tickets without leaving Magento
• Display relevant support tickets on order & customer dashboards
• Create support tickets from Contact Us requests
• Easily add the Embeddables Web Widget to your site

The latest stable version of the extension can be installed via the Magento Connect marketplace.

API

General Notes

The extension provides its own custom RESTful API, which is intended to be used by the Magento Zendesk App. The custom API allows for a consistent interface across all Magento versions, regardless of whether they support XML-RPC, SOAP or REST interfaces, and provides exactly the data that the app requires.

The base URL of the API is http://your_site_base_url/zendesk/api/.

Authentication

The API can be enabled in the Zendesk settings page in the Magento admin panel. Using it requires a token to be generated and be sent to the API in an Authorization header:

Authorization: Token token="your token goes here"

Single Sign-on (SSO)

The extension only accepts one type of SSO implementation, either for administrators/agents or end-users. Verify that you have selected the correct user group to enable SSO, on your Zendesk account go to Settings > Security and select Single sign-on for which users to enable SSO via Magento.

Administrators and agents

• Remote login URL: http://your_site_base_url/admin/zendesk/authenticate
• Remote logout URL: http://your_site_base_url/admin/zendesk/logout

End-users sign-in

• Remote login URL: http://your_site_base_url/zendesk/sso/login
• Remote logout URL: http://your_site_base_url/zendesk/sso/logout

Responses

You may receive the following errors from any of the API calls:

• 401 Not authorised

  Authentication token is not valid.

• 403 API access disabled

  API access has been disabled in the Magento admin panel. It will need to be enabled before using the API.

• 404 Resource does not exist

  The requested resource was not found.

All API methods return content as JSON objects following the format set out in the method definitions below.

Available Methods

GET /customers/<email>

Will return customer information for the customer with the provided email address. If no customer record exists but orders have been placed then the email is treated as a guest and only the orders they have placed are returned. If no customer record exists and there are no orders using the email then a 404 error is returned.

Note that Magento allows scoping customers either globally or per website. If set to be scoped per website then this method will return the first customer which matches the email address, regardless of the website they belong to.

Response Format

Guest customers only have the guest and orders keys returned.

Name	Type	Comment
guest	boolean	Whether the customer is a guest (no customer record) or has a full customer record
id	integer	Internal Magento ID for the customer
name	string	Customer's full name
email	string	Customer's email address
active	boolean	Whether the customer is marked as active in Magento
admin_url	string	URL to access the customer detail in the Magento admin panel
created	string	Date and time the customer record was created
dob	string	Date of birth
addresses	array	List of addresses recorded on the customer account
orders	array	List of orders placed by the customer (see the `orders` method for details)

GET /orders/<order_increment_id>

Will return details of an individual order based on the Magento order increment ID, which usually takes the form 100000321.

Response Format

Name	Type	Comment
id	string	The order ID displayed to the customer
status	string	Current order status (e.g. Pending, Processing, Complete)
created	string	Date and time the order was created
updated	string	Date and time the order was last updated
customer	object	Has the keys: name Customer's name email Customer's email address ip IP address the order was placed from guest Whether the customer placed the order as a guest
store	string	Magento store that the order was placed in
total	string	Total value of the order
currency	string	Currency code (e.g. AUD, USD)
items	array	List of items on the order; each item has the keys: sku Product's unique SKU name Product name
admin_url	string	URL to access the order in the Magento admin panel

GET /users/<user_id>

Will return either a single Magento admin user, or a list of users if the user_id argument is left out. Admin user accounts have access to the admin panel and are different to customer accounts.

Parameters

Argument	Default	Comment
page_size	100	Number of results to be returned
offset	0	Page number to return, based on `page_size`
sort	given_name	Attribute to sort by

Response Format

Name	Type	Comment
id	string	Internal ID for the user
given_name	string	User's first name
family_name	string	User's surname
username	string	Username used to log in to the Magento admin panel
email	string	User's email address
active	boolean	Whether the user is enabled and can log in
role	string	User's role; used for ACLs in Magento

Local Development

Resetting the extension

During development you may wish to clear out the configuration for the Magento extension. All settings are stored in the core_config_data table of the Magento database and can be removed with an SQL query:

DELETE FROM `core_config_data` WHERE `path` LIKE 'zendesk/%';

Contribution

Improvements to the extension are always welcome. To contribute, please submit detailed Pull Requests.

Bugs

Please submit bug reports to Zendesk.

Copyright and License

Copyright 2012-present, Zendesk Inc. Licensed under the Apache License Version 2.0.