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

4.8 KiB

sidebar_position, title
sidebar_position title
5 Quotes/Search

Quotes/Search

GET /DataHUB/rest/Quotes/Search

See API Overview & Conventions 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

{
  "Quotations": [ { ... } ],
  "TotalCount": 311
}

Quotation Object (base, no include flags)

{
  "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.
  • 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. :::

:::danger[2. 500 when lastUpdatedTo precedes lastUpdatedFrom]

GET /DataHUB/rest/Quotes/Search?...&lastUpdatedFrom=2026-07-17T00%3A00%3A00Z&lastUpdatedTo=2026-05-01T00%3A00%3A00Z
{ "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:

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