Files
jaime.meza 928a4451f7 Add DataHUB documentation and API reference
- 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.
2026-11-17 10:42:21 -05:00

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).
:::