Skip to content

Commit

Permalink
Merge pull request #164 from agnostack/release/3.0.0
Browse files Browse the repository at this point in the history 
Release 3.0.0: fix core issues and add new v3 zendesk endpoints
  • Loading branch information
@agrohs
agrohs authored Sep 23, 2020
2 parents b31346d + 047a2c8 commit b6aa80b
Show file tree
Hide file tree
Showing 7 changed files with 710 additions and 229 deletions.
2 changes: 2 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -1 +1,3 @@
**/.DS_Store

/vendor
293 changes: 68 additions & 225 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,14 @@
# ANNOUNCING VERSION 3.0 :mega:

The new 3.0 version of the Extension provides all new endpoints, with the ability to retrieve additional information about customers and orders within your Magento store.

* Perform advanced Customer Search
* View real-time Shipping Status
* Access detailed Payment Status
* Enable direct Order Search by ID
* Access Order Messages and Notes


# Zendesk Extension for Magento

This extension makes Zendesk work seamlessly with Magento to enable stores to deliver great customer support. **Features include:**
Expand All @@ -14,7 +25,7 @@ The latest stable version of the extension can be installed via the [Magento Con

### General Notes

The extension provides its own custom RESTful API, which is intended to be used by the [Magento Zendesk App](https://github.com/zendesk/magento_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 extension provides its own custom RESTful API, which is intended to be used by the [agnoStack app](https://www.zendesk.com/apps/support/agnostack-commerce---by-particular/). 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/`.

Expand Down Expand Up @@ -62,239 +73,71 @@ Will return customer information for the customer with the provided email addres

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.

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

#### 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**

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

#### 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**

<table>
<thead>
<tr>
<th>Argument</th>
<th>Default</th>
<th>Comment</th>
<tr>
</thead>
<tbody>
<tr>
<td>page_size</td>
<td>100</td>
<td>Number of results to be returned</td>
</tr>
<tr>
<td>offset</td>
<td>0</td>
<td>Page number to return, based on `page_size`</td>
</tr>
<tr>
<td>sort</td>
<td>given_name</td>
<td>Attribute to sort by</td>
</tr>
</tbody>
</table>

**Response Format**

<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Comment</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>string</td>
<td>Internal ID for the user</td>
</tr>
<tr>
<td>given_name</td>
<td>string</td>
<td>User's first name</td>
</tr>
<tr>
<td>family_name</td>
<td>string</td>
<td>User's surname</td>
</tr>
<tr>
<td>username</td>
<td>string</td>
<td>Username used to log in to the Magento admin panel</td>
</tr>
<tr>
<td>email</td>
<td>string</td>
<td>User's email address</td>
</tr>
<tr>
<td>active</td>
<td>boolean</td>
<td>Whether the user is enabled and can log in</td>
</tr>
<tr>
<td>role</td>
<td>string</td>
<td>User's role; used for ACLs in Magento</td>
</tr>
</tbody>
</table>
### Additional Available Methods (v3 and later)

#### GET /customer/`<customer_id>`

Will return customer information for the customer with the provided customer ID. If no customer record exists, this will return `null`.

#### POST /searchCustomers

Will return customer information for the customers with the provided customer atrribute payload.

Example payload:

```
{
"customer": {
"email": "[email protected]",
"firstname": "Jane",
"lastname": "Doe"
}
}
```

#### POST /searchOrders

Will return order details for orders which match the provided order attribute payload.

Example payloads:

```
// Lookup by customer and product
{
"customer": {
"email": "[email protected]"
},
"product": {
"sku": "123"
}
}
// Lookup by status
{
"status": "complete"
}
```

#### GET /order/`<order_id>`

Will return details of an individual order based on the Magento order increment ID, which usually takes the form 100000321. This endpoint will return enhanced data on top of what is prodived by the v2.x endpoint.

#### GET /shipping/`<order_id>`

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

#### GET /notes/`<order_id>`

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

## Local Development

Expand Down
Loading

0 comments on commit b6aa80b

Please sign in to comment.