Service Items - JSON API
Table of Contents
- Introduction
- Request Information
- GET Service Items
- GET Service Item
- POST Create Service item
- POST Update Service Item
- Object Definitions
- Request Filters
- Statuses
1.0 Introduction
Service items are operations that can been logged against a service. An example of this would be logging an item of post against an address service.
Once a service item has been logged, eFiling will invoice the customer for these at the start of the following month.
2.0 Request Information
HTTP GET
All 'service item' endpoints have optional parameters that can be used to filter the result set, if no filters are sent then the API will return all records.
The results will be paginated and limited to 100 per result set.
The filters will remain the same for all service item endpoints
Example:
/services/123/items?status=1&limit=20
Please See Request Filters for a list of parameters
3.0 GET /services/[service-id]/items
This endpont allows you to retrieve all service items logged against a service.
Response
| Value | Type | Description |
|---|---|---|
| request | object | Request details |
| response | object | Response object which contains an array of service item |
| pagination | object | Ragination information |
| errors | array | Contains an array of strings |
4.0 GET /services/[service-id]/items/[service-item-id]
This end point allows you to retrieve a individual service item.
This end point will return the response as /services/[service-id]/items. The response will be an object that contains an array of 'service_items'; this array will contain one result.
Response
| Value | Type | Description |
|---|---|---|
| request | object | Request details |
| response | object | Response object which contains an array of service item |
| pagination | object | Ragination information |
| errors | array | Contains an array of strings |
5.0 POST Create Service item
This end point will allow an API user to create a service item against a service.
Please note that this endpoint will return the same response as the GET methods. The created service item will be returned as the only element in the 'service_items' array.
Request
/services/['service-id']/items
| Value | Type | Description |
|---|---|---|
| operation_id | int | The id for the operation |
| status | int | A status for the item |
| description | string | Optional. A description for the service item. |
| price | int | Optional. A price for the item, otherwise the operation price will be used. |
| external_ref | string | Optional. A external references. |
Response
| Value | Type | Description |
|---|---|---|
| request | object | Request details |
| response | object | Response object which contains an array of service item |
| pagination | object | Ragination information |
| errors | array | Contains an array of strings |
6.0 POST Update Service Item
eFiling has an end point which will allow a developer to update a service item; Only set properties will be saved.
Please note that this end point will return the same response as the GET methods. The updated service item will be returned as the only element in the 'service_items' array.
Request
/services/['service-id']/items/['service-item-id']
| Value | Type | Description |
|---|---|---|
| operation_id | int | Optional. The id for the operation. |
| description | string | Optional. A description for the service item. |
| status | int | Optional. A status for the item. |
| price | int | Optional. A price for the item, otherwise the operation price will be used. |
| external_ref | string | Optional. A external references. |
Response
| Value | Type | Description |
|---|---|---|
| request | object | Request details |
| response | object | Response object which contains an array of service item |
| pagination | object | Ragination information |
| errors | array | Contains an array of strings |
7.0 Object Definitions
7.1 Request
Request object returned
| Property | Value | Description |
|---|---|---|
| type | string | HTTP method |
| url | string | Endpoint requested. |
| filters | object | An object containing request values submitted |
7.2 Response
An object that contains the data requested.
| Property | Value | Description |
|---|---|---|
| service_items | array | An array of service item objects |
7.3 Service Item
| Value | Type | Description |
|---|---|---|
| id | int | The id of the service item. |
| service_id | int | The id of the service this item is related to |
| operation_id | int | The id of the product operation. |
| user_id | int | The id of the user this item belongs to. |
| incorporation_id | int | The id of the incorporation this item belongs to. |
| officer_id | int | The id of the officer this item belongs to. |
| status | int | The status of the item. |
| price | int | The price of the item. |
| description | string | A description for the item. |
| external_ref | string | An external reference |
| date_created | int | A 14 digit int representing the date this was created. In the format YmdHis. |
7.4 Pagination
An object that contains details about pagination
| Property | Value | Description |
|---|---|---|
| result_count | int | The number of results returned. |
| result_total | int | The total number of results available. |
| current_page | int | The page you are viewing based on the result_limit being displayed. Passed in through the URL |
| total_pages | int | The total number of pages you can view. |
8.0 Request Filters
| Value | Type | Description |
|---|---|---|
| page | int | The number of page you want to view, defaulted to 1. |
| limit | int | The limit of results you receive, defaulted to 30. |
9.0 Statuses
Here is a list of possible statues
| Status | Status Text |
|---|---|
| 0 | Held |
| 1 | Forwarded |
| 2 | Returned to Sender |
| 3 | Paused due to MLC |
| 100 | Invoiced |
| 500 | Processed |
*0 - An item of post has been marked as HELD, likely due to an inactive service or insufficient funds.
*1 - An item of post has been marked as FORWARDED, will be invoiced at the start of the following month.
*2 - An item of post has been HELD for too long and the brand has "Returned to Sender".
*3 - An item is being HELD due to an unverified customer, the customer may have an active service but they must be ID checked first.
*100 - An item of post has been invoiced, items change from 1 => 100.
*500 - An item is 'PROCESSED' when 'HELD' post becomes available to be 'FORWARDED'. eFiling holds post when the customer does not have the appropriate service, once the customer purchases the correct service eFiling will forward the post. eFiling keeps track of these items by creating a new item with a status of '1' and updates the original item to '500', the original item of post will then be linked to the new item via the 'parent id'.