Contracts API: ChangeContractCostCentre

ChangeContractCostCentre

This method changes the contracts clients cost centre and creates a cost centre change event.

This works in the same way as creating a Contracts / Events Cost Centre Change.

Supplementary SWAGGER documentation is available here: https://api.catch-e.com/docs/#/Contract%20%2F%20Events/changeContractCostCentre

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Go to Roles / Apis and check on ContractEvents:changeContractCostCentre

Note: This API can also be enabled for the following external roles: fleetmanager, groupmanager and package_employer.
Contact your Account Manager if you would like to enable this permission for one of these roles

HTTP Method

Use the HTTP Method 'POST' for consuming this web service.

URL Examples

https://api.demo.catch-e.com/authenticate

https://api..catch-e.com/authenticate

/fm/contract/events/{contract_id}/change-cost-centre

Parameters - Path Variables

Headers

Input Fields (Body)

Input Fields (JSON)

{ "client_cost_centre_id": "100430", "contract_id": "102888", "event_date": "2024-03-01", "description": "API TEST 4 changeCostCentre", "allocation": "70.56", "contract_event_action_id": "100000", "due_date": "2024-03-01", "completed_flag": "yes", "override_warnings_flag": "yes"}

Successful Response Example

{ "contract_event_id": "109980", "contract_id": "102888", "posting_class_id": "100032", "attachment_id": null, "event_date": "2024-03-01", "table_name": "fm_client_cost_centres", "record_id": "100430", "event_value": "MATT CC1", "description": "API TEST 4 changeCostCentre", "contract_event_value_id": null, "contract_event_description_id": "0", "contract_event_action_id": "100000", "due_date": "2024-03-01", "completed_flag": "yes", "event_amount": 70.56, "message_type": null, "user_id": "11244", "last_edit": "2024-06-25 01:27:39", "status_flag": "active"}

Error Response Details

"detail": "API endpoint not found"

| 422 Unprocessable Entity | | |

"contract_id": { "noRecordFound": "No record matching the input was found"}}

| The contractid passed is not stored in the database. E.g. '1'. If the user is external, contracts that are not linked to the user's login will not be visible. I.e. the contractid may be valid, but it is not visible to this user. | |

"client_cost_centre_id": {"invalidValue": "Specified client cost centre does not belong to the client associated with the specified contract"}},

| The clientcostcentre_id is stored in the database, but does not belong to the linked client. | |

"client_cost_centre_id":{"noRecordFound": "No record matching the input was found"}}

| The clientcostcentre_id is not stored in the database, or it is not available to the authenticated user. | |

 "event_date": { "dateInvalidDate": "The input does not appear to be a valid date"}},

| You must enter a valid date as 'YYYY-MM-DD', or 0 (to leave event_date blank. | |

 "detail": "Failed Validation"|{"contract_event_description_id":{"noRecordFound": "No record matching the input was found"}}

| The contracteventdescription_id is not stored in the database | |

 "allocation": { "notBetween": "The input is not between '1' and '100', inclusively"}},

| The allocation cannot be higher than 100 or lower than 0. | |

"contract_event_action_id":{"noRecordFound": "No record matching the input was found"}}

| The contracteventaction_id is not stored in the database. | |

 "warning_messages": { "client_cost_centre_id": { "costCentreAlreadyAllocated": "Specified client cost centre is already allocated to this contract"}},

| Cost Centre already allocated to contract. |
| 403 - Forbidden | | |

"detail": "Forbidden"

| You do not have permissions for this request. |

CreateContractEvents

This method creates contract events.

This works in the same way as creating a new Contracts / Events record in the system.

If you want to store an attachment to the event you have created, follow this up with the API Save an attachment .

Supplementary SWAGGER documentation is available here: https://api.catch-e.com/docs/#/Contract%20%2F%20Events/createContractEvents(https://api.catch-e.com/docs/#/Contract%20%2F%20Events/createContractEvents)

Excluded Classes

The events listed below aren't supported by this API.

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Go to Roles / Apis and check on ContractEvents:Create

Note: This API is not configured for external use.
Contact your Account Manager to discuss access to this API.

HTTP Method

Use the HTTP Method 'POST' for consuming this web service.

URL Examples

https://api.demo.catch-e.com/authenticate

https://api..catch-e.com/authenticate

https://api.test.catch-e.com/fm/contract/events

Parameters - Path Variables

Headers

Input Fields (Body)

Input Fields (JSON)

{ "contract_id": "100002", "posting_class_id": "100036", "event_date": "2023-10-26", "event_value": "Test", "description": "API TEST", "event_amount": 0, "contract_event_action_id": "100002", "due_date": "2023-10-26", "completed_flag": "no", "status_flag": "active"}

Successful Response Example

{ "contract_event_id": "109364", "contract_id": "102355", "posting_class_id": "100091", "attachment_id": null, "event_date": "0000-00-00", "table_name": null, "record_id": null, "event_value": "", "description": "", "contract_event_value_id": null, "contract_event_description_id": "0", "contract_event_action_id": "0", "due_date": "0000-00-00", "completed_flag": "no", "event_amount": 0, "message_type": null, "user_id": "0", "last_edit": "2023-08-18 02:47:34", "status_flag": "active",}

Error Response Details

{""posting_class_id ":{"noRecordFound": "No record matching the input was found"}}

| The postingclassid passed is not stored in the database. E.g. '1' | |

{"posting_class_id":{"noRecordFound": "Event cannot be created for this Posting Class as it is in excluded list or event flag is set to no "}}

| The postingclassid passed cannot be used to create an event as it is a coded event, listed above. | |

{"contract_event_value_id":{"noRecordFound": "No record matching the input was found"}}

| The contracteventvalue_id passed is not stored in the database. E.g. '1' | |

{"contract_event_description_id":{"noRecordFound": "No record matching the input was found"}}

| The contracteventdescription_id passed is not stored in the database. E.g. '1' | |

{""posting_class_id ":{" invalidRecord": "event type requires Contract Event Values"}}

| The postingclassid passed requires contracteventvalue_id to be passed. | |

{""posting_class_id ":{" invalidRecord": "event type requires Contract Event description"}}

| The postingclassid passed requires contracteventdescription_id to be passed. |
| 423 - Locked | |
| "detail": "Locked" | Either the Contract is being edited or Billing is being processed. Try again once the Contract is no longer in use or the Billing process has completed. |
| 403 - Forbidden | |
| "detail": "Forbidden" | You do not have permissions for this request. |

GetContractBudgets

Overview

Beta function

Allows you to retrieve Budget details for a Contract.

A single Contract may have 1000's of records depending on Periodic Interval, Posting Classes and Term (eg Weekly Pay Cycle with 10 Posting Classes (FIN, MAINT, REG etc) over 60 months will have 2600 Budget records.

Use the Billing Period, Posting Class Code and Page filters to return a manageable set of data.

Contract Budget Web Services use an alternative authentication protocol.

HTTP Method

Use the HTTP Method 'GET' for consuming this web service.

Input Fields (Body)

Input URL Examples

For all Contract Budgets from all Billing Periods:

https://api.catch-e.com/beta/fm/contract/budgets?contract_id=100000

For all Budgets from a single period:

https://api.catch-e.com/beta/fm/contract/budgets?contract_id=100000&billing_period=10&page=1&page_size=30

A single Billing Period can be obtained by using the API "id" found in the results from an earlier call. For example:

https://api.test.catch-e.com/beta/fm/contract/budgets/cf6a070492ab0bcd02f9de708082d1ad043e4bad

(Successful) Output Example

{ "_links": { "self": { "href": "https://api.test.catch-e.com/fm/contract/budgets/?contract_id=102255&billing_period=10&posting_class_code=MAINT&page=1&page_size=30" }, "first": { "href": "https://api.test.catch-e.com/fm/contract/budgets/?contract_id=102255&billing_period=10&posting_class_code=MAINT&page_size=30" }, "last": { "href": "https://api.test.catch-e.com/fm/contract/budgets/?contract_id=102255&billing_period=10&posting_class_code=MAINT&page=1&page_size=30" } }, "_embedded": { "contract_budgets": [ { "id": "cf6a070492ab0bcd02f9de708082d1ad043e4bad", "contract_id": 102255, "posting_class_id": 100012, "billing_period": 10, "billing_period_item_no": 1, "billing_type_flag": "periodic", "billing_interval": "monthly", "billing_date": "2016-09-01", "payment_method": "direct-debit", "amount_net": 27.73, "amount_gst": 2.77, "status_flag": "pending", "posting_class_code": "MAINT", "_links": { "self": { "href": "https://api.test.catch-e.com/fm/contract/budgets/cf6a070492ab0bcd02f9de708082d1ad043e4bad" } } } ] }, "page_count": 1, "page_size": 30, "total_items": 1, "page": 1}

Error Codes

Example error output

{ "warning_messages": { "fieldName": { "warningException": "A textual description of the warning exception." } }, "validation_messages": { "fieldName": { "validationException": "A textual description of the validation exception." } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"}