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://dev.integration.cl.sodtrack-shared.sodtrack.com/api/integration/acquisition" \
  -H "Authorization: Bearer $SODTRACK_TOKEN"

Base URL: https://dev.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.

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[].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 }
  ]
}

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": "serialNumber",
      "product": { "id": 6, "sku": "MOTO-BAJ-BOX150", "name": "Bajaj Boxer 150" },
      "productUnit": { "id": 41020, "serialNumber": "BOX150-CHS-2402" }
    }
  ]
}

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.
`items[].product`	`object`	Resolved product (`id`, `sku`, `name`). Present when the item resolves to a product.
`items[].productUnit`	`object`	Resolved product unit (`id`, `serialNumber`). Present when the item is a product unit.

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_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 (resolved against the products in the same request)

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

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

Work order trigger

Idempotency

🧍 Customer (`customer`)

📦 Items (`items[]`)

📣 Sale channel (`saleChannel`)

📝 Dynamic forms (`dynamicForms[]`)