Create work order

Creates one or more work orders in Sodtrack from an external system.

POST/api/integration/work-order

Request

cURL

curl -X POST "https://dev.integration.cl.sodtrack-shared.sodtrack.com/api/integration/work-order" \
  -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

Create work order

[
  {
    "id": 1024,
    "externalReference": "EXT-WO-0001",
    "customer": {
      "id": 2001,
      "name": "María",
      "lastname": "Gómez",
      "email": "maria.gomez@example.com"
    },
    "provider": {
      "id": 3001,
      "name": "Taller Motos Racing"
    },
    "stakeholder": null,
    "workOrderServiceVariant": {
      "id": 18,
      "name": "Service 10.000 km"
    },
    "product": {
      "id": 1,
      "sku": "MOTO-HND-CG125",
      "name": "Honda CG 125"
    },
    "productUnit": {
      "id": 1,
      "serialNumber": "CG125-CHS-2401"
    },
    "executionDateTime": null
  }
]

Error responses for this endpoint follow the shared error reference.

Purpose

Creates one or more work orders in Sodtrack from an external system.

A single request targets one product and a quantity; one work order is created per unit of quantity, and the response is an array with one entry per created work order.

The customer is resolved or created automatically. The service variant and product are resolved from the references you provide. Optionally, you can assign an existing provider, attribute the work orders to a sales channel, and associate specific product units to the first work orders.

Authentication

Header	Required	Description
`x-api-key`	✅	External integration API key provided by Sodtrack.

Field Definitions

🧾 Work order

Field	Type	Required	Description
`reference`	`string`	✅	External reference stored on every created work order.
`quantity`	`integer`	✅	Number of work orders to create (minimum `1`).

🧍 Customer

The customer is matched by email first, then by reference; if no match exists it is created.

Field	Type	Required	Description
`customer.name`	`string`	✅	Customer first name / name.
`customer.lastName`	`string`	❌	Customer last name.
`customer.email`	`string`	❌	Used as the primary identity to match an existing customer.
`customer.reference`	`string`	❌	External reference; used to match a customer when email does not match.
`customer.identificationType`	`string`	❌	One of: `"PASSPORT"`, `"DRIVER_LICENSE"`, `"NATIONAL_ID"`, `"TAX_ID"`, `"OTHER"`.
`customer.identificationNumber`	`string`	❌	Identification number.
`customer.identificationNumberCountry`	`string`	❌	Country of the identification number.
`customer.phoneType`	`string`	❌	One of: `"MOBILE"`, `"HOME"`, `"WORK"`.
`customer.phoneNumber`	`string`	❌	Phone number.

🧩 Service variant

Field	Type	Required	Description
`workOrderServiceVariant.type`	`string`	✅	One of: `"variantId"`, `"externalReference"`. Determines how `value` is interpreted.
`workOrderServiceVariant.value`	`string`	✅	Internal variant id when `type` is `"variantId"`, or the variant external reference when `type` is `"externalReference"`.

📦 Product

Field	Type	Required	Description
`product.type`	`string`	✅	One of: `"productId"`, `"productSku"`, `"productSerialNumber"`.
`product.value`	`string`	✅	Product id / sku / unit serial number, per `type`. When a serial number is sent, the product that owns that unit is used.

📦 Product units (optional)

Field	Type	Required	Description
`productUnits`	`array`	❌	Units to associate. Length must be `<= quantity`; the first work orders are associated at product-unit level, the rest only at product level.
`productUnits[].type`	`string`	✅ when a unit is sent	One of: `"productUnitId"`, `"productSerialNumber"`.
`productUnits[].value`	`string`	✅ when a unit is sent	Product unit id or unit serial number, per `type`.

👷 Provider assignment (optional)

Field	Type	Required	Description
`providerReference`	`string`	❌	Reference of an existing provider to assign to all created work orders. If omitted, the work orders are created without a provider.

📣 Sales channel (optional)

Field	Type	Required	Description
`saleChannel.type`	`string`	✅ when object sent	One of: `"reference"`, `"id"`. Determines how `value` is interpreted.
`saleChannel.value`	`string`	✅ when object sent	Sales channel reference when `type` is `"reference"`, or the numeric sales channel id (sent as a string) when `type` is `"id"`.

The sales channel is applied to every created work order. It is not echoed back in the response.

🧍 Stakeholder (optional)

Field	Type	Required	Description
`stakeholder.name`	`string`	✅ when stakeholder sent	Stakeholder name.
`stakeholder.lastname`	`string`	❌	Stakeholder last name.
`stakeholder.reference`	`string`	❌	External reference.
`stakeholder.email`	`string`	❌	Email.
`stakeholder.phone`	`string`	❌	Phone.
`stakeholder.identificationNumber`	`string`	❌	Identification number.
`stakeholder.identificationNumberCountry`	`string`	❌	Country of the identification number.

Example Request

json

{
  "reference": "EXT-WO-0001",
  "quantity": 1,
  "customer": {
    "name": "María",
    "lastName": "Gómez",
    "email": "maria.gomez@example.com",
    "reference": "EXT-CUSTOMER-002"
  },
  "providerReference": "PROVIDER-REF-A",
  "workOrderServiceVariant": { "type": "externalReference", "value": "SERVICE-VARIANT-REF" },
  "saleChannel": { "type": "reference", "value": "SALES-CHANNEL-WEB" },
  "product": { "type": "productSku", "value": "MOTO-HND-CG125" },
  "productUnits": [{ "type": "productSerialNumber", "value": "CG125-CHS-2401" }]
}

Minimal valid request

json

{
  "reference": "EXT-WO-0002",
  "quantity": 1,
  "customer": { "name": "Juan" },
  "workOrderServiceVariant": { "type": "variantId", "value": "18" },
  "product": { "type": "productId", "value": "6" }
}

Response Example

json

[
  {
    "id": 1024,
    "externalReference": "EXT-WO-0001",
    "customer": { "id": 2001, "name": "María", "lastname": "Gómez", "email": "maria.gomez@example.com" },
    "provider": { "id": 3001, "name": "Taller Motos Racing" },
    "stakeholder": null,
    "workOrderServiceVariant": { "id": 18, "name": "Service 10.000 km" },
    "product": { "id": 1, "sku": "MOTO-HND-CG125", "name": "Honda CG 125" },
    "productUnit": { "id": 1, "serialNumber": "CG125-CHS-2401" },
    "executionDateTime": null
  }
]

Response Fields

Field	Type	Description
`id`	`number`	Unique Sodtrack identifier of the created work order.
`externalReference`	`string`	The `reference` sent in the request.
`customer`	`object`	Customer summary (id, name, last name, email).
`provider`	`object`	Assigned provider summary, or `null` if no provider was assigned.
`stakeholder`	`object`	Stakeholder summary, or `null` if none was sent.
`workOrderServiceVariant`	`object`	Resolved service variant summary.
`product`	`object`	Resolved product data (id, sku, name, …).
`productUnit`	`object`	Associated product unit, or `null` if the work order is only at product level.
`executionDateTime`	`string`	Scheduled execution date-time, or `null`. This endpoint assigns a provider but does not schedule, so it is `null`.

One response entry is returned per created work order (quantity entries).

Error Responses

HTTP Status	Error	Description
`400 Bad Request`	`InvalidParameters`	A required field is missing or invalid (e.g. `quantity` < 1, or `type` not in the allowed values for variant / product / product units).
`400 Bad Request`	—	A referenced entity could not be resolved: service variant, product (by sku), product unit (by serial), or `providerReference` not found. Also when `productUnits` length exceeds `quantity`.
`400 Bad Request`	`INVALID_SALES_CHANNEL`	`saleChannel.value` is not a valid sales channel reference, or is not a positive integer when `type` is `"id"`.
`401 Unauthorized`	—	Missing or invalid `x-api-key`.
`404 Not Found`	—	`saleChannel.type` is `"id"` and no sales channel exists with that id.
`500 Internal Server Error`	—	Unexpected server error. Contact Sodtrack support.

Business Rules & Constraints

Quantity and response

quantity work orders are created for the product, and the response is an array with one entry per work order.

Customer resolution

The customer is matched by email first, then by reference. If a match is found it is reused as-is; if not, a new customer is created. Sending the same email repeatedly resolves to the same customer.

Provider assignment

providerReference must match an existing provider — this endpoint does not create providers. When provided, the provider is assigned to every created work order. When omitted, the work orders are created without a provider (it can be assigned later). Scheduling is not performed here, so executionDateTime is null.

Sales channel attribution

saleChannel is optional. When sent, the resolved sales channel is applied to every work order created by the request; when omitted, the work orders are created without one.

Selector	`value` contains	Not found
`saleChannel.type = "reference"`	Sales channel reference.	`400 Bad Request` with `INVALID_SALES_CHANNEL`.
`saleChannel.type = "id"`	Numeric sales channel id, sent as a string.	`404 Not Found`. A non-numeric or non-positive value returns `400 Bad Request` with `INVALID_SALES_CHANNEL`.

The sales channel is not returned in the response.

Service variant and product resolution

Selector	`value` contains
`workOrderServiceVariant.type = "variantId"`	Internal variant id.
`workOrderServiceVariant.type = "externalReference"`	Variant external reference.
`product.type = "productId"`	Internal product id.
`product.type = "productSku"`	Product sku.
`product.type = "productSerialNumber"`	A unit serial number; the product that owns that unit is used.

Product unit association

productUnits length must be <= quantity. The first work orders are associated at product-unit level (in the order provided); any remaining work orders are associated only at product level. Each unit is identified by productUnitId or productSerialNumber.