Create acquisition

Creates an acquisition in Sodtrack from an external system, together with its items (products, product units, or extended warranties) and an associated customer.

POST/api/integration/acquisition

Request

cURL

curl -X POST "https://uat.integration.cl.sodtrack-shared.sodtrack.com/api/integration/acquisition" \
  -H "Authorization: Bearer $SODTRACK_TOKEN"

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

Responses

Create acquisition

{
  "id": 73457,
  "customer": {
    "id": 32813,
    "name": "Lucía",
    "lastname": "Fernández",
    "email": "lucia.fernandez@example.com",
    "phone": "+5491150000001",
    "reference": "EXT-CUST-1001"
  },
  "acquisitionDate": "2026-06-07T00:00:00.000Z",
  "items": [
    {
      "id": 89250,
      "itemType": "serialNumber",
      "product": {
        "id": 6,
        "sku": "MOTO-BAJ-BOX150",
        "name": "Bajaj Boxer 150"
      },
      "productUnit": {
        "id": 41020,
        "serialNumber": "BOX150-CHS-2402"
      }
    }
  ]
}

Error responses for this endpoint follow the shared error reference.

Purpose

Creates an acquisition in Sodtrack from an external system, together with its items (products, product units, or extended warranties) and an associated customer.

A single request can carry multiple items. For each item you indicate how to resolve it (sku, serialNumber, or warrantyReference) and the reference value. Sodtrack resolves each item against its product catalog and registers the acquisition.

The customer is resolved automatically: if a matching customer already exists it is reused; otherwise a new one is created.

For extended warranty items, you can choose when the warranty validity starts (extendedWarrantyStartMode): on the acquisition date (default), right after the latest warranty of the covered product ends, or on a specific date. The response returns the resulting validity period of each base and extended warranty.

Optionally, the request can attach dynamic form responses (at customer, acquisition, and/or item level), attribute the acquisition to a sale channel, and trigger the creation of a work order for a given service variant.

Authentication

Header	Required	Description
`x-api-key`	✅	Sodtrack inbound integration API key.

The endpoint is restricted to Sodtrack's private integration network. Requests from unauthorized origins are rejected.

Field Definitions

🧾 Acquisition

Field	Type	Required	Description
`reference`	`string`	✅	Your unique reference for this acquisition. Must be non-empty and unique; reusing it returns `409 Conflict`.
`acquisitionDate`	`string (date)`	✅	Acquisition date. ISO format, e.g. `"2026-06-07"` or a full ISO datetime.
`relatedAcquisitionReference`	`string`	❌	Reference of a previously created acquisition to relate this one to.
`serviceVariantReferenceTriggered`	`string`	❌	When sent, Sodtrack also creates a work order for the service variant with this external reference. See Work order trigger.

🧍 Customer (`customer`)

Field	Type	Required	Description
`customer.name`	`string`	✅	Customer first name.
`customer.lastName`	`string`	❌	Customer last name.
`customer.email`	`string`	❌	Customer email. Used to match an existing customer. Recommended to avoid duplicates; if omitted a temporary email is generated.
`customer.reference`	`string`	❌	Your external reference for the customer. Used to match an existing customer when email does not match.
`customer.phoneType`	`string`	❌	One of: `"MOBILE"`, `"HOME"`, `"WORK"`.
`customer.phoneNumber`	`string`	❌	Customer phone number.
`customer.identificationType`	`string`	❌	One of: `"PASSPORT"`, `"DRIVER_LICENSE"`, `"NATIONAL_ID"`, `"TAX_ID"`, `"OTHER"`.
`customer.identificationNumber`	`string`	❌	Customer identification number.
`customer.identificationNumberCountry`	`string`	❌	Country of the identification number.
`customer.dynamicForms`	`array`	❌	Dynamic form responses attached to the customer. See Dynamic forms.

📦 Items (`items[]`)

At least one item is required.

Field	Type	Required	Description
`items[].item.type`	`string`	✅	How to resolve the item. One of: `"sku"` (product), `"serialNumber"` (product unit), `"warrantyReference"` (extended warranty).
`items[].item.value`	`string`	✅	The reference value matching `type` (the product SKU, the product unit serial number, or the warranty external reference).
`items[].quantity`	`number`	❌	Quantity for the item. Defaults to `1`.
`items[].extendedWarrantyStartMode`	`string`	❌	Only for `warrantyReference` items; ignored for other types. When the extended warranty validity starts. One of: `"ACQUISITION_DATE"` (default), `"LAST_WARRANTY_END_DATE"`, `"CUSTOM_DATE"`. See Extended warranty validity.
`items[].extendedWarrantyStartDate`	`string (date)`	✅ when `extendedWarrantyStartMode` is `"CUSTOM_DATE"`	Extended warranty validity start date. ISO format, e.g. `"2027-01-15"` or a full ISO datetime. Ignored for other modes.
`items[].dynamicForms`	`array`	❌	Dynamic form responses attached to this item. See Dynamic forms.

📣 Sale channel (`saleChannel`)

Field	Type	Required	Description
`saleChannel`	`object`	❌	Sale channel the acquisition is attributed to. If omitted, the acquisition is created without one.
`saleChannel.type`	`string`	✅ when object sent	How to identify the sale channel. One of: `"reference"` (look it up by its string reference), `"id"` (the numeric primary key).
`saleChannel.value`	`string`	✅ when object sent	The value used to identify the sale channel (the reference string, or the numeric id as string). An unknown or invalid channel is rejected with `400 Bad Request` (`INVALID_SALES_CHANNEL`).

📝 Dynamic forms (`dynamicForms[]`)

Acquisition-level dynamic forms are sent in the top-level dynamicForms. The same shape applies to customer.dynamicForms and items[].dynamicForms.

Field	Type	Required	Description
`dynamicForms[].formReference`	`string`	✅	Reference of an existing, active dynamic form.
`dynamicForms[].values`	`array`	✅	Field responses for the form.
`dynamicForms[].values[].fieldReference`	`string`	✅	Reference of a field defined in the form.
`dynamicForms[].values[].value`	`string`	❌	Value for that field.
`dynamicForms[].values[].secondaryValue`	`string`	❌	Secondary answer for composite fields (e.g. currency amount). Free-form string.

Example Request

Complete example (customer + item-level and acquisition-level dynamic forms + sale channel + work order trigger):

json

{
  "reference": "ACQ-EXT-1001",
  "acquisitionDate": "2026-06-07",
  "serviceVariantReferenceTriggered": "SERVICE-MOTO-10000KM",
  "customer": {
    "name": "Lucía",
    "lastName": "Fernández",
    "email": "lucia.fernandez@example.com",
    "phoneType": "MOBILE",
    "phoneNumber": "+5491150000001",
    "identificationType": "NATIONAL_ID",
    "identificationNumber": "30111222",
    "identificationNumberCountry": "AR",
    "reference": "EXT-CUST-1001",
    "dynamicForms": [
      {
        "formReference": "FORM-CUSTOMER",
        "values": [{ "fieldReference": "customer_segment", "value": "Premium" }]
      }
    ]
  },
  "items": [
    {
      "item": { "type": "serialNumber", "value": "BOX150-CHS-2402" },
      "quantity": 1,
      "dynamicForms": [
        {
          "formReference": "FORM-ACQ-ITEM",
          "values": [{ "fieldReference": "item_condition", "value": "nuevo" }]
        }
      ]
    }
  ],
  "saleChannel": { "type": "reference", "value": "SALES-CHANNEL-WEB" },
  "dynamicForms": [
    {
      "formReference": "FORM-ACQUISITION",
      "values": [{ "fieldReference": "acquisition_channel", "value": "web" }]
    }
  ]
}

Minimal example:

json

{
  "reference": "ACQ-EXT-1002",
  "acquisitionDate": "2026-06-07",
  "customer": {
    "name": "Diego",
    "email": "diego.pereyra@example.com"
  },
  "items": [
    { "item": { "type": "sku", "value": "MOTO-HND-CG125" }, "quantity": 1 }
  ]
}

Product with extended warranties (one starting on a specific date, one starting right after the base warranty ends):

json

{
  "reference": "ACQ-EXT-1003",
  "acquisitionDate": "2026-10-05",
  "customer": {
    "name": "Diego",
    "email": "diego.pereyra@example.com"
  },
  "items": [
    { "item": { "type": "sku", "value": "MOTO-YAM-CRY110" }, "quantity": 1 },
    {
      "item": { "type": "warrantyReference", "value": "WAR-EXT-24M" },
      "quantity": 1,
      "extendedWarrantyStartMode": "CUSTOM_DATE",
      "extendedWarrantyStartDate": "2027-01-15"
    },
    {
      "item": { "type": "warrantyReference", "value": "WAR-EXT-24M" },
      "quantity": 1,
      "extendedWarrantyStartMode": "LAST_WARRANTY_END_DATE"
    }
  ]
}

Extended warranty sold separately, related to the acquisition of the covered product and chained after its latest warranty:

json

{
  "reference": "ACQ-EXT-1004",
  "acquisitionDate": "2026-11-20",
  "relatedAcquisitionReference": "ACQ-EXT-1001",
  "customer": {
    "name": "Lucía",
    "email": "lucia.fernandez@example.com"
  },
  "items": [
    {
      "item": { "type": "warrantyReference", "value": "WAR-EXT-24M" },
      "quantity": 1,
      "extendedWarrantyStartMode": "LAST_WARRANTY_END_DATE"
    }
  ]
}

Response Example

json

{
  "id": 73457,
  "customer": {
    "id": 32813,
    "name": "Lucía",
    "lastname": "Fernández",
    "email": "lucia.fernandez@example.com",
    "phone": "+5491150000001",
    "reference": "EXT-CUST-1001"
  },
  "acquisitionDate": "2026-06-07T00:00:00.000Z",
  "items": [
    {
      "id": 89250,
      "itemType": "PRODUCT",
      "product": { "id": 6, "sku": "MOTO-BAJ-BOX150", "name": "Bajaj Boxer 150" },
      "productUnit": { "id": 41020, "serialNumber": "BOX150-CHS-2402" },
      "baseWarrantyExecution": {
        "id": 60570,
        "validityStartDate": "2026-06-07T00:00:00.000Z",
        "validityEndDate": "2028-06-07T00:00:00.000Z",
        "warranty": {
          "id": 2,
          "name": "Factory Warranty 24 Months",
          "externalReference": "WAR-FACTORY-24M",
          "type": "BASE",
          "durationValue": 24,
          "durationMetric": { "id": 1, "name": "MESES" }
        }
      }
    }
  ]
}

Response for the request with extended warranties (ACQ-EXT-1003, customer omitted):

json

{
  "id": 73459,
  "acquisitionDate": "2026-10-05T00:00:00.000Z",
  "items": [
    {
      "id": 89411,
      "itemType": "PRODUCT",
      "product": { "id": 4, "sku": "MOTO-YAM-CRY110", "name": "Yamaha Crypton 110" },
      "baseWarrantyExecution": {
        "id": 60573,
        "validityStartDate": "2026-10-05T00:00:00.000Z",
        "validityEndDate": "2027-10-05T00:00:00.000Z",
        "warranty": {
          "id": 1,
          "name": "Factory Warranty 12 Months",
          "externalReference": "WAR-FACTORY-12M",
          "type": "BASE",
          "durationValue": 12,
          "durationMetric": { "id": 1, "name": "MESES" }
        }
      }
    },
    {
      "id": 89412,
      "itemType": "EXTENDED_WARRANTY",
      "product": { "id": 4, "sku": "MOTO-YAM-CRY110", "name": "Yamaha Crypton 110" },
      "extendedWarrantyExecution": {
        "id": 60574,
        "validityStartDate": "2027-01-15T00:00:00.000Z",
        "validityEndDate": "2029-01-15T00:00:00.000Z",
        "warranty": {
          "id": 4,
          "name": "Extended Warranty 24 Months",
          "externalReference": "WAR-EXT-24M",
          "type": "EXTENDED",
          "durationValue": 24,
          "durationMetric": { "id": 1, "name": "MESES" }
        }
      }
    },
    {
      "id": 89413,
      "itemType": "EXTENDED_WARRANTY",
      "product": { "id": 4, "sku": "MOTO-YAM-CRY110", "name": "Yamaha Crypton 110" },
      "extendedWarrantyExecution": {
        "id": 60575,
        "validityStartDate": "2027-10-06T00:00:00.000Z",
        "validityEndDate": "2029-10-06T00:00:00.000Z",
        "warranty": {
          "id": 4,
          "name": "Extended Warranty 24 Months",
          "externalReference": "WAR-EXT-24M",
          "type": "EXTENDED",
          "durationValue": 24,
          "durationMetric": { "id": 1, "name": "MESES" }
        }
      }
    }
  ]
}

Response Fields

Field	Type	Description
`id`	`number`	Sodtrack acquisition identifier.
`customer.id`	`number`	Sodtrack customer identifier.
`customer.name`	`string`	Customer first name.
`customer.lastname`	`string`	Customer last name.
`customer.email`	`string`	Customer email.
`customer.phone`	`string`	Customer phone.
`customer.reference`	`string`	Customer external reference.
`acquisitionDate`	`string (date-time)`	Acquisition date.
`items[].id`	`number`	Sodtrack acquisition item identifier.
`items[].itemType`	`string`	Resolved item type. One of: `"PRODUCT"` (`sku` and `serialNumber` items), `"EXTENDED_WARRANTY"` (`warrantyReference` items).
`items[].product`	`object`	Resolved product (`id`, `sku`, `name`). For extended warranty items, the product the warranty covers.
`items[].productUnit`	`object`	Resolved product unit (`id`, `serialNumber`). Present when the item is a product unit.
`items[].baseWarrantyExecution`	`object`	Base warranty validity of a `PRODUCT` item. Present when the product has a base warranty.
`items[].extendedWarrantyExecution`	`object`	Extended warranty validity of an `EXTENDED_WARRANTY` item.
`items[].*WarrantyExecution.id`	`number`	Sodtrack warranty execution identifier.
`items[].*WarrantyExecution.validityStartDate`	`string (date-time)`	Start of the warranty validity.
`items[].*WarrantyExecution.validityEndDate`	`string (date-time)`	End of the warranty validity (start plus the warranty duration). `null` when it cannot be computed from the warranty duration.
`items[].*WarrantyExecution.warranty`	`object`	The warranty: `id`, `name`, `externalReference`, `type` (`"BASE"` or `"EXTENDED"`), `durationValue`, `durationMetric` (`id`, `name`).

Error Responses

HTTP Status	Error	Description
`400 Bad Request`	—	Missing or invalid fields, an invalid/unknown dynamic form, or an item that cannot be resolved (e.g. product, product unit, or warranty not found).
`400 Bad Request`	—	Invalid `extendedWarrantyStartMode`, or `extendedWarrantyStartDate` missing or invalid when `extendedWarrantyStartMode` is `"CUSTOM_DATE"`.
`400 Bad Request`	`INVALID_SALES_CHANNEL`	The sale channel could not be resolved from `saleChannel`.
`401 Unauthorized`	—	API key missing or invalid.
`403 Forbidden`	—	Origin not authorized for the inbound integration network.
`409 Conflict`	`ACQUISITION_ALREADY_EXISTS`	An acquisition already exists for the given `reference`.
`500 Internal Server Error`	—	Unexpected server error. Contact Sodtrack support.

Business Rules & Constraints

Customer resolution

Sodtrack resolves the customer before creating the acquisition:

Scenario	Behavior
`customer.email` matches an existing customer	The existing customer is reused.
No email match but `customer.reference` matches	The existing customer is reused.
No match	A new customer is created (a temporary email is generated when none is provided).

When an existing customer is reused, the remaining customer.\* fields are not updated.

Dynamic forms

Dynamic forms can be attached at three levels: customer, the acquisition (top-level dynamicForms), and each item (items[].dynamicForms).

Scenario	Behavior
All sent forms are valid	The acquisition is created and the form responses are stored.
A form is invalid (unknown `formReference`, or a value that does not satisfy the form)	The request is rejected with `400 Bad Request` and nothing is created. Forms are validated before the acquisition is created.

Item resolution

Each item is resolved against the Sodtrack product catalog using item.type and item.value:

`item.type`	`item.value` must be	Resolves to
`sku`	a product SKU	a product
`serialNumber`	a product unit serial number	a product unit (and its product)
`warrantyReference`	a warranty external reference	an extended warranty, applied to a product the warranty covers: from the acquisition in `relatedAcquisitionReference` when sent, otherwise from the products in the same request

If any item cannot be resolved, the request is rejected with 400 Bad Request.

Extended warranty validity

Product items get their base warranty validity from the acquisition date. For each warrantyReference item, the extended warranty validity start depends on extendedWarrantyStartMode; the end is always the start plus the warranty duration.

`extendedWarrantyStartMode`	Validity starts
Not sent or `"ACQUISITION_DATE"`	On `acquisitionDate`.
`"CUSTOM_DATE"`	On `extendedWarrantyStartDate`. Any date is accepted, including dates before `acquisitionDate`.
`"LAST_WARRANTY_END_DATE"`	The day after the latest warranty of the covered product unit ends. See below.

With "LAST_WARRANTY_END_DATE", Sodtrack chains the extension after the coverage the product already has:

Scenario	Validity starts
The covered product unit is known and has warranties (base or extended)	The day after the warranty that ends last.
The product unit is not known (e.g. the product was sold by `sku`) or has no warranties	The day after the base warranty of the covered product ends.
The covered product has no base warranty	On `acquisitionDate`.

The covered product unit is known when the extension is related (relatedAcquisitionReference) to an acquisition whose product was sold by serialNumber.

Work order trigger

When serviceVariantReferenceTriggered is sent, Sodtrack additionally creates a work order:

Same customer as the acquisition.
One work order item per acquisition item that resolved to a product (carrying the product unit when present).
Built on a best-effort basis: if the service variant reference does not exist, or no acquisition item resolved to a product, the work order is not created and the acquisition is still returned successfully.

Idempotency

reference must be unique. Re-sending the same reference returns 409 Conflict.

Request

Responses

Purpose

Authentication

Field Definitions

🧾 Acquisition

🧍 Customer (customer)

📦 Items (items[])

📣 Sale channel (saleChannel)

📝 Dynamic forms (dynamicForms[])

Example Request

Response Example

Response Fields

Error Responses

Business Rules & Constraints

Customer resolution

Dynamic forms

Item resolution

Extended warranty validity

Work order trigger

Idempotency

🧍 Customer (`customer`)

📦 Items (`items[]`)

📣 Sale channel (`saleChannel`)

📝 Dynamic forms (`dynamicForms[]`)