Get bookings

Returns a paginated list of bookings enriched with related entites data for integration use cases.

GET/api/integration/booking

Request

cURL

curl -X GET "https://dev.integration.cl.sodtrack-shared.sodtrack.com/api/integration/booking" \
  -H "Authorization: Bearer $SODTRACK_TOKEN" \
  -H "origin: <your-origin>"

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

Headers

Name	Type	Description
`origin`	string	—

Responses

Get bookings by reference

{
  "data": [
    {
      "id": 10452,
      "reference": "ORD-2025-001",
      "status": "accepted",
      "scheduledDate": "2025-03-15T09:00:00.000Z",
      "totalDurationMinutes": 90,
      "doneDate": null,
      "createdDate": "2025-03-10T14:22:00.000Z",
      "customer": {
        "id": 2001,
        "reference": "EXT-CUSTOMER-REF-001"
      },
      "stakeholder": {
        "id": "stakeholder-uuid-01",
        "reference": "STK-REF-001"
      },
      "service": {
        "id": 10,
        "name": "Instalación"
      },
      "variant": {
        "id": 321,
        "name": "Instalación cortinas",
        "type": "execution",
        "skus": [
          "install_curtains_sku"
        ]
      },
      "category": {
        "id": 5,
        "name": "Hogar"
      },
      "address": {
        "formattedAddress": "Av. Providencia 1234, Santiago, Chile",
        "coordinates": {
          "lat": -33.43324794409109,
          "lng": -70.58645659063548
        }
      },
      "originAddress": null,
      "saleChannel": {
        "id": 1,
        "name": "Canal principal",
        "reference": "E001",
        "coordinates": null
      },
      "project": {
        "id": 88,
        "reference": "PROJ-EXT-100"
      },
      "lead": null,
      "provider": {
        "id": 42,
        "reference": "PROV-REF-42",
        "name": "María",
        "lastname": "Técnica",
        "email": "maria.tecnica@example.com",
        "phone": "+56912345678",
        "identificationNumber": "12345678-9",
        "assignedTo": null
      },
      "bookingBundle": null,
      "price": 150000,
      "cost": 80000,
      "bookingAddOns": [
        {
          "id": 501,
          "name": "Material extra",
          "reference": "ADDON-REF-01"
        }
      ],
      "products": [
        {
          "id": 300,
          "name": "Cortina roller",
          "sku": "CURTAIN-001",
          "productType": "product",
          "quantity": 2,
          "serialNumber": null
        }
      ],
      "incidents": [
        {
          "id": 77,
          "reference": "INC-REF-77"
        }
      ],
      "alerts": [
        {
          "id": 23,
          "reference": "ALRT-E23423S2"
        }
      ],
      "notes": [
        {
          "id": 12,
          "note": "Cliente solicita ventana matutina.",
          "reference": null
        }
      ],
      "dynamicFormSnapshotFields": [
        {
          "id": "field-uuid-1",
          "reference": "purchase_channel",
          "value": "online",
          "type": "text",
          "snapshotId": "snapshot-uuid-1"
        }
      ]
    }
  ],
  "metadata": {
    "count": 1,
    "pageSize": 10,
    "pageNumber": 1,
    "totalPages": 1
  }
}

Error responses for this endpoint follow the shared error reference.

Purpose

Returns a paginated list of bookings enriched with related entites data for integration use cases.

Field Definitions

🔐 Authentication

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

🔎 Query parameters

Parameter	Type	Required	Description
`id`	`number`	❌	Filter by Sodtrack booking id. Positive integer (minimum `1`).
`reference`	`string`	❌	Filter by booking external reference.
`pageSize`	`number`	❌	Number of results per page. Min `1`, max `50`. Default `10`.
`pageNumber`	`number`	❌	Page index (1-based). Min `1`. Default `1`.

All filters provided are combined with AND. If neither id nor reference is sent, the endpoint returns the paginated list of all bookings ordered by id descending.

Example Request

code

GET /api/integration/booking?reference=ORD-2025-001
GET /api/integration/booking?id=10452
GET /api/integration/booking?pageSize=20&pageNumber=2

Response Example

json

{
  "data": [
    {
      "id": 10452,
      "reference": "ORD-2025-001",
      "status": "accepted",
      "scheduledDate": "2025-03-15T09:00:00.000Z",
      "quantity": 1,
      "totalDurationMinutes": 90,
      "doneDate": null,
      "createdDate": "2025-03-10T14:22:00.000Z",
      "customer": {
        "id": 2001,
        "reference": "EXT-CUSTOMER-REF-001"
      },
      "stakeholder": {
        "id": "stakeholder-uuid-01",
        "reference": "STK-REF-001"
      },
      "service": {
        "id": 10,
        "name": "Instalación"
      },
      "variant": {
        "id": 321,
        "name": "Instalación cortinas",
        "type": "execution",
        "skus": ["install_curtains_sku"]
      },
      "category": {
        "id": 5,
        "name": "Hogar"
      },
      "address": {
        "formattedAddress": "Av. Providencia 1234, Santiago, Chile",
        "coordinates": {
          "lat": -33.43324794409109,
          "lng": -70.58645659063548
        }
      },
      "originAddress": null,
      "saleChannel": {
        "id": 1,
        "name": "Canal principal",
        "reference": "E001",
        "coordinates": null
      },
      "project": {
        "id": 88,
        "reference": "PROJ-EXT-100"
      },
      "lead": null,
      "provider": {
        "id": 42,
        "reference": "PROV-REF-42",
        "name": "María",
        "lastname": "Técnica",
        "email": "maria.tecnica@example.com",
        "phone": "+56912345678",
        "identificationNumber": "12345678-9",
        "assignedTo": null
      },
      "bookingBundle": null,
      "price": 150000,
      "cost": 80000,
      "bookingAddOns": [
        {
          "id": 501,
          "name": "Material extra",
          "reference": "ADDON-REF-01"
        }
      ],
      "products": [
        {
          "id": 300,
          "name": "Cortina roller",
          "sku": "CURTAIN-001",
          "productType": "product",
          "quantity": 2,
          "serialNumber": null,
          "pricing": {
            "price": 45000,
            "cost": 30000,
            "currency": {
              "id": 2,
              "name": "CLP",
              "symbol": "$"
            }
          }
        },
        {
          "id": 415,
          "name": "Soporte de pared",
          "sku": "BRACKET-010",
          "productType": "component",
          "quantity": 4,
          "serialNumber": null,
          "pricing": {
            "price": 3500,
            "cost": null,
            "currency": null
          }
        }
      ],
      "incidents": [
        {
          "id": 77,
          "reference": "INC-REF-77"
        }
      ],
      "alerts": [
        {
          "id": 23,
          "reference": "ALRT-E23423S2"
        }
      ],
      "notes": [
        {
          "id": 12,
          "note": "Cliente solicita ventana matutina.",
          "reference": null
        }
      ],
      "dynamicFormSnapshotFields": [
        {
          "id": "field-uuid-1",
          "reference": "purchase_channel",
          "value": "online",
          "type": "text",
          "snapshotId": "snapshot-uuid-1"
        }
      ]
    }
  ],
  "metadata": {
    "count": 1,
    "pageNumber": 1,
    "pageSize": 10,
    "totalPages": 1
  }
}

Pagination (`metadata`)

Field	Type	Description
`count`	`number`	Total number of bookings matching the filters (across all pages).
`pageSize`	`number`	Page size used for this response.
`pageNumber`	`number`	Current page (1-based).
`totalPages`	`number`	Total pages for the current filters and `pageSize`.

Booking item (`data[]`)

Field	Type	Description
`id`	`number`	Sodtrack booking id.
`reference`	`string`	`null`
`status`	`string`	Booking status. One of: `created`, `searching`, `accepted`, `on_my_way_to_origin`, `arrived_to_origin`, `on_my_way`, `on_my_way_to_destination`, `arrived_to_destination`, `left_destination`, `done`, `cancelled`, `waiting_customer_to_set_date`, `waiting_scheduling_mechanism`, `waiting_assignment_mechanism`, `waiting_provider_to_propose_date`, `waiting_customer_to_accept_proposed_date`.
`scheduledDate`	`string` (ISO 8601)	`null`
`quantity`	`number`	Booking quantity.
`totalDurationMinutes`	`number`	`null`
`doneDate`	`string` (ISO 8601)	`null`
`createdDate`	`string` (ISO 8601)	Booking creation timestamp.
`customer`	`object`	`null`
`stakeholder`	`object`	`null`
`service`	`object`	`null`
`variant`	`object`	`null`
`category`	`object`	`null`
`address`	`object`	`null`
`originAddress`	`object`	`null`
`saleChannel`	`object`	`null`
`project`	`object`	`null`
`lead`	`object`	`null`
`provider`	`object`	`null`
`bookingBundle`	`object`	`null`
`price`	`number`	`null`
`cost`	`number`	`null`
`bookingAddOns`	`array`	Add-ons on the booking (`id`, `name`, `reference`).
`products`	`array`	Products and components linked to the booking, with pricing (see Product).
`incidents`	`array`	Incident references (`id`, `reference`).
`alerts`	`array`	Alert references (`id`, `reference`).
`notes`	`array`	Booking notes (`id`, `note`, `reference`).
`dynamicFormSnapshotFields`	`array`	Dynamic form field values captured on the booking (see Dynamic form field).

Nested reference objects

Objects such as customer, stakeholder, project, lead, incidents[], alerts[] and bookingBundle.bundleHead use:

Field	Type	Description
`id`	`number`	`string`
`reference`	`string`	`null`

Variant (`variant`)

Field	Type	Description
`id`	`number`	Variant id.
`name`	`string`	Variant name.
`type`	`string`	`"budget"` or `"execution"`.
`skus`	`array[string]`	SKUs linked to the variant.

Address (`address` / `originAddress`)

Field	Type	Description
`formattedAddress`	`string`	Human-readable address.
`coordinates`	`object`	`null`

Sales channel (`saleChannel`)

Field	Type	Description
`id`	`number`	Sales channel id.
`name`	`string`	Sales channel name.
`reference`	`string`	`null`
`coordinates`	`object`	`null`

Provider (`provider`)

Field	Type	Description
`id`	`number`	Provider id. When the assignee belongs to a company, this is the company.
`reference`	`string`	`null`
`name`	`string`	Provider first name.
`lastname`	`string`	Provider last name.
`email`	`string`	Provider email.
`phone`	`string`	`null`
`identificationNumber`	`string`	`null`
`assignedTo`	`object`	`null`

Bundle (`bookingBundle`)

Field	Type	Description
`bundleHead`	`object`	Bundle head booking (`id`, `reference`).
`bundledBookings`	`array`	Other bookings in the same bundle (`id`, `reference`), excluding the current one.

Product (`products[]`)

Field	Type	Description
`id`	`number`	Product id.
`name`	`string`	Product name.
`sku`	`string`	Product SKU.
`productType`	`string`	`"product"` or `"component"`.
`quantity`	`number`	Quantity linked to the booking. `1` per entry when the product is expanded by physical unit.
`serialNumber`	`string`	`null`
`pricing`	`object`	Unit pricing of the product for this booking (see Product pricing).

Product pricing (`products[].pricing`)

Field	Type	Description
`price`	`number`	`null`
`cost`	`number`	`null`
`currency`	`object`	`null`

Dynamic form field (`dynamicFormSnapshotFields[]`)

Field	Type	Description
`id`	`string`	Field instance id.
`reference`	`string`	Field reference in the form definition.
`value`	`string`	Submitted value.
`type`	`string`	Field type.
`snapshotId`	`string`	Parent snapshot id.

Error Responses

HTTP Status	Error	Description
`400 Bad Request`	`id must be an integer number` / `id must not be less than 1`	`id` is not a positive integer.
`400 Bad Request`	`pageSize must not be greater than 50` / `pageSize must not be less than 1`	`pageSize` out of range.
`400 Bad Request`	`pageNumber must not be less than 1`	`pageNumber` out of range.
`401 Unauthorized`	—	API key missing or invalid, or the request does not come from an authorized network.
`403 Forbidden`	—	The request origin is not allowed.
`500 Internal Server Error`	—	Unexpected server error. Contact Sodtrack support.

When the filters match no booking, data is an empty array and metadata.count is 0.

Business Rules & Constraints

Filters

id and reference are combined with AND. Sending both returns the booking only if it matches both values; if they point at different bookings the result is an empty page, not an error.
With no id or reference, the endpoint returns all bookings (paginated), ordered by id descending (newest first).
Unknown query parameters are ignored.

Pagination

pageNumber is 1-based (first page = 1).
Default pageSize is 10; maximum allowed is 50. Out-of-range values are rejected with 400 Bad Request.
metadata.count is the total of matching bookings; use it with pageSize to iterate pages.

Product pricing resolution

For each entry in products[], Sodtrack resolves pricing as follows:

Scenario	`price`	`cost`	`currency`
The product (or component) has an active area pricing that covers the area of the booking address	Area pricing price	Area pricing cost (`null` if not configured)	Currency of that area
No area pricing applies, and the product has a catalog price	Catalog price	`null`	`null`
No area pricing applies and no catalog price is loaded	`null`	`null`	`null`

The area is determined from the booking address. A booking without an address, or whose address is not inside any area, never uses area pricing.
Inactive area pricing configurations and configurations without a price are ignored.
A catalog price of 0 is treated as "no price loaded" and returned as null.
Prices are per unit; multiply by quantity to obtain totals.
Products and components are priced by the same rules; the pricing configuration is looked up according to productType.

Enriched payload

Each booking in data is built with related data loaded. A null nested object means that relation is not set on the booking.

Dynamic forms included

Snapshot fields are returned for every booking-related dynamic form flow configured for the booking entity and answered for that particular booking.

Data and format

Timestamps use ISO 8601 (UTC).
Query parameter values are passed as strings in the URL; id, pageSize and pageNumber are coerced to integers before validation.