Add New Product Unit

Purpose

Registers equipment the customer already owns as a product unit located at one of their addresses.

Use it when your system detects an installed asset that Sodtrack does not know yet (for example, a pool the provider finds while executing a repair) and you need it tracked before putting it under a maintenance plan.

The unit is identified by product (productSku or productId) and placed at an address (addressId). The unit's owner is derived from the address: Sodtrack resolves the customer associated with it, so you do not send a customer identifier. The serial number is generated by Sodtrack and returned in the response.

This endpoint only creates the unit. To start its maintenance cycle, call Start Maintenance Plan afterwards with the returned productUnit.id.

Field Definitions

📦 Product

productSerialNumber is not accepted here: this endpoint creates the unit, so it has no serial number to be identified by yet.

🏠 Address

The address must belong to a customer and have a customer associated. Provider or sales channel addresses are rejected. To obtain valid address IDs for a customer, use Get Customer.

Example Request (by product SKU)

{
  "product": {
    "type": "productSku",
    "value": "SKU-PISCINA-001"
  },
  "address": {
    "type": "addressId",
    "value": "12345"
  }
}

Example Request (by product ID)

{
  "product": {
    "type": "productId",
    "value": "87"
  },
  "address": {
    "type": "addressId",
    "value": "12345"
  }
}

Response Example

200 OK

{
  "productUnit": {
    "id": 9871,
    "serialNumber": "7788001122336"
  }
}

Response Fields

Error Responses

Business Rules & Constraints

Product resolution

• When product.type is productSku, the SKU is resolved against the product catalog. If no product matches exactly, the request fails with Product not found in the product module.

• When product.type is productId, the value is used directly and must be a positive integer; it is not verified against the catalog before the unit is created, so an unknown ID surfaces as a rejection forwarded from the product module.

• productSerialNumber is not a valid product.type for this endpoint.

Address and ownership

• Only addressId resolves today. The addressReference type exists in the contract but fails explicitly instead of being silently ignored, because Sodtrack addresses have no external reference field yet.

• The customer is derived from the address, never sent by the caller: the address must be a customer address with a customer associated, or the request fails.

• The address is stored on the unit as a plain reference; changing the customer's address later does not move the unit.

Unit creation

• The serial number is generated by Sodtrack as an EAN-13 code (13 digits with check digit); it cannot be supplied by the caller.

• Every call creates a new unit. There is no idempotency key: repeating the same request registers the same equipment twice.

• The unit is created with no maintenance cycle. Starting it is a separate call to Start Maintenance Plan.

Errors and retries

• Failures are not swallowed: a 4xx means nothing was created and the request should be corrected, while a 502 means the product module failed and the call can be retried.

Data and format

• All identifiers are sent as strings inside the { type, value } selectors, even when they are numeric IDs.

• All timestamps follow the ISO 8601 format (UTC) where applicable.