Available Hours by Date

Retrieves available time slots for a given date, based on the requested location, service variant, and optional provider parameters.

POST/api/integration/hours/check

Request

cURL

curl -X POST "https://dev.integration.cl.sodtrack-shared.sodtrack.com/api/integration/hours/check" \
  -H "Authorization: Bearer $SODTRACK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "location": { //Required
        "type": "string", //"coordinates" | "areaId" | "areaReference",
        "value": "number | Object" //number | { lat: number, lng: number }
    },
    "variant": { //Required
        "type": "string", //'variantSku' | 'variantId'
        "value": "string"
    },
    "provider": {
        "type": "string", //'providerId' | 'providerReference'
        "value": "string"
    },
    "date": "YYYY-MM-dd" //Required
}'

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

Request body

application/json

{
    "location": { //Required
        "type": "string", //"coordinates" | "areaId" | "areaReference",
        "value": "number | Object" //number | { lat: number, lng: number }
    },
    "variant": { //Required
        "type": "string", //'variantSku' | 'variantId'
        "value": "string"
    },
    "provider": {
        "type": "string", //'providerId' | 'providerReference'
        "value": "string"
    },
    "date": "YYYY-MM-dd" //Required
}

Responses

Available Hours by Date

{
  "timeRanges": [
    {
      "startTime": "08:00",
      "endTime": "10:00"
    },
    {
      "startTime": "14:00",
      "endTime": "16:30"
    }
  ]
}

Error responses for this endpoint follow the shared error reference.

Purpose

Retrieves available time slots for a given date, based on the requested location, service variant, and optional provider parameters.

Depending on the tenant configuration, the response may return either:

A list of specific times (in 30-minute intervals), or
A list of time ranges ({ startTime, endTime }) when time ranges are configured at the tenant level.

This endpoint allows client systems to display accurate, real-time scheduling options for a specific date.

Field Definitions

Field	Type	Required	Description
`location`	`object`	✅	Defines the geographical reference for checking service availability.
`location.type`	`string`	✅	Determines how the location is identified. Accepted values:
• `"coordinates"` — Uses geographic coordinates.
• `"areaId"` — Uses the internal Sodtrack area identifier.
• `"areaSku"` — Uses the SKU associated with a predefined service area.
`location.value`	`object` or `number` or `string`	✅	The value corresponding to the selected `location.type`:

If type = "coordinates" → must be an object: { "lat": number, "lng": number }
If type = "areaId" → must be a number (internal area ID).
If type = "areaSku" → must be a string (area SKU). | | variant | object | ✅ | Identifies the specific service variant for which to check availability. | | variant.type | string | ✅ | Type of variant identifier. Options: "variantSku" or "variantId". | | variant.value | string | ✅ | The SKU or ID of the variant corresponding to the selected variant.type. | | provider | object | ❌ | (Optional) Restricts availability to a specific contractor. | | provider.type | string | ❌ | Type of provider identifier. Options: "providerId" or "providerReference". | | provider.value | string | ❌ | The corresponding provider ID or external reference. | | date | string | ✅ | The specific date for which to retrieve available hours. Format: YYYY-MM-DD. |

Sample Requests

Example 1 — Retrieve hours for coordinates

code

{
  "location": {
    "type": "coordinates",
    "value": { "lat": -33.4489, "lng": -70.6693 }
  },
  "variant": {
    "type": "variantSku",
    "value": "install_curtains_sku"
  },
  "date": "2025-10-10"
}

Example 2 — Retrieve hours for a specific provider

code

{
  "location": {
    "type": "areaSku",
    "value": "SANTIAGO_RM"
  },
  "variant": {
    "type": "variantId",
    "value": "567"
  },
  "provider": {
    "type": "providerId",
    "value": "999"
  },
  "date": "2025-10-10"
}

Success Responses (200 OK)

Example A — Tenant configured for specific times

code

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

Example B — Tenant configured for time ranges

code

{
  "timeRanges": [
    { "startTime": "08:00", "endTime": "10:00" },
    { "startTime": "14:00", "endTime": "16:30" }
  ]
}

Response Fields

Field	Type	Description
`hours`	`array[string]`	(If applicable) List of available start times in `HH:mm` format, spaced at 30-minute intervals.
`timeRanges`	`array[object]`	(If applicable) List of available time windows. Each object includes:
• `startTime`: Start time of the range (`HH:mm`).
• `endTime`: End time of the range (`HH:mm`).

Note: The API will return either hours or timeRanges, depending on tenant configuration.

Error Responses

HTTP Status	Error Code / Key	Description
`400 Bad Request`	`InvalidParameters`	Missing or invalid request parameters.
`401 Unauthorized`	—	Authentication failed or token expired.
`403 Forbidden`	—	The API key or origin is not authorized to access this endpoint.
`404 Not Found`	—	No availability found for the given date or parameters.
`500 Internal Server Error`	—	Unexpected server-side error. Contact Sodtrack support.

Business Logic Notes

Availability is derived from contractor schedules, coverage zones, and existing bookings.
When the tenant is configured for time ranges, returned windows are inclusive and may vary in length (e.g., 2-hour blocks).
When configured for specific times, availability is expressed in 30-minute intervals.
{ "hours": [] }{ "timeRanges": [] }

or
All times are expressed in local time relative to the contractor’s region or the defined coverage area.