# Allocate a zimarker code and couple it in one call

Allocates the next zimarker code for the calling organization (always synchronous) and couples it to a new track. The synchronous variant (async=false, default) additionally waits for coupling and returns the resulting track alongside the allocated code and its marker image with 200. The asynchronous variant (async=true) couples in the background and returns 202 with the allocated code, its marker image and an operation identifier (no track). imageDelivery selects the image form: BASE64 (default) returns the marker inline as base64 in markerImage; URL returns its public image URL in markerImageUrl instead of inline bytes. The supplied WMS identifier is stored as-is and NOT validated against any WMS connector.

Endpoint: POST /integration/rest/api/v1/track/get-and-couple
Version: v0
Security: X-AUTH-KEY

## Query parameters:

  - `async` (boolean)
    When true, couple in the background and return 202 with the allocated code, image and an operation identifier; when false (default), wait and return 200 with the track too.

  - `imageDelivery` (string)
    Marker image delivery form: BASE64 (default) returns the image inline as base64 in markerImage; URL returns the public image URL in markerImageUrl.
    Enum: "BASE64", "URL"

## Request fields (application/json):

  - `wmsId` (string, required)
    External asset identifier (WMS id) stored on the track. It is NOT validated against any WMS connector — an identifier with no matching WMS record still couples.
    Example: "PAL-001"

  - `customFields` (array)
    Custom field values to set on the track. Each fieldKey must match a configured track custom field; unknown keys are rejected with CUSTOM_FIELD_MISSING.

  - `customFields.fieldKey` (string, required)
    System key (name) of the custom field; must match a configured field.
    Example: "CARRIER"

  - `customFields.fieldValue` (string)
    Value to set. For NUMERIC fields send the number as a string; for DATE fields send an ISO-8601 date-time. A blank/null value clears the existing value.
    Example: "DHL Express"

## Response 200 fields (*/*):

  - `markerCode` (string)
    The allocated zimarker code.
    Example: 123456

  - `markerImage` (string)
    The allocated marker rendered as a 1-bit, 600x600 black-and-white PNG, base64-encoded (inline). Present only when imageDelivery is BASE64 (the default).

  - `markerImageUrl` (string)
    The allocated marker image's public, stable URL ({base-path}/{markerCode}.png). Present only when imageDelivery is URL.
    Example: "https://acme.zimark.link/integration/rest/api/v1/zmarker-code/image/123456.png"

  - `track` (object)
    The resulting coupled track (standard integration track representation). Present only on the synchronous variant; omitted on the asynchronous variant, which couples in the background.

  - `track.createDate` (string)

  - `track.updateDate` (string)

  - `track.deepLink` (string)
    Deep link URL to open this entity in Ops.App.

  - `track.trackCode` (string)
    Unique track code.

  - `track.wmsId` (string)
    External asset identifier provided by WMS.

  - `track.status` (string)
    Current status of the track.
    Enum: "SCHEDULED_FOR_RETIREMENT", "ACTIVE", "NOT_ACTIVE", "FLAGGED"

  - `track.zimarkCodes` (array)
    Associated Zimark codes for this track.

  - `track.zimarkCodes.zimarkMarkerValue` (string)
    Unique Zimark marker value encoded/printed on the label.

  - `track.zimarkCodes.markerType` (string)
    Marker type (layout/type) of this coupled marker.
    Enum: "MARKER_3X3", "MARKER_3X4", "PROPRIETARY", "ARUCO", "ZMARKER"

  - `track.zimarkCodes.coupledAt` (string)
    Timestamp when this marker was coupled to the track.

  - `track.manifests` (array)
    Manifests that include this track.

  - `track.manifests.externalIdentifier` (string)
    External unique identifier for this manifest.

  - `track.manifests.manifestStatus` (string)
    Current status of the manifest.
    Enum: "PLANNED", "TO_DO", "IN_PROGRESS", "COMPLETED", "CANCELLED"

  - `track.manifests.totalAssetsCount` (integer)
    Total assets attached to this manifest, excluding invalid loadings (WRONGLY_LOADED, UNKNOWN_LOADING).

  - `track.manifests.loadedAssetsCount` (integer)
    Successfully loaded assets in this manifest, excluding invalid loadings.

  - `track.manifests.deleted` (boolean)
    Indicates whether the manifest is soft-deleted.

  - `track.manifests.shipmentSummaryUrl` (string)
    Public URL to the Shipment Summary page for this manifest. Present only when manifest status is COMPLETED. Does not expire.

  - `track.customFields` (array)
    Custom fields attached to this track.

  - `track.customFields.fieldCaption` (string)
    Human-readable caption of the custom field.

  - `track.customFields.fieldName` (string)
    System key of the custom field.

  - `track.customFields.fieldValue` (string)
    Assigned value for this custom field.

  - `track.labels` (array)
    Labels assigned to this track.

  - `track.labels.name` (string)
    Human-readable label name.

  - `track.retirementDate` (string)
    Date when the track was retired.

  - `track.sku` (string)
    Assigned SKU value, or null when unassigned or the SKU feature is disabled.

  - `track.client` (object)
    Assigned Client, or null when unassigned or the Client feature is disabled.

  - `track.client.id` (string)
    Internal Client UUID.

  - `track.client.displayName` (string)
    Client display name.

  - `track.client.externalId` (string)
    Client external ID.

  - `track.wmsLocation` (string)
    Pallet location as reported by the client's WMS, or null when unset or the WMS Location feature is disabled.

  - `track.wmsLocationUpdatedAt` (string)
    Timestamp of the last WMS Location change, or null when no value is set or the WMS Location feature is disabled.

  - `operationId` (string)
    Operation identifier correlating the eventual coupling outcome (delivered via the COUPLING_SUCCEEDED / COUPLING_FAILED webhook) to this request. Present only on the asynchronous variant.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

## Response 202 fields (*/*):

  - `markerCode` (string)
    The allocated zimarker code.
    Example: 123456

  - `markerImage` (string)
    The allocated marker rendered as a 1-bit, 600x600 black-and-white PNG, base64-encoded (inline). Present only when imageDelivery is BASE64 (the default).

  - `markerImageUrl` (string)
    The allocated marker image's public, stable URL ({base-path}/{markerCode}.png). Present only when imageDelivery is URL.
    Example: "https://acme.zimark.link/integration/rest/api/v1/zmarker-code/image/123456.png"

  - `track` (object)
    The resulting coupled track (standard integration track representation). Present only on the synchronous variant; omitted on the asynchronous variant, which couples in the background.

  - `track.createDate` (string)

  - `track.updateDate` (string)

  - `track.deepLink` (string)
    Deep link URL to open this entity in Ops.App.

  - `track.trackCode` (string)
    Unique track code.

  - `track.wmsId` (string)
    External asset identifier provided by WMS.

  - `track.status` (string)
    Current status of the track.
    Enum: "SCHEDULED_FOR_RETIREMENT", "ACTIVE", "NOT_ACTIVE", "FLAGGED"

  - `track.zimarkCodes` (array)
    Associated Zimark codes for this track.

  - `track.zimarkCodes.zimarkMarkerValue` (string)
    Unique Zimark marker value encoded/printed on the label.

  - `track.zimarkCodes.markerType` (string)
    Marker type (layout/type) of this coupled marker.
    Enum: "MARKER_3X3", "MARKER_3X4", "PROPRIETARY", "ARUCO", "ZMARKER"

  - `track.zimarkCodes.coupledAt` (string)
    Timestamp when this marker was coupled to the track.

  - `track.manifests` (array)
    Manifests that include this track.

  - `track.manifests.externalIdentifier` (string)
    External unique identifier for this manifest.

  - `track.manifests.manifestStatus` (string)
    Current status of the manifest.
    Enum: "PLANNED", "TO_DO", "IN_PROGRESS", "COMPLETED", "CANCELLED"

  - `track.manifests.totalAssetsCount` (integer)
    Total assets attached to this manifest, excluding invalid loadings (WRONGLY_LOADED, UNKNOWN_LOADING).

  - `track.manifests.loadedAssetsCount` (integer)
    Successfully loaded assets in this manifest, excluding invalid loadings.

  - `track.manifests.deleted` (boolean)
    Indicates whether the manifest is soft-deleted.

  - `track.manifests.shipmentSummaryUrl` (string)
    Public URL to the Shipment Summary page for this manifest. Present only when manifest status is COMPLETED. Does not expire.

  - `track.customFields` (array)
    Custom fields attached to this track.

  - `track.customFields.fieldCaption` (string)
    Human-readable caption of the custom field.

  - `track.customFields.fieldName` (string)
    System key of the custom field.

  - `track.customFields.fieldValue` (string)
    Assigned value for this custom field.

  - `track.labels` (array)
    Labels assigned to this track.

  - `track.labels.name` (string)
    Human-readable label name.

  - `track.retirementDate` (string)
    Date when the track was retired.

  - `track.sku` (string)
    Assigned SKU value, or null when unassigned or the SKU feature is disabled.

  - `track.client` (object)
    Assigned Client, or null when unassigned or the Client feature is disabled.

  - `track.client.id` (string)
    Internal Client UUID.

  - `track.client.displayName` (string)
    Client display name.

  - `track.client.externalId` (string)
    Client external ID.

  - `track.wmsLocation` (string)
    Pallet location as reported by the client's WMS, or null when unset or the WMS Location feature is disabled.

  - `track.wmsLocationUpdatedAt` (string)
    Timestamp of the last WMS Location change, or null when no value is set or the WMS Location feature is disabled.

  - `operationId` (string)
    Operation identifier correlating the eventual coupling outcome (delivered via the COUPLING_SUCCEEDED / COUPLING_FAILED webhook) to this request. Present only on the asynchronous variant.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

## Response 400 fields (*/*):

  - `code` (string)
    Error code

  - `message` (string)
    Error message

  - `timeStamp` (integer)
    Timestamp

  - `correlationId` (string)
    Correlation id

## Response 403 fields (*/*):

  - `code` (string)
    Error code

  - `message` (string)
    Error message

  - `timeStamp` (integer)
    Timestamp

  - `correlationId` (string)
    Correlation id

## Response 500 fields (*/*):

  - `code` (string)
    Error code

  - `message` (string)
    Error message

  - `timeStamp` (integer)
    Timestamp

  - `correlationId` (string)
    Correlation id