API version 1 Adjustments
1. List Adjustments (api1/adjustments)
This method will answer with a collection of iinsight's adjustments that has been modified/created since a provided date. The collection wil be in JSON format.
The results would be paginated, having a maximum of 100 records per page. An empty collection and a status code 200 response, means that there is no records in the specified page.
URL
| Server | URL | HTTP type |
|---|---|---|
| UAT | https://api-uk-uat.iinsightonline.com/api1/adjustments | GET |
| PRODUCTION | https://api-uk.iinsightonline.com/api1/adjustments | GET |
Authorization
| Parameter | Value | Mandatory |
|---|---|---|
| Type | Bearer Token | Yes |
| Token | The token is generated using the /auth/login method | Yes |
Query Params
| Parameter | Value | Mandatory |
|---|---|---|
| modified_since |
Date since last update or insert. Format: YYYY-MM-DDThh:mm:ssZ (date and time in UTC ISO 8601) Example: 2024-02-29T12:28:01Z |
Yes |
| page | The page number of the paginated results. (i.e.: 1) | Yes |
| status |
The transaction status. (i.e.: active / voided / all) - The "active" status returns all active adjustments and reversal transactions. - The "voided" status returns all voided adjustments. - The "all" status returns all active and voided adjustments and reversal transactions. |
Yes |
| type |
The transaction type. (i.e.: adjustment / reversal / all) - The "adjustment" type returns all adjustment transactions. - The "reversal" type returns all reversal transactions. - The "all" type returns all adjustment and reversal transactions. |
Yes |
Response
[
{
"adjustment_number": "JP2014423-A6",
"status": "active", // The transaction status: (active | voided)
"type": "negative adjustment", // The transaction type: (negative adjustment | positive adjustment | reversal)
"transaction_id": "2573", // IInsight ID
"date_entered": "02-01-2024",
"amount": "-3.30",
"tax_amount": "0.30",
"reason": "fsdsfd",
"invoice_number": "JP2014423",
"case_number": "JP11",
"case_id": "605",
"invoice_id": "1626",
"company_name": "A Tech Support Business 2",
"details": [
{
"record_id": "368",
"cost_id": "0",
"quantity": "",
"duration": "1.00",
"unit_charge": "3.00",
"gst": "0.30",
"exgst": "3.00",
"amount": "3.30",
"type": "Activity",
"time_based": "1",
"date": "29-12-2023",
"charge_code": "101",
"description": "test",
"details": "sss",
"charge": "Standard",
"milestone": "0",
"role": null,
"employee": "System"
}
],
"last_update": "02-01-2024 04:13:01",
"last_update_utc": "2024-01-02T17:13:01Z"
},
{
"adjustment_number": "TED1-A3",
"status": "voided",
"type": "negative adjustment",
"transaction_id": "2585",
"date_entered": "05-01-2024",
"amount": "-14.10",
"tax_amount": "0.60",
"reason": "QuickBooks Credit Memo Allocation.",
"invoice_number": "TED1",
"case_number": "TED1",
"case_id": "606",
"invoice_id": "1628",
"company_name": "Fox Sports",
"details": [
{
"record_id": "381",
"cost_id": "0",
"quantity": "1.00",
"duration": "",
"unit_charge": "7.50",
"gst": "0.00",
"exgst": "7.50",
"amount": "7.50",
"type": "Item",
"time_based": "0",
"date": "05-01-2024",
"charge_code": "",
"description": "Employee celebration -- Anniversary / Retirement",
"details": "",
"charge": null,
"milestone": "0",
"role": null,
"employee": "System"
},
{
"record_id": "380",
"cost_id": "0",
"quantity": "1.00",
"duration": "",
"unit_charge": "6.00",
"gst": "0.60",
"exgst": "6.00",
"amount": "6.60",
"type": "Item",
"time_based": "0",
"date": "05-01-2024",
"charge_code": "",
"description": "Catering -- food & beverage",
"details": "",
"charge": null,
"milestone": "0",
"role": null,
"employee": "System"
}
]
"last_update": "05-01-2024 04:13:01",
"last_update_utc": "2024-01-05T17:13:01Z"
},
]
2. Create Adjustment (api1/adjustments/create_adjustment)
This method will allow to create a new adjustment in IInsight.
URL
| Server | URL | HTTP type |
|---|---|---|
| UAT | https://api-uk-uat.iinsightonline.com/api1/adjustments/create_adjustment | POST |
| PRODUCTION | https://api-uk.iinsightonline.com/api1/adjustments/create_adjustment | POST |
Authorization
| Parameter | Value | Mandatory |
|---|---|---|
| Type | Bearer Token | Yes |
| Token | The token is generated using the /auth/login method | Yes |
Query Params
| Parameter | Value | Mandatory |
|---|---|---|
| invoice_id | A valid invoice id | Yes |
| transaction_date |
The transaction date. Format: YYYY-MM-DDThh:mm:ssZ (date and time in UTC ISO 8601) Example: 2024-02-29T12:28:01Z |
Yes |
| reason | A reason for the adjustment | Yes |
| detail |
A JSON String of an object config for the adjustment details. This object requires different fields for two cases: 1. Invoice Line Item Mode: This object requires the following fields: cost_id, quantity, rate, apply_gst. This mode uses a specific invoice line item (cost_id) to obtain data such as description, details, date, charge_code, gl_code, etc. 2. Manual Line Item Mode: This object requires the following attributes: time_based, quantity, rate, apply_gst, description, details, date, charge_code, gl_code. This method requires all above fields, because it is not based on a specific invoice line item. |
Yes |
| ↳ cost_id |
If sent, it means that you are working with Invoice Line Item Mode A positive integer value. An Invoice Line Item ID (cost_id) An Invoice Line Item ID cost_id (e.g. 123) |
Optional |
| ↳ quantity | A positive numeric value. The quantity value for the line item. (e.g. 10) | Yes |
| ↳ rate | A positive numeric value. The rate value for the line item. (e.g. 12.25) | Yes |
| ↳ apply_gst |
A boolean value to know if tax should be applied for the total amount calculation for this line item. Valid values: 1, 0, true, false. Please note that boolean values are not strings. |
Yes |
| ↳ time_based |
This field is required if you are not sending the "cost_id" value. Then you are working with Manual Line Item Mode. A boolean value to know if line item is based in time. This is used by IInsight to know if line item is an activity or item. Valid values: 1, 0, true, false. Please note that boolean values are not strings. |
Conditional |
| ↳ description |
This field is required if you are not sending the "cost_id" value. Then you are working with Manual Line Item Mode. A string value. The line item description. |
Conditional |
| ↳ details |
This field is required if you are not sending the "cost_id" value. Then you are working with Manual Line Item Mode. A string value. The line item description. |
Conditional |
| ↳ date |
This field is required if you are not sending the "cost_id" value. Then you are working with Manual Line Item Mode. A date for this line item. Format: YYYY-MM-DDThh:mm:ssZ (date and time in UTC ISO 8601) Example: 2024-02-29T12:28:01Z |
Conditional |
| ↳ charge_code |
This field is required if you are not sending the "cost_id" value. Then you are working with Manual Line Item Mode. A string value. A valid IInsight Service Contract Charge Code for this invoice. |
Conditional |
| ↳ gl_code |
This field is required if you are not sending the "cost_id" value. Then you are working with Manual Line Item Mode. This field is required General Ledger is enabled on IInsight. A string value. A valid General Ledger Code. |
Conditional |
Response Structure
A JSON object with the following attributes: success, message, data.
| Attribute | Value | Mandatory |
|---|---|---|
| success | A boolean value. "true" for success adjustment creation. "false" for failed adjustment creation. | Yes |
| message | A string message about the success value. | Yes |
| data | The available request result data. | Yes |
Failed Response
{
"success": false,
"message": "The detail line 0 has the following validations.",
"data":
[
"Invalid GL Code."
]
}
Success Response
{
"success": true,
"message": "Adjustment created.",
"data":
{
"adjustment_number": "JP20144258-A4",
"transaction_id": 2845
}
}