- Introduced new documentation for the DataHUB service, including purpose, roles, and business case. - Added detailed API reference for Quotes and Visits, including search endpoints and response structures. - Created sections for service records, time reports, and visits in the CustomerHUB documentation. - Implemented a change log and test plan for the DataHUB project. - Updated the introduction to include links to the new DataHUB documentation. - Modified navbar configuration to reflect changes in documentation structure.
126 lines
4.8 KiB
Markdown
126 lines
4.8 KiB
Markdown
---
|
|
sidebar_position: 5
|
|
title: Quotes/Search
|
|
---
|
|
|
|
# Quotes/Search
|
|
|
|
```
|
|
GET /DataHUB/rest/Quotes/Search
|
|
```
|
|
|
|
See [API Overview & Conventions](./overview) for pagination, identifiers, and response envelope conventions shared by all endpoints.
|
|
|
|
## Query Parameters
|
|
|
|
| Param | Type | Required | Description |
|
|
|---|---|---|---|
|
|
| `startIndex` | int | Yes | 0-based offset. |
|
|
| `maxRecords` | int | Yes | Max rows. `0` = all. |
|
|
| `lastUpdatedFrom` | ISO 8601 datetime | Yes | Filters `UpdatedOn >= lastUpdatedFrom`. |
|
|
| `lastUpdatedTo` | ISO 8601 datetime | No | Filters `UpdatedOn <= lastUpdatedTo`. Combines with `lastUpdatedFrom` as a closed range. |
|
|
| `status` | string | No | Filters by quote status name. Valid values: `Released`, `Closed`, `Planned`, `Cancelled`. |
|
|
| `site` | string | No | Filters by site `ExternalId` (e.g. `US001`). Invalid values return a clear error (see below). |
|
|
| `includeQuoteLines` | bool | No | Adds `QuotationLines[]` to each quote. |
|
|
| `includeQuoteCharges` | bool | No | Adds `QuotationCharges[]` to each quote. |
|
|
| `includeLaborWorksheet` | bool | No | Adds `LaborWorksheet` to each quote, when one exists. |
|
|
|
|
## Example Request
|
|
|
|
```
|
|
GET /DataHUB/rest/Quotes/Search?startIndex=0&maxRecords=10&lastUpdatedFrom=2026-05-01T00%3A00%3A00Z&lastUpdatedTo=2026-07-17T23%3A59%3A00Z&status=Released&site=US001&includeQuoteLines=true&includeQuoteCharges=true&includeLaborWorksheet=true
|
|
```
|
|
|
|
## Response Shape
|
|
|
|
```json
|
|
{
|
|
"Quotations": [ { ... } ],
|
|
"TotalCount": 311
|
|
}
|
|
```
|
|
|
|
### Quotation Object (base, no include flags)
|
|
|
|
```json
|
|
{
|
|
"QuoteId": 2627,
|
|
"QuotationNo": "A1000007",
|
|
"QuotationName": "Test RP",
|
|
"Customer": { "CustomerNo": "202703", "CustomerName": "21ST CENTURY CONCRETE - HUDSON" },
|
|
"Status": "Released",
|
|
"ApprovalStatus": "No Approvals",
|
|
"QuoteType": "Product with Install",
|
|
"Territory": { "TerritoryId": 185, "ExternalId": "US-1C", "Code": "US-1C", "Description": "Lower Great Lakes" },
|
|
"Region": { "ExternalId": "1", "Description": "Northeast" },
|
|
"Site": { "ExternalId": "US001", "Description": "Neponset" },
|
|
"ResponsiblePerson": { "ExternalId": "AARONL", "Description": "Aaron Lee" },
|
|
"OrderCoordinator": { "ExternalId": "SUSIEO", "Description": "Susie Orlandi" },
|
|
"CancelReason": { "ExternalId": "False", "Description": "False" },
|
|
"ExpirationDate": "2026-06-09",
|
|
"DeliveryDate": "2026-04-10",
|
|
"MinimumLeadTime": 2,
|
|
"MaximumLeadTime": 3,
|
|
"LeadTimeUnit": { "ExternalId": "CfEnum_DAYS", "Description": "Days" },
|
|
"CreatedOn": "2026-04-10T11:44:44Z",
|
|
"UpdatedOn": "2026-05-02T20:56:45Z",
|
|
"HubCreatedBy": "ruwanthika.premalal@hoist.tech",
|
|
"HubUpdatedBy": "thomas.soubliere@hoist.tech",
|
|
"ShipToAddress": {
|
|
"Id": 152972, "Country": "US", "State": "MA", "City": "HUDSON",
|
|
"AddressName": "21ST CENTURY CONCRETE", "StreetAddress": "560 MAIN ST",
|
|
"ExternalId": "1", "IsDeliveryAddress": true, "IsDefaultDeliveryAddr": true
|
|
}
|
|
}
|
|
```
|
|
|
|
`HubUpdatedBy` holds a user identifier (email); `CreatedOn`/`UpdatedOn` are the date fields.
|
|
|
|
### `include*` Flags — Added Fields
|
|
|
|
| Flag | Adds field | Notes |
|
|
|---|---|---|
|
|
| `includeQuoteLines=true` | `QuotationLines[]` | Array of quote line items. |
|
|
| `includeQuoteCharges=true` | `QuotationCharges[]` | Array of quote charges. |
|
|
| `includeLaborWorksheet=true` | `LaborWorksheet` | Singular object, not an array. Only present when the quote has one. |
|
|
|
|
## Pagination & Date Range Behavior (Verified)
|
|
|
|
- `startIndex`/`maxRecords`/`maxRecords=0` behave as described in [API Overview & Conventions](./overview).
|
|
- `lastUpdatedFrom` + `lastUpdatedTo` together produce a correct closed-range filter (verified: narrower windows return a strict subset of the wider window).
|
|
|
|
## Known Issues
|
|
|
|
:::danger[1. 500 on lastUpdatedFrom at/after current time]
|
|
See [API Overview & Conventions](./overview).
|
|
:::
|
|
|
|
:::danger[2. 500 when lastUpdatedTo precedes lastUpdatedFrom]
|
|
```
|
|
GET /DataHUB/rest/Quotes/Search?...&lastUpdatedFrom=2026-07-17T00%3A00%3A00Z&lastUpdatedTo=2026-05-01T00%3A00%3A00Z
|
|
```
|
|
```json
|
|
{ "Errors": ["Error executing query."], "StatusCode": 500 }
|
|
```
|
|
Expected: an empty result or a 400 validation error, not a 500. Neither date-range edge case (future date, inverted range) is validated before hitting the query engine.
|
|
:::
|
|
|
|
:::warning[3. status filter validates correctly, but still returns 500 instead of 400]
|
|
An invalid `status` value (e.g. `status=99999`) returns a descriptive error, but as an HTTP 500:
|
|
|
|
```json
|
|
{ "Errors": ["Invalid Quote Status"], "StatusCode": 500 }
|
|
```
|
|
:::
|
|
|
|
:::warning[4. site filter validates correctly, but still returns 500 instead of 400]
|
|
```
|
|
GET /DataHUB/rest/Quotes/Search?...&site=DOES_NOT_EXIST
|
|
```
|
|
```json
|
|
{ "Errors": ["Invalid Site"], "StatusCode": 500 }
|
|
```
|
|
|
|
Valid `site=US001` works as expected. The validation itself is correct; only the status code is questionable (client error reported as a server error).
|
|
:::
|