/magento_extension

Zendesk's Magento extension

Primary LanguagePHPOtherNOASSERTION

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.