Obtain Times

Returns, for one day, when a group of service variants can start to be executed together, in a single visit, at a location.

POST/api/integration/bundle/times

Request

cURL

curl -X POST "https://uat.integration.cl.sodtrack-shared.sodtrack.com/api/integration/bundle/times" \
  -H "Authorization: Bearer $SODTRACK_TOKEN" \
  -H "origin: <your-origin>"

Base URL: https://uat.integration.cl.sodtrack-shared.sodtrack.com · other environments

Headers

Name	Type	Description
`origin`	string	—

Responses

Obtain Times

{
  "timeRanges": [
    {
      "startTime": "09:00",
      "endTime": "13:00"
    },
    {
      "startTime": "14:00",
      "endTime": "18:00"
    }
  ]
}

Error responses for this endpoint follow the shared error reference.

Purpose

Returns, for one day, when a group of service variants can start to be executed together, in a single visit, at a location.

Use it after POST /api/integration/bundle/dates: send the same variants, quantities and addons, and one of the returned days.

Depending on how the Sodtrack tenant schedules visits, the answer is either a list of time ranges (the visit starts at some time within the range) or a list of exact start times.

Field Definitions

🔐 Authentication

Field	Type	Required	Description
`x-api-key` (header)	`string`	✅	External integration API key provided by Sodtrack.

🧩 Service variants

Field	Type	Required	Description
`variants`	`array`	✅	Variants of the group. Between 1 and 10 items. The same `type` + `value` cannot be repeated.
`variants[].type`	`string`	✅	How the variant is identified. One of: `"variantId"`, `"variantSku"`.
`variants[].value`	`string`	✅	Sodtrack variant id (positive integer as a string) when `type` is `"variantId"`, or the variant SKU (exact match) when `type` is `"variantSku"`.
`variants[].quantity`	`number`	❌	Quantity of the variant. Minimum `1`. Defaults to `1`.
`variants[].addons`	`array`	❌	Addons of the variant. The same `type` + `value` cannot be repeated within a variant.
`variants[].addons[].type`	`string`	✅ when addon sent	How the addon is identified. One of: `"addonId"`, `"addonReference"`.
`variants[].addons[].value`	`string`	✅ when addon sent	Sodtrack addon id (positive integer as a string) when `type` is `"addonId"`, or the addon reference when `type` is `"addonReference"`.
`variants[].addons[].quantity`	`number`	✅ when addon sent	Quantity of the addon. Minimum `1`.

🏠 Location

Field	Type	Required	Description
`addressId`	`number`	✅ when `coordinates` not sent	Id of an existing Sodtrack address.
`coordinates`	`object`	✅ when `addressId` not sent	Location of the visit.
`coordinates.lat`	`number`	✅ when `coordinates` sent	Latitude.
`coordinates.lng`	`number`	✅ when `coordinates` sent	Longitude.

When both are sent, addressId is used.

📅 Day

Field	Type	Required	Description
`date`	`string`	✅	Day to check (`YYYY-MM-DD`).

Example Request

json

{
  "variants": [
    {
      "type": "variantSku",
      "value": "SKU-INSTALLATION",
      "quantity": 2,
      "addons": [
        { "type": "addonReference", "value": "ADDON-EXTRA-HOSE", "quantity": 1 }
      ]
    },
    { "type": "variantSku", "value": "SKU-MAINTENANCE" },
    { "type": "variantId", "value": "63", "quantity": 2 }
  ],
  "addressId": 17,
  "date": "2026-10-05"
}

Response Example

201 Created, tenant that schedules by time ranges:

json

{
  "timeRanges": [
    { "startTime": "09:00", "endTime": "13:00" },
    { "startTime": "14:00", "endTime": "18:00" }
  ]
}

201 Created, tenant that schedules by exact start time:

json

{
  "hours": ["09:00", "09:30", "10:00", "14:30"]
}

Response Fields

Field	Type	Description
`timeRanges`	`array`	Returned when the tenant schedules by time ranges. Ranges of the day in which the visit can start. Empty when there is no availability.
`timeRanges[].startTime`	`string`	Start of the range (`HH:mm`).
`timeRanges[].endTime`	`string`	End of the range (`HH:mm`).
`hours`	`string[]`	Returned when the tenant does not use time ranges. Start times (`HH:mm`) at which the visit can start. Empty when there is no availability.

Only one of timeRanges or hours is returned, always the same one for a given tenant.

Error Responses

HTTP Status	Error	Description
`400 Bad Request`	Validation message, e.g. `date must be a valid ISO 8601 date string`	A field is missing, has an invalid value, or a variant or addon is repeated.
`400 Bad Request`	`NO_VARIANT_FOUND_FOR_ID` / `NO_VARIANT_FOUND_FOR_SKU`	A variant could not be found by its id or SKU.
`400 Bad Request`	`VARIANT_ID_IS_NOT_A_VALID_POSITIVE_INTEGER`	A `"variantId"` value is not a positive integer.
`400 Bad Request`	`ADDON_ID_IS_NOT_A_VALID_POSITIVE_INTEGER`	An `"addonId"` value is not a positive integer.
`400 Bad Request`	`NO_ACTIVE_ADDON_OPERATION_FOUND_FOR: ADDON_{ID	SKU}: {value} VARIANT_ID: {variantId}`
`400 Bad Request`	`NO_COVERAGE_FOR_ADDON: {addonId} (Reference: {reference})`	The addon is not offered at the location.
`401 Unauthorized`	—	The API key is missing or invalid.
`404 Not Found`	`ADDRESS_NOT_FOUND`	`addressId` does not match an existing address.
`500 Internal Server Error`	—	Unexpected server error. Contact Sodtrack support.

Business Rules & Constraints

When a start time is available

A start time is returned when at least one provider that executes every variant of the group at the location can start the visit at that time and execute all the variants back to back, within the operating hours of the variants and respecting the booking anticipation, capacity and holidays that apply to a booking.

When several variants have different booking anticipation, the longest one applies to the whole group.

Time ranges

When the tenant schedules by time ranges, a range is returned only if the visit can start at some time within it; ranges without any available start time are left out.

Duration of the visit

Each variant counts as variant duration × quantity, plus addon duration × addon quantity for each of its addons, the same duration the booking gets when it is created. The visit needs the sum of the durations of all the variants of the group in consecutive time.

Consistency with dates

Use a day returned by POST /api/integration/bundle/dates for the same variants, quantities, addons and location. A day not returned there has no start times.

Variants without coverage

If any variant of the group is not offered at the location, the group cannot be executed there and the result is empty.

Identification

A variant can be identified by id or by SKU, and both can be mixed in the same request.
If two entries identify the same variant (for example its id and its SKU), the first one is used and the variant is counted once.

Addons

Each addon must be offered for its variant and must be offered at the location. Otherwise the request is rejected (see Error Responses); addons are never silently ignored.

Scope

Availability is computed for bookings without origin address, without products with a promised delivery date and with automatic provider assignment. When the booking is created with any of them, the offered times are indicative: the travel time from the origin, the delivery date of the products or the chosen provider may leave no availability for the group.