Recent Service Tickets

Overview

Service tickets enable you to track customer issues and work on those issues through to resolution.

The Recent Service Tickets service provides you with an overview of the service tickets that have most recently been updated. The list is separated into service tickets that are still open (in status Open or In Process) and service tickets that are closed (in status Completed or Confirmed).

API Reference

/{tenant}/customers/{customerNumber}/recentItems

Overview of recent service tickets for a customer

/{tenant}/customers/{customerNumber}/recentItems

get

Retrieve a list of recent service tickets for the given customer.

The customer is identified by the customerNumber.

Required scope: hybris.serviceticket_view

Retrieve a list of recent service tickets for the given customer.

The customer is identified by the customerNumber.

Required scope: hybris.serviceticket_view

Request
Response

URI Parameters

tenant: required (string - minLength: 3 - maxLength: 16 - pattern: [a-z][a-z0-9]+)
Stands for the "project" that requests this resource. Must match the "project" that is associated with the access token in the Authorization header.
Example:
```
myexampleshop
```
Customer number: required (string)
Example:
```
C0750876755
```

Headers

Authorization: required (string)
Used to send a valid OAuth2 access token.
Example:
```
Bearer access_token
```
Accept-Language: (string - repeat: true)
The value of the locale identifier of the language in which the attribute should be returned. Provide several values separated by comma, in order to specify fallback languages.
Example:
```
en
```

Query Parameters

openItemsMaxHits: (integer - default: 5)
Maximum number of open service tickets to retrieve
Example:
```
5
```
closedItemsMaxHits: (integer - default: 5)
Maximum number closed service tickets to retrieve
Example:
```
5
```

HTTP status code 200

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Recent items GET response schema",
    "type": "object",
    "properties": {
        "numberOfOpenItems": {
            "type": "integer",
            "description": "Total number of open items"
        },
        "recentOpenItems": {
            "type": "array",
            "description": "Recent open items",
            "items": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "title": "Recent item schema",
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "Id of the recent item"
                    },
                    "name": {
                        "type": "string",
                        "description": "Human-readable name of the recent item"
                    },
                    "description": {
                        "type": "string",
                        "description": "Description of the recent item"
                    },
                    "statusDescription": {
                        "type": "string",
                        "description": "Status description of the recent item"
                    },
                    "modifiedAt": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Date and time the recent item was last changed at"
                    }
                },
                "required": [
                    "id"
                ]
            }
        },
        "numberOfClosedItems": {
            "type": "integer",
            "description": "Total number of closed items"
        },
        "recentClosedItems": {
            "type": "array",
            "description": "Recent closed items",
            "items": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "title": "Recent item schema",
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "Id of the recent item"
                    },
                    "name": {
                        "type": "string",
                        "description": "Human-readable name of the recent item"
                    },
                    "description": {
                        "type": "string",
                        "description": "Description of the recent item"
                    },
                    "statusDescription": {
                        "type": "string",
                        "description": "Status description of the recent item"
                    },
                    "modifiedAt": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Date and time the recent item was last changed at"
                    }
                },
                "required": [
                    "id"
                ]
            }
        }
    }
}

Example:

{
    "numberOfOpenItems": 9,
    "recentOpenItems": [
        {
            "id": "55a66652e10e1b156b8837d5",
            "name": "1000000205",
            "description": "Request for regular maintenance",
            "statusDescription": "In Process",
            "modifiedAt": "2015-07-15T13:55:30.155+0000"
        },
        {
            "id": "55a387bf7ecef0f015cbd214",
            "name": "1000000008",
            "description": "Request for regular maintenance",
            "statusDescription": "In Process",
            "modifiedAt": "2015-07-13T09:41:19.863+0000"
        },
        {
            "id": "55a38710e10e1b156b882a9e",
            "name": "1000000009",
            "description": "Request for regular maintenance",
            "statusDescription": "In Process",
            "modifiedAt": "2015-07-13T09:38:24.562+0000"
        },
        {
            "id": "55a3536c7d4e63c7dc41e81b",
            "name": "1000000204",
            "description": "Request for regular maintenance",
            "statusDescription": "In Process",
            "modifiedAt": "2015-07-13T05:58:04.761+0000"
        },
        {
            "id": "55a3530de10e1b156b8829f8",
            "name": "1000000203",
            "description": "Request for regular maintenance",
            "statusDescription": "In Process",
            "modifiedAt": "2015-07-13T05:56:29.678+0000"
        }
    ],
    "numberOfClosedItems": 3,
    "recentClosedItems": [
        {
            "id": "55a391cc7ecef0f015cbd23c",
            "name": "83964",
            "description": "Burst Tyre; Under Warranty;  Status changed",
            "statusDescription": "Confirmed",
            "modifiedAt": "2015-07-17T07:17:55.565+0000"
        },
        {
            "id": "55a50921e10e1b156b8830bb",
            "name": "1000000001",
            "description": "Request for regular maintenance",
            "statusDescription": "Completed",
            "modifiedAt": "2015-07-14T13:07:46.455+0000"
        },
        {
            "id": "55a504dee10e1b156b8830a4",
            "name": "1000000001",
            "description": "Request for regular maintenance",
            "statusDescription": "Completed",
            "modifiedAt": "2015-07-14T12:49:50.360+0000"
        }
    ]
}

HTTP status code 400

Request syntactically incorrect. Any details will be provided within the response payload.

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "error",
    "description": "Schema for API specified errors.",
    "type": "object",
    "properties": {
        "status": {
            "type": "integer",
            "description": "original HTTP error code, should be consistent with the response HTTP code",
            "minimum": 100,
            "maximum": 599
        },
        "type": {
            "type": "string",
            "description": "classification of the error type, lower case with underscore eg validation_failure",
            "pattern": "[a-z]+[a-z_]*[a-z]+"
        },
        "message": {
            "type": "string",
            "description": "descriptive error message for debugging"
        },
        "moreInfo": {
            "type": "string",
            "format": "uri",
            "description": "link to documentation to investigate further and finding support"
        },
        "details": {
            "type": "array",
            "description": "list of problems causing this error",
            "items": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "title": "errorDetail",
                "description": "schema for specific error cause",
                "type": "object",
                "properties": {
                    "field": {
                        "type": "string",
                        "description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
                    },
                    "type": {
                        "type": "string",
                        "description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
                        "pattern": "[a-z]+[a-z_]*[a-z]+"
                    },
                    "message": {
                        "type": "string",
                        "description": "descriptive error detail message for debugging"
                    },
                    "moreInfo": {
                        "type": "string",
                        "format": "uri",
                        "description": "link to documentation to investigate further and finding support for error detail"
                    }
                },
                "required": [
                    "type"
                ]
            }
        }
    },
    "required": [
        "status",
        "type"
    ]
}

Example:

{
    "status": 400,
    "type": "validation_violation",
    "message": "The tenants passed in the request header hybris-tenant and in the resource path do not match.",
    "details": [
        {
            "type": "tenant_mismatch",
            "message": "The tenants passed in the request header hybris-tenant and in the resource path do not match."
        }
    ]
}

HTTP status code 401

Given request is unauthorized. Bad or expired token. Reauthenticate the user. Any details will be provided within the response payload.

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "error",
    "description": "Schema for API specified errors.",
    "type": "object",
    "properties": {
        "status": {
            "type": "integer",
            "description": "original HTTP error code, should be consistent with the response HTTP code",
            "minimum": 100,
            "maximum": 599
        },
        "type": {
            "type": "string",
            "description": "classification of the error type, lower case with underscore eg validation_failure",
            "pattern": "[a-z]+[a-z_]*[a-z]+"
        },
        "message": {
            "type": "string",
            "description": "descriptive error message for debugging"
        },
        "moreInfo": {
            "type": "string",
            "format": "uri",
            "description": "link to documentation to investigate further and finding support"
        },
        "details": {
            "type": "array",
            "description": "list of problems causing this error",
            "items": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "title": "errorDetail",
                "description": "schema for specific error cause",
                "type": "object",
                "properties": {
                    "field": {
                        "type": "string",
                        "description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
                    },
                    "type": {
                        "type": "string",
                        "description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
                        "pattern": "[a-z]+[a-z_]*[a-z]+"
                    },
                    "message": {
                        "type": "string",
                        "description": "descriptive error detail message for debugging"
                    },
                    "moreInfo": {
                        "type": "string",
                        "format": "uri",
                        "description": "link to documentation to investigate further and finding support for error detail"
                    }
                },
                "required": [
                    "type"
                ]
            }
        }
    },
    "required": [
        "status",
        "type"
    ]
}

Example:

{
    "status": 401,
    "message": "Authorization: Unauthorized. Bearer TOKEN is invalid",
    "type": "insufficient_credentials",
    "moreInfo": "https://api.yaas.io/patterns/errortypes.html"
}

HTTP status code 403

Evaluated request scopes in access token are not sufficient and do not match required scopes.

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "error",
    "description": "Schema for API specified errors.",
    "type": "object",
    "properties": {
        "status": {
            "type": "integer",
            "description": "original HTTP error code, should be consistent with the response HTTP code",
            "minimum": 100,
            "maximum": 599
        },
        "type": {
            "type": "string",
            "description": "classification of the error type, lower case with underscore eg validation_failure",
            "pattern": "[a-z]+[a-z_]*[a-z]+"
        },
        "message": {
            "type": "string",
            "description": "descriptive error message for debugging"
        },
        "moreInfo": {
            "type": "string",
            "format": "uri",
            "description": "link to documentation to investigate further and finding support"
        },
        "details": {
            "type": "array",
            "description": "list of problems causing this error",
            "items": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "title": "errorDetail",
                "description": "schema for specific error cause",
                "type": "object",
                "properties": {
                    "field": {
                        "type": "string",
                        "description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
                    },
                    "type": {
                        "type": "string",
                        "description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
                        "pattern": "[a-z]+[a-z_]*[a-z]+"
                    },
                    "message": {
                        "type": "string",
                        "description": "descriptive error detail message for debugging"
                    },
                    "moreInfo": {
                        "type": "string",
                        "format": "uri",
                        "description": "link to documentation to investigate further and finding support for error detail"
                    }
                },
                "required": [
                    "type"
                ]
            }
        }
    },
    "required": [
        "status",
        "type"
    ]
}

Example:

{
    "status": 403,
    "type": "insufficient_permissions",
    "message": "The credentials indicate a system-known user, but the user is not allowed to perform the requested operation."
}

HTTP status code 408

Request timed out.

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "error",
    "description": "Schema for API specified errors.",
    "type": "object",
    "properties": {
        "status": {
            "type": "integer",
            "description": "original HTTP error code, should be consistent with the response HTTP code",
            "minimum": 100,
            "maximum": 599
        },
        "type": {
            "type": "string",
            "description": "classification of the error type, lower case with underscore eg validation_failure",
            "pattern": "[a-z]+[a-z_]*[a-z]+"
        },
        "message": {
            "type": "string",
            "description": "descriptive error message for debugging"
        },
        "moreInfo": {
            "type": "string",
            "format": "uri",
            "description": "link to documentation to investigate further and finding support"
        },
        "details": {
            "type": "array",
            "description": "list of problems causing this error",
            "items": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "title": "errorDetail",
                "description": "schema for specific error cause",
                "type": "object",
                "properties": {
                    "field": {
                        "type": "string",
                        "description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
                    },
                    "type": {
                        "type": "string",
                        "description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
                        "pattern": "[a-z]+[a-z_]*[a-z]+"
                    },
                    "message": {
                        "type": "string",
                        "description": "descriptive error detail message for debugging"
                    },
                    "moreInfo": {
                        "type": "string",
                        "format": "uri",
                        "description": "link to documentation to investigate further and finding support for error detail"
                    }
                },
                "required": [
                    "type"
                ]
            }
        }
    },
    "required": [
        "status",
        "type"
    ]
}

Example:

{
    "status": 408,
    "type": "request_timeout",
    "message": "The request timed out."
}

HTTP status code 500

An internal server error occurred.

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "error",
    "description": "Schema for API specified errors.",
    "type": "object",
    "properties": {
        "status": {
            "type": "integer",
            "description": "original HTTP error code, should be consistent with the response HTTP code",
            "minimum": 100,
            "maximum": 599
        },
        "type": {
            "type": "string",
            "description": "classification of the error type, lower case with underscore eg validation_failure",
            "pattern": "[a-z]+[a-z_]*[a-z]+"
        },
        "message": {
            "type": "string",
            "description": "descriptive error message for debugging"
        },
        "moreInfo": {
            "type": "string",
            "format": "uri",
            "description": "link to documentation to investigate further and finding support"
        },
        "details": {
            "type": "array",
            "description": "list of problems causing this error",
            "items": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "title": "errorDetail",
                "description": "schema for specific error cause",
                "type": "object",
                "properties": {
                    "field": {
                        "type": "string",
                        "description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
                    },
                    "type": {
                        "type": "string",
                        "description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
                        "pattern": "[a-z]+[a-z_]*[a-z]+"
                    },
                    "message": {
                        "type": "string",
                        "description": "descriptive error detail message for debugging"
                    },
                    "moreInfo": {
                        "type": "string",
                        "format": "uri",
                        "description": "link to documentation to investigate further and finding support for error detail"
                    }
                },
                "required": [
                    "type"
                ]
            }
        }
    },
    "required": [
        "status",
        "type"
    ]
}

Example:

{
    "status": 500,
    "type": "internal_service_error",
    "message": "An internal server error occured."
}

/{tenant}/customers/{customerNumber}/recentItems

Scopes

The table shows the scopes that the Recent Service Tickets service supports.

SCOPE	DESCRIPTION
hybris.serviceticket_view	Read-only access to the service ticket

For more information about scopes, authorization, and authentication procedures for YaaS services, see Scopes and Authorization.

Manage Recent Service Tickets Service

You can use Recent Service Tickets sevice to retrieve the recent service tickets for a given customer. A valid service ticket created by a customer has four status: Open, In Process, Completed, Confirm.

Open is the initial status when a customer created a service ticket.
In Process represents that the service ticket is solving.
Completed represents that the ticket has been worked out.
Confirm represent that the customer has verified the ticket.

For more details about the meaning and transition of the statuses, please refer to Service Ticket Statuses.

Recent Service Tickets service will return the number and details of open items that contain the service tickets which status is Open or In Process. This service will also return the number and details of close items contain the service tickets which status is Completed or Confirm.

To achieve better data retrieval performance, this service is based on data in Engagement Center Indexing.

To retrieve a list of recent service tickets for a given customer, call the GET method. Identify the customer in the customerNumber parameter. To limit the number of service tickets returned, you can specify the query parameters openItemsMaxHits and closedItemsMaxHits. If you do not specify values for these parameters, the default value is 5.

openItemsMaxHits: Sets the maximum length of the recent open items returned in the response.
closedItemsMaxHits: Sets the maximum length of the recent closed items returned in the response.

The service tickets in the response are sorted by the time they were created.

Retrieve Recent Service Tickets

Merchants can retrieve the details of recent service tickets for a given customer in a specified tenant. The request body does not need to contain any information. All the necessary data is in the query parameters and message headers. The service returns the tickets in descending order, based on the time they were created.

The following example shows how to retrieve recent service tickets by customer Number.

Request

You can retrieve the recent service tickets by performing a request with:

Method: GET
Request URL: https://api.beta.yaas.io/hybris/recent-serviceticket/v1/{tenant}/customers/{customerNumber}/recentItems
Headers
- Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.serviceticket_view.
URI Parameters
- {tenant}: Name of the current tenant.
- {customerNumber}: Unique identifier of the customer.

Response

The successful response returns a 200 status code. An example JSON content looks similar to the following:

{
    "numberOfOpenItems": 5,
    "recentOpenItems": 
    [
        {
            "id": "55a66652e10e1b156b8837d5",
            "name": "1000000205",
            "description": "Request for regular maintenance",
            "statusDescription": "In Process",
            "modifiedAt": "2015-07-15T13:55:30.155+0000"
        }, 
        {
            "id": "55a387bf7ecef0f015cbd214",
            "name": "1000000008",
            "description": "Request for regular maintenance",
            "statusDescription": "In Process",
            "modifiedAt": "2015-07-13T09:41:19.863+0000"
        }, 
        {
            "id": "55a38710e10e1b156b882a9e",
            "name": "1000000009",
            "description": "Request for regular maintenance",
            "statusDescription": "In Process",
            "modifiedAt": "2015-07-13T09:38:24.562+0000"
        }, 
        {
            "id": "55a3536c7d4e63c7dc41e81b",
            "name": "1000000204",
            "description": "Request for regular maintenance",
            "statusDescription": "In Process",
            "modifiedAt": "2015-07-13T05:58:04.761+0000"
        }, 
        {
            "id": "55a3530de10e1b156b8829f8",
            "name": "1000000203",
            "description": "Request for regular maintenance",
            "statusDescription": "In Process",
            "modifiedAt": "2015-07-13T05:56:29.678+0000"
        }
    ],
    "numberOfClosedItems": 3,
    "recentClosedItems": 
    [
        {
            "id": "55a391cc7ecef0f015cbd23c",
            "name": "83964",
            "description": "Burst Tyre; Under Warranty;  Status changed",
            "statusDescription": "Confirmed",
            "modifiedAt": "2015-07-17T07:17:55.565+0000"
        }, 
        {
            "id": "55a50921e10e1b156b8830bb",
            "name": "1000000001",
            "description": "Request for regular maintenance",
            "statusDescription": "Completed",
            "modifiedAt": "2015-07-14T13:07:46.455+0000"
        }, 
        {
            "id": "55a504dee10e1b156b8830a4",
            "name": "1000000001",
            "description": "Request for regular maintenance",
            "statusDescription": "Completed",
            "modifiedAt": "2015-07-14T12:49:50.360+0000"
        }
    ]
}

Error Types

For information about error codes, see the API Reference.

Send feedback
If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.
Get Help
Use our private help channel. Receive updates over email and contact our specialists directly.
hybris Experts
If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.

Overview

API Reference

/{tenant}/customers/{customerNumber}/recentItems

/{tenant}/customers/{customerNumber}/recentItems

get /{tenant}/customers/{customerNumber}/recentItems

URI Parameters

Headers

Query Parameters

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 401

Body

HTTP status code 403

Body

HTTP status code 408

Body

HTTP status code 500

Body

Scopes

Manage Recent Service Tickets Service

Retrieve Recent Service Tickets

Request

Response

Error Types