openapi: 3.0.1
info:
  title: UDS API
  version: 2.0.0
  description: >
    This document describes the **Partner API v2** provided by UDS — a loyalty

    platform that connects businesses with customers through mobile and web
    applications.


    The Partner API is designed for developers who integrate UDS loyalty program
    into

    POS systems, e-commerce platforms, mobile apps, or any third-party
    application

    that processes customer transactions.



    ## What you can do with Partner API


    - **Settings** — retrieve your company's loyalty program configuration
    (discount policies, membership tiers, reward rates)


    - **Customers** — search, list, and retrieve customer profiles with point
    balances and membership tier information


    - **Operations** — create purchase transactions, calculate discounts and
    cashback, process refunds, award bonus points


    - **Goods** — manage product catalog (categories, items, variants,
    inventory, images)


    - **Goods Orders** — process online orders from UDS marketplace (accept,
    modify, complete, cancel)


    - **Webhooks** — receive real-time notifications about operations, new
    customers, and orders


    - **Tags** — manage customer segmentation tags



    ## Common API Use Case



    The following scenario describes a typical checkout integration with UDS.

    Review all available endpoints to implement more advanced scenarios such as

    online ordering, product catalog management, or customer segmentation.



    1. When partner's application is ready for checkout it may suggest a

    customer getting a discount and earn reward points. In order to achieve

    this, the customer should have a UDS application and be able to generate a

    promo code (QR code) and provide it to the application (e.g., type the code

    into a checkout form).


    2. The customer opens the mobile application and selects "Discount" action.

    A new promo code is shown to the customer.


    3. The customer provides this promo code to the application, so it may be

    used for further requests.



    **NB!** *The promo code is not an identifier of the customer. It has a short

    life-time period and may be used only once. The application should not

    persist the code.*



    4. The application executes a "[Get Customer](#!/partner/get_customer)"

    request to obtain customer info and current amount of available reward

    points.


    5. Then the application may request the customer, whether he/she would like

    to pay for goods using available reward points.


    6. The customer specifies (types into a form) amount of points to withdraw

    and submits a checkout form.


    7. The application executes a "[Post Purchase](#!/partner/post_purchase)"

    request to submit purchase details, withdraw reward points and track

    purchase data in UDS CRM.


    8. Then the client receives a discount and his/her referral tiers earn

    reward points according to marketing settings.



    ## How to use API



    API provide access to API-methods via URI paths. In order to use an API the

    application should be able to make a HTTPS request and to parse the

    response. The API is stateless by design, so the client should provide all

    data required for request processing in each request. Information required

    for request processing (business logic) is represented as a part of URI

    string and/or as content of the request body (for POST/PUT methods).

    Information required for data exchange infrastructure (e.g., authorization

    handling) is represented via custom request headers.



    The response format is JSON (please, check specification of each method

    regarding actual objects' structures). Your methods will be the standard

    HTTP methods: GET, POST or PUT. Partner API is based on open standards, so

    you can use any web development language to access the API.



    ### URI



    Each API method has a bound URI path. Therefore each request sent to the

    server will have destination according to the following format:

    `https://<base_uri>/<method_path>/<additional_qualifier>`



    Base URI to access the API is `https://'api.uds.app/partner/v2`.



    ### Request Headers



    There are several headers, which should be placed on each request in order

    to meet transportation infrastructure requirements.



    <table>


    <thead>


    <tr>


    <th>Name</th>


    <th>Format (Data Type)</th>


    <th>Description</th>


    </tr>


    </thead>


    <tbody><tr>


    <td><strong>Common Headers</strong></td>


    <td></td>


    <td></td>


    </tr>


    <tr>


    <td>Accept</td>


    <td>MIME Type</td>


    <td>should be <code>application/json</code></td>


    </tr>


    <tr>


    <td>Accept-Charset</td>


    <td>String</td>


    <td>should be <code>utf-8</code></td>


    </tr>


    <tr>


    <td>Content-Type</td>


    <td>MIME Type</td>


    <td>should be <code>application/json</code>;<br> applicable for POST

    method</td>


    </tr>


    <tr>


    <td><strong>Custom Headers</strong></td>


    <td></td>


    <td></td>


    </tr>


    <tr>


    <td>X-Origin-Request-Id</td>


    <td>UUID</td>


    <td>identifier of the request used by the application;<br> may be omitted,

    but it's recommended to use it</td>


    </tr>


    <tr>


    <td>X-Request-Id</td>


    <td>UUID</td>


    <td>identifier of the request used by the Partner API</td>


    </tr>


    <tr>


    <td>X-Timestamp</td>


    <td>ISO 8601 Date</td>


    <td>date and time when request was originated</td>


    </tr>


    </tbody>


    </table>



    ### Data Types



    Here are special notices regarding data types used by the Partner API.

    Please consider this notices as requirements, since not following them may

    result in lack of functionality, errors or unpredictable behavior.



    #### Numbers and Rounding



    All numbers given to API **must** be rounded to two decimal places with

    "round half up" method. All responses from the server do also follow this

    rule; so every field, which is calculated on the server side, will have not

    more than two decimal digits and the number will be rounded with "half up"

    method.



    #### UUID



    The Partner API uses UUID 4 (or similar) to distinguish each request sent by

    the application. Clients should set headers `X-Origin-Request-Id` in

    requests and log (if possible) `X-Request-Id` set by the server in order to

    simplify debugging and to get a proper support in case of errors. It should

    be guaranteed, that there will be no duplication in these identifiers at

    least during a reasonable time period. At least these identifier should not

    be reused for further requests.



    #### Timestamps and dates



    For any timestamp or date in Partner API, we use [ISO

    8601](https://en.wikipedia.org/wiki/ISO_8601) format.



    Where we use timestamps:


    * `X-Timestamp` header


    * `dateCreated` field for operation


    * other headers or fields having explicit declaration of `Date` or `ISO 8601

    Date` types.



    ### Making Requests



    Clients should set headers `X-Origin-Request-Id` with UUID value and

    `X-Timestamp` with ISO-8601 timestamp value to all requests.


    On response server generates and sets new UUID to `X-Request-Id` and

    timestamp to `X-Timestamp` headers. If request contains

    `X-Origin-Request-Id` header then server sets it to response.



    **Example:**



    ```


    X-Origin-request-Id: 8c828ee7-e7b2-4631-a3e4-b18987962556


    X-Timestamp: 2016-07-08T13:17:39,245+00:00


    ```




    ### Response Codes and Errors



    The Partner API uses standard HTTP status codes in order to specify, whether

    the request was successful or not. Some responses may also contain

    `errorCode` field which contains a detailed explanation of the error

    occurred. It is expected, that all requests resulted in 4xx (client-side

    error) response status will not be retried until the source of the error is

    not eliminated.



    #### Response Codes



    <table>


    <thead>


    <tr>


    <th>Response code</th>


    <th>Description</th>


    </tr>


    </thead>


    <tbody><tr>


    <td><code>200</code></td>


    <td>Okay. API call was successful</td>


    </tr>


    <tr>


    <td><code>400</code></td>


    <td>Validation error or business logic error has occurred</td>


    </tr>


    <tr>


    <td><code>403</code></td>


    <td>Access denied, given authentication token is not set or has insufficient

    permissions</td>


    </tr>


    <tr>


    <td><code>404</code></td>


    <td>Either requested entity or requested api-method or path does not

    exist</td>


    </tr>


    </tbody></table>



    #### Error object



    When API-method call results in an error then response will contain JSON

    error object.


    For most of all error responses this object has next schema:



    ```json


    {
      "errorCode": "<Short code for given error>",       // string
      "message": "<Human readable error description>"    // string
    }


    ```



    > **Tip:** Language for error description depends on `Accept-Language`

    HTTP-header.



    There is the special error code for form validation errors - `badRequest`.

    If error object has that error code then response also will contain `errors`

    property with next schema:



    ```json


    {
      "errorCode": "badRequest",                         // string
      "message": "<Error description>",                  // string
      "errors": [                                        // array
        {
          "errorCode": "nullable",                       // string
          "message": "Property [points] cannot be null", // string
          "field": "points",                             // string, optional
          "value": null                                  // string, optional
        },
        ...
      ]
    }


    ```



    #### Common Error Codes



    <table>


    <thead>


    <tr>


    <th>Error Code</th>


    <th>Description</th>


    </tr>


    </thead>


    <tbody><tr>


    <td><code>forbidden</code></td>


    <td>Access denied, given authentication token is not set or has insufficient

    permissions</td>


    </tr>


    <tr>


    <td><code>notFound</code></td>


    <td>An entity not found. Where entity refers to a customer or

    promo-code.</td>


    </tr>


    <tr>


    <td><code>badRequest</code></td>


    <td>Form validation errors have occurred. For example, it can be

    type-mismatch or constraint violation errors.</td>


    </tr>


    </tbody>


    </table>



    #### Method specific error codes



    Each API-method call can produce errors which are specific for this method.

    For details about those errors read in method description provided in each

    API path.
servers:
  - url: 'https://api.uds.app/partner/v2'
    description: API server
security:
  - Basic: []
tags:
  - name: Settings
    description: >-
      Retrieve your company's loyalty program configuration including discount
      policies, membership tiers, reward rates, and referral settings. Call this
      endpoint on application startup and cache the settings locally.
    x-displayName: Settings
  - name: Operations
    description: >-
      Create, retrieve, and manage customer purchase transactions. Handles point
      redemption, discount application, cashback calculation, refunds, and bonus
      rewards. This is the core transactional API for POS and e-commerce
      integration.
    x-displayName: Operations
  - name: Customers
    description: >-
      Search, list, and retrieve customer profiles within your company's loyalty
      program. Access customer point balances, membership tiers, transaction
      statistics, and manage customer segmentation tags.
    x-displayName: Customers
  - name: Webhooks
    x-displayName: Webhooks
    description: >-
      Receive real-time HTTP notifications when events occur in UDS — new
      operations, customer registrations, and goods orders. Configure webhook
      URLs in UDS Admin. All requests are signed with X-Signature header for
      verification.
  - name: Goods
    description: >-
      Manage your product catalog in UDS. Partner API methods allow you to set
      up automatic product loading into UDS and update product information
      (prices, descriptions, stock quantities, photos, etc.) from your
      accounting system. Create, update, and delete categories, items, and
      varying items (items with variants). Supports inventory tracking,
      promotional pricing, images, and measurements.
    x-displayName: Goods
  - name: Goods Order
    description: >-
      Process online orders placed through the UDS marketplace. Accept, modify,
      complete, or cancel orders. **Beta** — parameters may change. Use at your
      own risk.
    x-displayName: Goods Orders
  - name: Image uploading
    description: >-
      Generate presigned URLs for uploading product images.


      ### Key steps


      1. Send a request to get a presigned upload URL.


      2. From the response, upload the image to the `url` using the HTTP method
      from `method` and headers from `headers`.


      3. After uploading images, create or update the product by passing the
      list of image identifiers (`imageId`) in the `photos` parameter.


      * When uploading an image, set `Content-Type: image/jpeg` in the headers,
      along with any other headers returned in the presigned URL response.


      * Steps 1–2 can be repeated multiple times to upload multiple product
      images (maximum 5 photos per product).


      * If you pass an empty list `photos: []` in the `data` object when
      updating a product, all product images will be deleted.
    x-displayName: Image uploading
  - name: Tags
    description: >-
      Retrieve company-defined tags for customer segmentation. Segmentation is
      used to divide the customer base and identify individual user groups by
      criteria of interest for further analysis and targeted actions. Tags are
      created in UDS Admin and can be assigned to customers via the Customers
      API.
    x-displayName: Company tags
  - name: FAQ
    description: >
      ## Frequently Asked Questions


      ### Where can I get a customer code (QR code) for processing payments?


      * Install the UDS mobile app ([App
      Store](https://apps.apple.com/app/game-united-discount-system/id954809132),
      [Google
      Play](https://play.google.com/store/apps/details?id=com.setinbox.game),
      [App Gallery](https://appgallery.huawei.com/#/app/C101533881)) and
      register. To generate a code, tap the card in the app.


      ### What is the lifetime of a customer code from the app?


      * The code is valid for 45 minutes. It is invalidated early if a payment
      is made using it.


      ### How can I get a code with an extended lifetime?


      * Add the `exchangeCode=true` parameter to the [customer →
      find](https://docs.uds.app/#tag/Customers/paths/~1customers~1find/get)
      request. The response will include a long-lived code in the `code` field
      that can be used to redeem points for 24 hours.


      ### How can I get test access to the API?


      * Contact us at [support@uds.app](mailto:support@uds.app) to request a
      test license.


      ### Where can I find the API Key and company ID?


      * Copy the company ID and API Key from UDS Business settings on the
      [Integration](https://admin.uds.app/admin/integration) page.


      ### Can I use the same API Key and company ID on multiple cash registers?


      * Each company has only one set of integration credentials in UDS, so the
      same API Key and company ID are used on all cash registers. Identification
      by register/branch/employee is done by passing parameters in the `cashier`
      field.


      ### Can I change the bonus points percentage for customer purchases via
      the API?


      * No. Bonus point accrual depends on the `cash` parameter and the bonus
      settings for customer tiers in the company. To limit points accrual, pass
      the `skipLoyaltyTotal` parameter — the portion of the receipt amount on
      which bonus points should not be accrued.


      ### Can bonus points be redeemed by phone number or customer UID?


      * Points can be redeemed by phone number only if the corresponding setting
      is enabled in the company. Points cannot be redeemed by customer UID.


      ### Can bonus points be rounded up when creating an operation?


      * No. Bonus points can only be rounded down.


      ### What is the external cashier identifier?


      * To identify the employee who processed the payment via UDS, you need to
      send the employee's individual number — their identifier. This identifier
      can be set in UDS Business for each employee in the corresponding field —
      external identifier.


      ### How do I configure a webhook?


      * Webhooks are configured in UDS Business settings on the
      [Integration](https://admin.uds.app/admin/integration) page. Specify the
      URL of your server where the webhook will be sent.


      ### Why do I receive multiple webhooks with the same information?


      * A webhook is retried up to three times at 5-minute intervals if it was
      not delivered or a 200 response was not received within 5 seconds.



      ## API Error Codes Reference


      | Status | Error Code | Description |

      |--------|------------|-------------|

      | `400` | badRequest | Validation errors occurred. See the `errors` field
      for details. Occurs when an invalid request is sent. |

      | `400` | invalidChecksum | The values in `cash`, `points`, or `total` do
      not match the discount method setting in the [loyalty
      program](https://admin.uds.app/admin/marketing/discount) settings. For
      bonus points accrual: `total = cash + points`. For discount: `total =
      (cash + points) / (1 - discount rate)`. Common causes: third-party
      discounts applied, incorrect rounding. For vouchers: discount method is
      not `CHARGE_SCORES`, accrual rate is `0.0`, or `total` ≤
      `skipLoyaltyTotal`. |

      | `400` | withdrawNotPermitted | The `participant → uid` was specified but
      `points` is not `0.0`. Can also occur if `uid` or `phone` is sent together
      with `code` when redeeming points — remove `uid` and `phone` and use only
      `code`. Also occurs when trying to redeem points by UID or phone if the
      company does not allow it. Set `points` to `0.0`. |

      | `400` | insufficientFunds | The `points` value exceeds the customer's
      available bonus point balance. Usually caused by incorrect rounding —
      points can only be rounded down. |

      | `400` | discountLimitExceed | The `points / total` ratio exceeds the
      maximum allowed in UDS settings. Check the maximum redemption percentage
      in [Loyalty Program](https://admin.uds.app/admin/marketing/discount)
      settings. |

      | `400` | purchaseByPhoneDisabled | Purchase by phone number is not
      allowed by UDS settings. Enable the [purchase by
      phone](https://admin.uds.app/admin/marketing/discount) setting in UDS
      Business. |

      | `400` | participantIsBlocked | The customer is blocked in this company.
      |

      | `400` | goods.nodeIndex.invalid | Specifying a `nodeId` is not allowed
      when creating a category. Verify the correct category ID. |

      | `400` | goods.limitIsReached | The product limit has been exceeded.
      Check the limit in the [Goods &
      Services](https://admin.uds.app/admin/price-list) section of UDS Business.
      |

      | `401` | unauthorized | Invalid company ID or API Key. Verify your
      credentials on the [Integration](https://admin.uds.app/admin/integration)
      page and check your Basic authentication. |

      | `404` | notFound | Customer with the given payment code or identifier
      was not found. Usually occurs with an incorrectly entered code or an
      expired code. Also occurs when searching by phone number if the number is
      not registered and has no prior operations in the company. |



      ## Changelog


      ### 2025-09-22


      * Added `offerPrice` and `skipLoyalty` fields to the
      [order](https://docs.uds.app/#tag/Goods-Order) model and the [new order
      webhook](https://docs.uds.app/#tag/Webhooks/paths/~1api~1v2~1events~1goods-order/post).


      ### 2025-07-21


      * Added `usePointsByPhone` field to the [company
      settings](https://docs.uds.app/#tag/Settings) model.


      ### 2025-02-03


      * Added new methods for
      [getting](https://docs.uds.app/#tag/Goods/paths/~1goods~1external~1{externalId}/get),
      [updating](https://docs.uds.app/#tag/Goods/paths/~1goods~1external~1{externalId}/put),
      and
      [deleting](https://docs.uds.app/#tag/Goods/paths/~1goods~1external~1{externalId}/delete)
      goods by external identifier.


      ### 2024-08-26


      * Added `cashSpent`, `savedFunds`, `invitedCount`,
      `effectiveInvitedCount`, `operationsCount`, `fullRefundsCount`, `note`,
      `pointsExpireIn` fields to the
      [customer](https://docs.uds.app/#tag/Customers) model.


      ### 2024-06-24


      * Added `certificatePoints` field to the
      [operation](https://docs.uds.app/#tag/Operations) model.


      ### 2024-03-11


      * Added `nodeId` field to the [goods](https://docs.uds.app/#tag/Goods)
      model.


      ### 2024-02-19


      * Added new method for [canceling
      orders](https://docs.uds.app/#tag/Goods-Order/paths/~1goods-orders~1{id}~1cancel/post).

      * Added new method for [changing order
      status](https://docs.uds.app/#tag/Goods-Order/paths/~1goods-orders~1{id}~1change-status/post).

      * Added `orderStatus` field to the
      [order](https://docs.uds.app/#tag/Goods-Order) model.


      ### 2023-10-09


      * Added `vatCode` and `paymentSubject` fields to the
      [goods](https://docs.uds.app/#tag/Goods) model for VAT codes (`NO_NDS`,
      `NDS_0`, `NDS_10`, `NDS_20`, `NDS_10_110`, `NDS_20_120`) and payment
      subject types (`COMMODITY`, `EXCISE`, `SERVICE`).


      ### 2023-04-24


      * Added `unredeemableTotal` — the receipt amount for which point
      redemption is not allowed — to [find
      customer](https://docs.uds.app/#tag/Customers/paths/~1customers~1find/get),
      [calculate
      discount](https://docs.uds.app/#tag/Operations/paths/~1operations~1calc/post),
      and [create
      operation](https://docs.uds.app/#tag/Operations/paths/~1operations/post).

      * Added `maxScoresDiscount` and `certificatePoints` to the
      [PurchaseCalc](https://docs.uds.app/#tag/Operations/paths/~1operations~1calc/post)
      model.


      ### 2022-07-18


      * Added `maxScoresDiscount` to the
      [customer](https://docs.uds.app/#tag/Customers) model.


      ### 2022-04-25


      * Added new methods for [listing company
      tags](https://docs.uds.app/#tag/Tags/paths/~1tags/get), [getting customer
      tags](https://docs.uds.app/#tag/Customers/paths/~1customers~1{id}~1tags/get),
      and [setting customer
      tags](https://docs.uds.app/#tag/Customers/paths/~1customers~1{id}~1tags/post).

      * Added `tags` field to the
      [customer](https://docs.uds.app/#tag/Customers) model and [create
      operation](https://docs.uds.app/#tag/Operations/paths/~1operations/post).


      ### 2022-04-11


      * Added `measurement`, `minQuantity`, and `increment` fields to the
      [goods](https://docs.uds.app/#tag/Goods) model for different measurement
      units and minimum order quantities.


      ### 2022-03-28


      * Added `email` field to the
      [customer](https://docs.uds.app/#tag/Customers) model.


      ### 2021-11-29


      * Added `channelName` field to the
      [customer](https://docs.uds.app/#tag/Customers) model for tracking the
      acquisition channel.


      ### 2021-09-21


      * Added `photos` and `imageUrls` fields to the
      [goods](https://docs.uds.app/#tag/Goods) model for product images.

      * Added `image-upload-url` method for generating image upload URLs.


      ### 2021-08-23


      * Added `inventory` with `inStock` field to the
      [goods](https://docs.uds.app/#tag/Goods) model for stock tracking.

      * Added `cursor` parameter to replace `offset` for paginating the
      [operations
      list](https://docs.uds.app/#tag/Operations/paths/~1operations/get).


      ### 2021-07-12


      * Added [voucher
      creation](https://docs.uds.app/#tag/Operations/paths/~1operations~1voucher/post)
      method for accruing bonus points via printed QR code.

      * For performance optimization, [operations
      list](https://docs.uds.app/#tag/Operations/paths/~1operations/get) `total`
      now always returns `0`.


      ### 2021-02-08


      * Added `silent` field to [send bonus
      points](https://docs.uds.app/#tag/Operations/paths/~1operations~1reward/post).
      When `silent = true`, no push notification is sent to the customer.
    x-displayName: FAQ
paths:
  /settings:
    get:
      summary: Get company loyalty settings
      tags:
        - Settings
      description: >
        Retrieves your company's current loyalty program configuration,
        including discount policy,

        membership tier structure, referral reward rates, and operational
        limits.


        **When to use:** Call this endpoint when initializing your application
        or periodically

        (e.g., daily) to cache current settings. Settings rarely change but
        affect all transaction calculations.


        Marketing settings can be configured in [UDS
        Admin](https://admin.uds.app/admin/marketing/discount).
      x-codeSamples:
        - lang: curl
          source: |
            curl -H 'Accept: application/json' \
                 -H "X-Origin-Request-Id: $(uuidgen)" \
                 -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
                 -u "<companyId>:<api_key>"
                 -X GET -s https://api.uds.app/partner/v2/settings
        - lang: PHP
          source: >
            $date = new DateTime();

            $url = "https://api.uds.app/partner/v2/settings";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'GET',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM)
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='GET',
                url='/partner/v2/settings',
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8"),
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/settings',
              'method': 'GET',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {

                console.log(
                  JSON.parse(response)
                );

              });
            });

            req.end();
      parameters:
        - $ref: '#/components/parameters/x-request-id'
        - $ref: '#/components/parameters/x-timestamp'
      responses:
        '200':
          description: Settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanySettings'
              example:
                id: 123456
                name: Coffee House
                promoCode: COFFEE2024
                currency: USD
                baseDiscountPolicy: APPLY_DISCOUNT
                loyaltyProgramSettings:
                  baseMembershipTier:
                    uid: base-tier
                    name: Standard
                    rate: 5
                    maxScoresDiscount: 20
                  membershipTiers:
                    - uid: silver-tier
                      name: Silver
                      rate: 7
                      maxScoresDiscount: 30
                      conditions:
                        totalCashSpent:
                          target: 500
                    - uid: gold-tier
                      name: Gold
                      rate: 10
                      maxScoresDiscount: 50
                      conditions:
                        totalCashSpent:
                          target: 2000
                  referralCashbackRates:
                    - 2
                    - 1
                    - 0.5
                  cashierAward: 0.5
                  referralReward: 100
                  receiptLimit: 10000
                  deferPointsForDays: 7
                  firstPurchasePoints: 50
                purchaseByPhone: true
                usePointsByPhone: true
                writeInvoice: false
                slug: coffee-house
  /customers:
    get:
      summary: List customers
      tags:
        - Customers
      description: >
        Retrieves a paginated list of customers enrolled in your company's
        loyalty program.

        Use `max` and `offset` parameters to paginate through results.
      x-codeSamples:
        - lang: curl
          source: |
            curl -H 'Accept: application/json' \
                 -H "X-Origin-Request-Id: $(uuidgen)" \
                 -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
                 -u "<companyId>:<api_key>"
                 -X GET -s https://api.uds.app/partner/v2/customers?max=10&offset=0
        - lang: PHP
          source: >
            $date = new DateTime();

            $url = "https://api.uds.app/partner/v2/customers?max=10&offset=0";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'GET',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM)
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='GET',
                url='/partner/v2/customers?max=10&offset=0',
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/customers?max=10&offset=0',
              'method': 'GET',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {

                console.log(
                  JSON.parse(response)
                );

              });
            });

            req.end();
      parameters:
        - $ref: '#/components/parameters/max'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: Paginated list of company customers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  rows:
                    type: array
                    description: Customers information.
                    items:
                      $ref: '#/components/schemas/Customer'
                example:
                  rows:
                    - uid: 23684cea-ca50-4c5c-b399-eb473e85b5ad
                      avatar: 'https://cdn.uds.app/avatars/user123.jpg'
                      displayName: John Doe
                      gender: MALE
                      phone: '+12125551234'
                      birthDate: '1990-05-15'
                      email: john.doe@example.com
                      channelName: Website
                      participant:
                        id: 789
                        inviterId: 456
                        points: 350.5
                        discountRate: 7
                        cashbackRate: 7
                        cashSpent: 1250
                        savedFunds: 125
                        invitedCount: 3
                        effectiveInvitedCount: 2
                        operationsCount: 15
                        fullRefundsCount: 0
                        note: Regular customer
                        membershipTier:
                          uid: silver-tier
                          name: Silver
                          rate: 7
                        dateCreated: '2023-01-15T10:30:00.000Z'
                        lastTransactionTime: '2024-11-20T14:22:00.000Z'
                  total: 1
  /customers/find:
    get:
      summary: 'Find customer by code, phone, or UID'
      tags:
        - Customers
      description: >
        Find a customer by promo code (`code`), phone number (`phone`), or UDS
        identifier (`uid`).

        This is the primary endpoint for identifying customers during checkout.


        **Promo code** — generated by the customer in the UDS mobile app (QR
        code). Short-lived and single-use.

        Allows point redemption during the transaction.


        **Phone number** — for automated systems. Points cannot be redeemed when
        identifying by phone

        (unless `purchaseByPhone` is enabled in settings).


        **UID** — permanent UDS customer identifier for returning customers.


        The response includes the customer's loyalty calculation (`purchase`
        field) which shows

        available discounts and max redeemable points for the current
        transaction.
      x-codeSamples:
        - lang: curl
          source: |
            curl -H 'Accept: application/json' \
                 -H "X-Origin-Request-Id: $(uuidgen)" \
                 -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
                 -u "<companyId>:<api_key>"
                 -X GET -s https://api.uds.app/partner/v2/customers/find?code=456123&phone=%2b71234567898&uid=23684cea-ca50-4c5c-b399-eb473e85b5ad
        - lang: PHP
          source: >
            $date = new DateTime();

            $url =
            "https://api.uds.app/partner/v2/customers/find?code=456123&phone=%2b71234567898&uid=23684cea-ca50-4c5c-b399-eb473e85b5ad";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'GET',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM)
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='GET',
                url='/partner/v2/customers/find?code=456123&phone=%2b71234567898&uid=23684cea-ca50-4c5c-b399-eb473e85b5ad',
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/customers/find?code=456123&phone=%2b71234567898&uid=23684cea-ca50-4c5c-b399-eb473e85b5ad',
              'method': 'GET',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {

                console.log(
                  JSON.parse(response)
                );

              });
            });

            req.end();
      parameters:
        - name: code
          in: query
          schema:
            type: string
          description: Promo code
        - name: phone
          in: query
          schema:
            type: string
          description: >-
            Phone number in E164 format, URL-encoded. For example, +79123456789
            should be passed as %2b79123456789.
        - name: uid
          in: query
          schema:
            type: string
          description: Customer's uid
        - name: exchangeCode
          in: query
          schema:
            type: boolean
          description: >
            If specified, the response will include a new long-lived payment
            code in the `code` field. The old promo code will be deactivated.
        - name: total
          in: query
          description: Total receipt amount (in currency units).
          schema:
            type: number
        - name: skipLoyaltyTotal
          in: query
          description: >-
            A part of the bill amount for which cashback is not credited and to
            which the discount does not apply (in currency units).
          schema:
            type: number
        - name: unredeemableTotal
          in: query
          description: A part of total that cannot be redeemed with points
          schema:
            type: number
      responses:
        '200':
          description: Customer found by the given search criteria.
          content:
            application/json:
              schema:
                properties:
                  user:
                    $ref: '#/components/schemas/CustomerDetail'
                  code:
                    type: string
                    description: New long life purchase promo code if exchangeCode queried
                    nullable: true
                  type:
                    $ref: '#/components/schemas/PurchaseTokenAction'
                  purchase:
                    type: object
                    nullable: true
                    allOf:
                      - $ref: '#/components/schemas/PurchaseCalc'
              example:
                user:
                  uid: 23684cea-ca50-4c5c-b399-eb473e85b5ad
                  displayName: John Doe
                  gender: MALE
                  phone: '+12125551234'
                  birthDate: '1990-05-15'
                  participant:
                    id: 789
                    points: 350.5
                    discountRate: 7
                    cashbackRate: 7
                    cashSpent: 1250
                    savedFunds: 125
                    invitedCount: 3
                    effectiveInvitedCount: 2
                    operationsCount: 15
                    fullRefundsCount: 0
                    membershipTier:
                      uid: silver-tier
                      name: Silver
                      rate: 7
                    dateCreated: '2023-01-15T10:30:00.000Z'
                    lastTransactionTime: '2024-11-20T14:22:00.000Z'
                  tags:
                    - id: 1
                      name: VIP
                    - id: 3
                      name: Regular
                code: null
                type: PURCHASE
                purchase:
                  maxPoints: 200
                  total: 1000
                  skipLoyaltyTotal: 0
                  unredeemableTotal: 0
                  discountAmount: 70
                  discountPercent: 7
                  points: 0
                  pointsPercent: 0
                  netDiscount: 70
                  netDiscountPercent: 7
                  certificatePoints: 0
                  cash: 930
                  cashTotal: 930
                  cashBack: 65.1
                  maxScoresDiscount: 30
        '404':
          $ref: '#/components/responses/NotFound'
  '/customers/{id}':
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      summary: Get customer details
      tags:
        - Customers
      description: >
        Retrieves detailed customer information by participant ID within your
        company, including

        profile data, loyalty statistics, membership tier, and assigned tags.
      x-codeSamples:
        - lang: curl
          source: |
            curl -H 'Accept: application/json' \
                 -H "X-Origin-Request-Id: $(uuidgen)" \
                 -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
                 -u "<companyId>:<api_key>"
                 -X GET -s https://api.uds.app/partner/v2/customers/<id>
        - lang: PHP
          source: >
            $date = new DateTime();

            $customerId = 123;

            $url = "https://api.uds.app/partner/v2/customers/".$customerId;

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'GET',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM)
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            customerId = 123
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='GET',
                url='/partner/v2/customers/' + customerId,
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';
            const customerId = 123;

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/customers/' + customerId,
              'method': 'GET',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {

                console.log(
                  JSON.parse(response)
                );

              });
            });

            req.end();
      responses:
        '200':
          description: Customer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerDetail'
              example:
                uid: 23684cea-ca50-4c5c-b399-eb473e85b5ad
                avatar: 'https://cdn.uds.app/avatars/user123.jpg'
                displayName: John Doe
                gender: MALE
                phone: '+12125551234'
                birthDate: '1990-05-15'
                email: john.doe@example.com
                channelName: Website
                participant:
                  id: 789
                  inviterId: 456
                  points: 350.5
                  discountRate: 7
                  cashbackRate: 7
                  cashSpent: 1250
                  savedFunds: 125
                  invitedCount: 3
                  effectiveInvitedCount: 2
                  operationsCount: 15
                  fullRefundsCount: 0
                  note: Regular customer
                  membershipTier:
                    uid: silver-tier
                    name: Silver
                    rate: 7
                    maxScoresDiscount: 30
                  dateCreated: '2023-01-15T10:30:00.000Z'
                  lastTransactionTime: '2024-11-20T14:22:00.000Z'
                tags:
                  - id: 1
                    name: VIP
                  - id: 3
                    name: Regular
        '404':
          $ref: '#/components/responses/NotFound'
  '/customers/{id}/tags':
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      summary: Get customer tags
      tags:
        - Customers
      description: >-
        Fetches the list of tags assigned to a customer by participant ID in the
        company.
      x-codeSamples:
        - lang: curl
          source: |
            curl -H 'Accept: application/json' \
                 -H "X-Origin-Request-Id: $(uuidgen)" \
                 -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
                 -u "<companyId>:<api_key>"
                 -X GET -s https://api.uds.app/partner/v2/customers/<id>/tags
        - lang: PHP
          source: >
            $date = new DateTime();

            $customerId = 123;

            $url =
            "https://api.uds.app/partner/v2/customers/".$customerId."/tags";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'GET',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM)
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            customerId = 123
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='GET',
                url='/partner/v2/customers/' + customerId + '/tags',
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';
            const customerId = 123;

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/customers/' + customerId + '/tags',
              'method': 'GET',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {

                console.log(
                  JSON.parse(response)
                );

              });
            });

            req.end();
      responses:
        '200':
          description: Customer's tags model list
          content:
            application/json:
              schema:
                type: object
                properties:
                  rows:
                    type: array
                    items:
                      $ref: '#/components/schemas/TagModel'
                    description: Tags list.
                  total:
                    type: integer
                    description: Total count of customer tags
              example:
                rows:
                  - id: 1
                    name: VIP
                  - id: 3
                    name: Regular
                  - id: 7
                    name: Newsletter subscriber
                total: 3
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      summary: Add tags to customer
      tags:
        - Customers
      description: |
        Set tags to a customer by passing company tag identifiers.
      x-codeSamples:
        - lang: curl
          source: >
            curl -H "accept: application/json" \

            -H "Content-Type: application/json" \

            -H "X-Origin-Request-Id: $(uuidgen)" \

            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \

            -u "<companyId>:<api_key>"

            -d '{"ids": [1, 2, 3]}' -X POST
            "https://api.uds.app/partner/v2/customers/<id>/tags"
        - lang: PHP
          source: >
            $date = new DateTime();

            $url = "https://api.uds.app/partner/v2/customers/<id>/tags";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Set request body


            $postData = json_encode(
              array("ids", array(1, 2, 3))  // ids of tags
            );


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'POST',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $postData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='POST',
                url='/partner/v2/customers/<id>/tags',
                body=json.dumps({'ids': [1, 2, 3]}),
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Content-Type': 'application/json',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/customers/<id>/tags',
              'method': 'POST',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Content-Type': 'application/json',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const data = JSON.stringify({'ids': [1, 2, 3]});

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {

                console.log(
                  JSON.parse(response)
                );

              });
            });

            req.write(data);
            req.end();
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  description: >-
                    List of company tag identifiers (ids) to assign to the
                    customer.
                  type: array
                  items:
                    $ref: '#/components/schemas/TagId'
              required:
                - ids
      responses:
        '200':
          description: Updated customer tags
          content:
            application/json:
              schema:
                type: object
                properties:
                  rows:
                    description: Customer tags
                    type: array
                    items:
                      $ref: '#/components/schemas/TagModel'
                  total:
                    type: integer
                    description: Total count of customer tags
              example:
                rows:
                  - id: 1
                    name: VIP
                  - id: 2
                    name: Promo 2024
                  - id: 3
                    name: Regular
                total: 3
        '404':
          $ref: '#/components/responses/NotFound'
  /operations:
    get:
      summary: List operations
      tags:
        - Operations
      description: >
        Retrieves a paginated list of all company transactions (purchases,
        refunds, rewards).

        Use `cursor` for efficient pagination through large result sets.

        The `offset` parameter is deprecated — use `cursor` instead.
      x-codeSamples:
        - lang: curl
          source: |
            curl -H 'Accept: application/json' \
            -H "X-Origin-Request-Id: $(uuidgen)" \
            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
            -u "<companyId>:<api_key>"
            -X GET -s https://api.uds.app/partner/v2/operations?max=10
        - lang: PHP
          source: >
            $date = new DateTime();

            $url = "https://api.uds.app/partner/v2/operations?max=10";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'GET',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM)
                )
            );



            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='GET',
                url='/partner/v2/operations?max=10',
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/operations?max=10',
              'method': 'GET',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {

                console.log(
                  JSON.parse(response)
                );

              });
            });

            req.end();
      parameters:
        - $ref: '#/components/parameters/max'
        - name: offset
          in: query
          description: Paginate results by given offset. Deprecated. Use cursor instead
          deprecated: true
          schema:
            type: integer
            default: 0
            maximum: 10000
        - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: Operation list
          content:
            application/json:
              schema:
                type: object
                properties:
                  rows:
                    $ref: '#/components/schemas/Operation'
                  total:
                    deprecated: true
                    type: integer
                  cursor:
                    description: Use this cursor for next request
                    type: string
              example:
                rows:
                  - id: 10245
                    dateCreated: '2024-11-20T14:22:00.000Z'
                    action: PURCHASE
                    state: NORMAL
                    customer:
                      id: 789
                      uid: 23684cea-ca50-4c5c-b399-eb473e85b5ad
                      displayName: John Doe
                      membershipTier:
                        uid: silver-tier
                        name: Silver
                        rate: 7
                    cashier:
                      id: 5
                      displayName: Jane Smith
                    branch:
                      id: 1
                      displayName: Main Office
                    points: -50
                    certificatePoints: 0
                    cash: 950
                    total: 1000
                    receiptNumber: R-2024-1120
                    origin: null
                cursor: eyJsYXN0SWQiOjEwMjQ1fQ==
                total: 156
    post:
      summary: Create operation
      tags:
        - Operations
      description: >
        Perform operation in UDS. On success operation appears in operations
        list in UDS Admin and customer receives

        push notification about purchase.


        ### Marketing policy


        Depends on company discount policy (`baseDiscountPolicy` field) in
        company settings. Two values are supported:


        * `APPLY_DISCOUNT` — reduce the bill amount: the customer receives a
        discount in currency units at the rate specified in
        `participant.discountRate`;

        * `CHARGE_SCORES` — accrue bonus points: the customer receives bonus
        points at the rate specified in `participant.cashbackRate`.


        ### Key points

        * Fields `total` and `points` should come from user input but `cash`
        field should be calculated using POST `/operations/calc`;

        * Customer will be identified with either promo code passed in parameter
        `code` or with participant uid in parameter `participant -> uid`
          or by participant's phone in parameter `participant -> phone`;
          Difference between them is that with `participant -> uid` or `participant -> phone` is not permitted to withdraw points;
          If given parameter is `participant -> uid` or `participant -> phone` then `points` must be equal to `0.0`;
          Otherwise an error will occurs with code `withdrawNotPermitted`;
        * Only one identifier parameter must be passed: either `code`, or
        `phone`, or `uid`;

        * All numbers should be scaled to two decimal places with "round half
        up" method. The `points` value can only be rounded **down**;

        * `cash`, `points` and `total` fields MUST correlate with the "Discount
        method" setting in UDS;

        * The `nonce` field is a UUID-like string that can only be used once. It
        is recommended to prevent duplicate operations in case of request
        retries;

        * The `externalId` field is the cashier identifier. It may only contain
        Latin letters, digits, and the characters `_`, `-`;

        * If the register sends cashier information, enable the
        [Staff](https://store.uds.app/modules/staff) module in UDS to view
        detailed cashier data;

        * If UDS returns an error, do not finalize the payment in your system
        until the issue is corrected and a new request is sent successfully.


        ### Errors

        Status | Error Code | Description

        ------ | ---------- | -----------

        `400` | `badRequest` | Form validation errors occurred. See JSON
        `errors` property for detailed information about errors.

        `400` | `invalidChecksum` | Given `total`, `cash` and `points` fields
        don't correlate with company marketing settings.

        `400 `| `withdrawNotPermitted` | Method was called with `participant ->
        uid` or `participant -> phone` parameter and `points` field doesn't
        equal to `0.0`.

        `400` | `insufficientFunds` | Given `points` value greater than actual
        customer reward point balance.

        `400` | `priceListOnly` | Company marketing settings forbid purchases
        with using reward points, except of price list operations.

        `400` | `discountLimitExceed` | Given `points/total` rate more than
        allowed by marketing settings.

        `400` | `purchaseByPhoneDisabled` | Trying to make purchase by phone
        when it is disabled in company settings.

        `401` | `unauthorized` | Invalid company ID or API Key.

        `404` | `notFound` | Customer related to given code or ID is not found.

        `404` | `cashierNotFound` | `externalCashierId` is specified but cashier
        related to it is not found.
      x-codeSamples:
        - lang: curl
          source: |
            curl -H "accept: application/json" \
            -H "Content-Type: application/json" \
            -H "X-Origin-Request-Id: $(uuidgen)" \
            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
            -u "<companyId>:<api_key>"
            -d '{ \
              "code":"456123", \
              "participant":{ \
                "uid":"23684cea-ca50-4c5c-b399-eb473e85b5ad", \
                "phone":"+12125551234" \
              }, \
              "nonce":"a1b2c3d4-e5f6-7890-abcd-ef1234567890", \
              "cashier":{ \
                "externalId":"cashier-01", \
                "name":"John Smith" \
              }, \
              "receipt":{ \
                "total":100.0, \
                "cash":50.0, \
                "points":50.0, \
                "number":"REC-2024-001", \
                "skipLoyaltyTotal": 50.0, \
                "unredeemableTotal": 20.0 \
              }, \
              "tags": [1, 2], \
              "items": [ \
                { \
                  "itemId": "item-001", \
                  "itemCode": "code-001", \
                  "type": "product", \
                  "name": "Test Product", \
                  "measure": "pcs", \
                  "vatCode": "vat20", \
                  "price": 100.0, \
                  "discountPrice": 90.0, \
                  "qty": 1.0, \
                  "sku": "SKU-001", \
                  "isAlcohol": false, \
                  "isTobacco": false, \
                  "excise": null, \
                  "classificationCode": "CL-001", \
                  "modifiers": [{"key": "size", "value": "large"}], \
                  "attributes": {"category": "food"} \
                } \
              ] \
            }' -X POST "https://api.uds.app/partner/v2/operations"
        - lang: PHP
          source: >
            $date = new DateTime();

            $url = "https://api.uds.app/partner/v2/operations";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Set request body


            $postData = json_encode(
              array(
                'code' => 'string',
                'participant' => array(
                  'uid' => 'string',
                  'phone' => 'string'
                ),
                'nonce' => 'string',
                'cashier' => array(
                  'externalId' => 'string',
                  'name' => 'string'
                ),
                'receipt' => array(
                  'total' => 100.0,
                  'cash' => 50.0,
                  'points' => 50.0,
                  'number' => 'string',
                  'skipLoyaltyTotal' => 50.0,
                  'unredeemableTotal' => 20.0
                ),
                'tags' => array(1, 2),
                'items' => array(
                  array(
                    'itemId' => 'item-001',
                    'itemCode' => 'code-001',
                    'type' => 'product',
                    'name' => 'Test Product',
                    'measure' => 'pcs',
                    'vatCode' => 'vat20',
                    'price' => 100.0,
                    'discountPrice' => 90.0,
                    'qty' => 1.0,
                    'sku' => 'SKU-001',
                    'isAlcohol' => false,
                    'isTobacco' => false,
                    'classificationCode' => 'CL-001',
                    'modifiers' => array(array('key' => 'size', 'value' => 'large')),
                    'attributes' => array('category' => 'food')
                  )
                )
              )
            );


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'POST',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $postData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='POST',
                url='/partner/v2/operations',
                body=json.dumps({
                  'code': 'string',
                  'participant': {
                    'uid': 'string',
                    'phone': 'string'
                  },
                  'nonce': 'string',
                  'cashier': {
                    'externalId': 'string',
                    'name': 'string'
                  },
                  'receipt': {
                    'total': 100.0,
                    'cash': 50.0,
                    'points': 50.0,
                    'number': 'string',
                    'skipLoyaltyTotal': 50.0,
                    'unredeemableTotal': 20.0
                  },
                  'tags': [1, 2],
                  'items': [
                    {
                      'itemId': 'item-001',
                      'itemCode': 'code-001',
                      'type': 'product',
                      'name': 'Test Product',
                      'measure': 'pcs',
                      'vatCode': 'vat20',
                      'price': 100.0,
                      'discountPrice': 90.0,
                      'qty': 1.0,
                      'sku': 'SKU-001',
                      'isAlcohol': False,
                      'isTobacco': False,
                      'classificationCode': 'CL-001',
                      'modifiers': [{'key': 'size', 'value': 'large'}],
                      'attributes': {'category': 'food'}
                    }
                  ]
                }),
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Content-Type': 'application/json',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/operations',
              'method': 'POST',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Content-Type': 'application/json',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const data = JSON.stringify({
              'code': 'string',
              'participant': {
                'uid': 'string',
                'phone': 'string'
              },
              'nonce': 'string',
              'cashier': {
                'externalId': 'string',
                'name': 'string'
              },
              'receipt': {
                'total': 100.0,
                'cash': 50.0,
                'points': 50.0,
                'number': 'string',
                'skipLoyaltyTotal': 50.0,
                'unredeemableTotal': 20.0
              },
              'tags': [1, 2],
              'items': [
                {
                  'itemId': 'item-001',
                  'itemCode': 'code-001',
                  'type': 'product',
                  'name': 'Test Product',
                  'measure': 'pcs',
                  'vatCode': 'vat20',
                  'price': 100.0,
                  'discountPrice': 90.0,
                  'qty': 1.0,
                  'sku': 'SKU-001',
                  'isAlcohol': false,
                  'isTobacco': false,
                  'classificationCode': 'CL-001',
                  'modifiers': [{'key': 'size', 'value': 'large'}],
                  'attributes': {'category': 'food'}
                }
              ]
            });

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {

                console.log(
                  JSON.parse(response)
                );

              });
            });

            req.write(data);
            req.end();
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOperation'
      responses:
        '200':
          description: Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
              example:
                id: 1
                dateCreated: '2018-09-21T07:48:22.771Z'
                action: PURCHASE
                state: NORMAL
                customer:
                  id: 0
                  uid: abcdefgh-0000-1111-2222-ijklmnopqrst
                  displayName: Customer
                  membershipTier:
                    uid: vip
                    name: VIP
                    rate: 15
                    conditions:
                      totalCashSpent:
                        target: 100
                cashier:
                  id: 0
                  displayName: Cashier
                branch:
                  id: 0
                  displayName: Branch
                points: 0
                certificatePoints: 0
                cash: 100
                total: 100
                origin:
                  id: 0
  '/operations/{id}':
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      summary: Get operation
      tags:
        - Operations
      description: Find operation by its ID.
      x-codeSamples:
        - lang: curl
          source: |
            curl -H 'Accept: application/json' \
                 -H "X-Origin-Request-Id: $(uuidgen)" \
                 -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
                 -u "<companyId>:<api_key>"
                 -X GET -s https://api.uds.app/partner/v2/operations/<id>
        - lang: PHP
          source: >
            $date = new DateTime();

            $customerId = 123;

            $url = "https://api.uds.app/partner/v2/operations/".$customerId;

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'GET',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM)
                )
            );



            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            customerId = 123
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='GET',
                url='/partner/v2/operations/' + customerId,
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';
            const customerId = 123;

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/operations/' + customerId,
              'method': 'GET',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {

                console.log(
                  JSON.parse(response)
                );

              });
            });

            req.end();
      responses:
        '200':
          description: Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
              example:
                oneOf:
                  - id: 1 (Purchase operation)
                    dateCreated: '2018-09-21T07:48:22.771Z'
                    action: PURCHASE
                    state: NORMAL
                    customer:
                      id: 0
                      uid: abcdefgh-0000-1111-2222-ijklmnopqrst
                      displayName: Customer
                      membershipTier:
                        uid: vip
                        name: VIP
                        rate: 15
                        conditions:
                          totalCashSpent:
                            target: 100
                    cashier:
                      id: 0
                      displayName: Cashier
                    branch:
                      id: 0
                      displayName: Branch
                    points: 0
                    cash: 100
                    total: 100
                    origin:
                      id: 0
  /operations/voucher:
    post:
      summary: Create voucher
      tags:
        - Operations
      description: >
        Creation of a voucher for an operation in UDS. If successful, you will
        receive information for printing the code and a link to the graphic
        display of the QR code of the voucher on the check.

        ### Marketing policy

        A prerequisite for using this functionality is to configure the loyalty
        program module in the settings of the UDS Business administrative panel
        (https://admin.uds.app/). You need to specify "Accrue bonus points" in
        the settings block "Discount method"


        ### Errors

        Status | Error Code | Description

        ------ | ---------- | -----------

        `400` | `invalidChecksum` |  Discount method is not `CHARGE_SCORES`

        `400` | `invalidChecksum` |  Company charge scores rate is 0.

        `400` | `invalidChecksum` |  Given `total` less then or is equal to
        `skipLoyaltyTotal`
      x-codeSamples:
        - lang: curl
          source: |
            curl -H "accept: application/json" \
            -H "Content-Type: application/json" \
            -H "X-Origin-Request-Id: $(uuidgen)" \
            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
            -u "<companyId>:<api_key>"
            -d '{ \
              "nonce":"a1b2c3d4-e5f6-7890-abcd-ef1234567890", \
              "cashier":{ \
                "externalId":"cashier-01", \
                "name":"John Smith" \
              }, \
              "receipt":{ \
                "total":100.0, \
                "number":"REC-2024-001", \
                "skipLoyaltyTotal": 50.0 \
              } \
            }' -X POST "https://api.uds.app/partner/v2/operations/voucher"
        - lang: PHP
          source: >
            $date = new DateTime();

            $url = "https://api.uds.app/partner/v2/operations/voucher";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Set request body


            $postData = json_encode(
              array(
                'nonce' => 'string-UUID',
                'cashier' => array(
                  'externalId' => 'string',
                  'name' => 'string'
                ),
                'receipt' => array(
                  'total' => 100.0,
                  'number' => 'string',
                  'skipLoyaltyTotal' => 50.0
                )
              )
            );


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'POST',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $postData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='POST',
                url='/partner/v2/operations/voucher',
                body=json.dumps({
                  'nonce': 'string-UUID',
                  'cashier': {
                    'externalId': 'string',
                    'name': 'string'
                  },
                  'receipt': {
                    'total': 100.0,
                    'number': 'string',
                    'skipLoyaltyTotal': 50.0
                  }
                }),
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Content-Type': 'application/json',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/operations/voucher',
              'method': 'POST',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Content-Type': 'application/json',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const data = JSON.stringify({
              'nonce': 'string-UUID',
              'cashier': {
                'externalId': 'string',
                'name': 'string'
              },
              'receipt': {
                'total': 100.0,
                'number': 'string',
                'skipLoyaltyTotal': 50.0
              }
            });

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {

                console.log(
                  JSON.parse(response)
                );

              });
            });

            req.write(data);
            req.end();
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVoucher'
      responses:
        '200':
          description: Voucher
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoucherInfo'
              example:
                code: V-123456
                qrCodeText: 'uds://voucher/V-123456'
                qrCode128: 'https://cdn.uds.app/qr/V-123456/128'
                qrCode256: 'https://cdn.uds.app/qr/V-123456/256'
                expiresIn: '2024-12-01T23:59:59.000Z'
                points: 65.1
  '/operations/{id}/refund':
    parameters:
      - $ref: '#/components/parameters/id'
    post:
      summary: Refund operation
      tags:
        - Operations
      description: |
        Refund operation by its ID. If the parameter attribute `partialAmount`
        is set, refund will be partial, otherwise invocation of this method will
        cause full refund.
      x-codeSamples:
        - lang: curl
          source: |
            curl -H "accept: application/json" \
            -H "Content-Type: application/json" \
            -H "X-Origin-Request-Id: $(uuidgen)" \
            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
            -u "<companyId>:<api_key>"
            -d '{ \
              "partialAmount":100.0 \
            }' -X POST "https://api.uds.app/partner/v2/operations/<id>/refund"
        - lang: PHP
          source: >
            $date = new DateTime();

            $operationId = 123;

            $url =
            "https://api.uds.app/partner/v2/operations/".$operationId."/refund";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company


            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Set request body


            $postData = json_encode(
              array(
                'partialAmount' => 100.0
              )
            );


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'POST',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $postData,
                    'ignore_errors' => true
                )
            );



            $context = stream_context_create($opts);



            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            operationId = 123
            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='POST',
                url='/partner/v2/operations/' + operationId + '/refund',
                body=json.dumps({
                  'partialAmount': 100.0
                }),
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Content-Type': 'application/json',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';
            const operationId = 123;

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/operations/' + operationId + '/refund',
              'method': 'POST',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Content-Type': 'application/json',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const data = JSON.stringify({
              'partialAmount': 100.0
            });

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {

                console.log(
                  JSON.parse(response)
                );

              });
            });

            req.write(data);
            req.end();
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                partialAmount:
                  type: number
                  nullable: true
                  description: Refund amount.
      responses:
        '200':
          description: Refunded operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
              example:
                id: 10245
                dateCreated: '2024-11-20T14:22:00.000Z'
                action: PURCHASE
                state: REVERSAL
                customer:
                  id: 789
                  uid: 23684cea-ca50-4c5c-b399-eb473e85b5ad
                  displayName: John Doe
                  membershipTier:
                    uid: silver-tier
                    name: Silver
                    rate: 7
                cashier:
                  id: 5
                  displayName: Jane Smith
                branch:
                  id: 1
                  displayName: Main Office
                points: 50
                certificatePoints: 0
                cash: 950
                total: 1000
                origin:
                  id: 10244
  /operations/calc:
    post:
      summary: Calculate purchase discount and cashback
      tags:
        - Operations
      description: >
        Returns information about available bonus points for redemption or
        discount amount (depending on

        loyalty program settings), the payment amount after applying
        discounts/bonuses, and the number of

        bonus points that will be awarded after the operation is completed.


        **Always call this endpoint before POST /operations** to get the correct
        `cash` value.

        Do not calculate discounts manually — the server applies all loyalty
        rules including

        membership tier rates, point limits, and skip-loyalty exclusions.


        The response depends on your company's `baseDiscountPolicy`:

        - **APPLY_DISCOUNT** — returns discount amount and percentage

        - **CHARGE_SCORES** — returns cashback points to be earned
      x-codeSamples:
        - lang: curl
          source: |
            curl -H "accept: application/json" \
            -H "Content-Type: application/json" \
            -H "X-Origin-Request-Id: $(uuidgen)" \
            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
            -u "<companyId>:<api_key>"
            -d '{ \
              "code":"456123", \
              "participant":{ \
                "uid":"23684cea-ca50-4c5c-b399-eb473e85b5ad", \
                "phone":"+12125551234" \
              }, \
              "receipt":{ \
                "total":100.0, \
                "points":50.0, \
                "skipLoyaltyTotal": 50.0 \
              } \
            }' -X POST "https://api.uds.app/partner/v2/operations/calc"
        - lang: PHP
          source: >
            $date = new DateTime();

            $url = "https://api.uds.app/partner/v2/operations/calc";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Set request body


            $postData = json_encode(
              array(
                'code' => 'string',
                'participant' => array(
                  'uid' => 'string',
                  'phone' => 'string'
                ),
                'receipt' => array(
                  'total' => 100.0,
                  'points' => 50.0,
                  'skipLoyaltyTotal' => 50.0
                )
              )
            );


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'POST',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $postData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='POST',
                url='/partner/v2/operations/calc',
                body=json.dumps({
                  'code': 'string',
                  'participant': {
                    'uid': 'string',
                    'phone': 'string'
                  },
                  'receipt': {
                    'total': 100.0,
                    'points': 50.0,
                    'skipLoyaltyTotal': 50.0
                  }
                }),
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Content-Type': 'application/json',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/operations/calc',
              'method': 'POST',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Content-Type': 'application/json',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const data = JSON.stringify({
              'code': 'string',
              'participant': {
                'uid': 'string',
                'phone': 'string'
              },
              'receipt': {
                'total': 100.0,
                'points': 50.0,
                'skipLoyaltyTotal': 50.0
              }
            });

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {

                console.log(
                  JSON.parse(response)
                );

              });
            });

            req.write(data);
            req.end();
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseCalcRequest'
      responses:
        '200':
          description: Purchase calculation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseCalcResponse'
              example:
                user:
                  uid: 23684cea-ca50-4c5c-b399-eb473e85b5ad
                  displayName: John Doe
                  phone: '+12125551234'
                  participant:
                    id: 789
                    points: 350.5
                    discountRate: 7
                    cashbackRate: 7
                    cashSpent: 1250
                    membershipTier:
                      uid: silver-tier
                      name: Silver
                      rate: 7
                  tags:
                    - id: 1
                      name: VIP
                purchase:
                  maxPoints: 200
                  total: 1000
                  skipLoyaltyTotal: 0
                  unredeemableTotal: 0
                  discountAmount: 70
                  discountPercent: 7
                  points: 200
                  pointsPercent: 20
                  netDiscount: 270
                  netDiscountPercent: 27
                  certificatePoints: 0
                  cash: 730
                  cashTotal: 730
                  cashBack: 51.1
                  maxScoresDiscount: 30
  /operations/reward:
    post:
      summary: Send bonus points to participants
      tags:
        - Operations
      description: >
        Award bonus points to one or more customers asynchronously. Each
        participant receives

        the specified amount of points and an optional push notification.


        Use this for promotional campaigns, birthday rewards, compensation, or
        loyalty bonuses.

        Processing is asynchronous — the endpoint returns immediately with the
        count of accepted participants.


        The `participants` field accepts customer IDs within the company
        (`customer -> participant -> id`).

        To deduct bonus points, pass a negative number in `points`.
      x-codeSamples:
        - lang: curl
          source: |
            curl -H "accept: application/json" \
            -H "Content-Type: application/json" \
            -H "X-Origin-Request-Id: $(uuidgen)" \
            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
            -u "<companyId>:<api_key>"
            -d '{ \
              "comment":"string", \
              "points":50.0, \
              "participants": [1, 3, 21], \
              "silent": false \
            }' -X POST "https://api.uds.app/partner/v2/operations/reward"
        - lang: PHP
          source: >
            $date = new DateTime();

            $url = "https://api.uds.app/partner/v2/operations/reward";

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Set request body


            $postData = json_encode(
              array(
                'comment' => 'string',
                'points' => 50.0,
                'participants' => array(1, 3, 21),
                'silent' => false
              )
            );


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'POST',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $postData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='POST',
                url='/partner/v2/operations/reward',
                body=json.dumps({
                  'code': 'string',
                  'participants': [1, 3, 17],
                  'points': 50.0,
                  'silent': false
                }),
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Content-Type': 'application/json',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/operations/reward',
              'method': 'POST',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Content-Type': 'application/json',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const data = JSON.stringify({
              'code': 'string',
              'participants': [1, 3, 17],
              'points': 50.0,
              'silent': false
            });

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {

                console.log(
                  JSON.parse(response)
                );

              });
            });

            req.write(data);
            req.end();
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - points
                - participants
              properties:
                points:
                  type: number
                  description: Points amount
                comment:
                  type: string
                  nullable: true
                  description: Comment visible to participant
                participants:
                  type: array
                  description: Participant ID list
                  items:
                    type: string
                silent:
                  type: boolean
                  nullable: true
                  description: Do not send push notification to customer (default false)
      responses:
        '202':
          description: Reward accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  accepted:
                    type: string
                    description: |
                      Total amount of the participants who will receive reward
                      points
              example:
                accepted: '3'
  /api/v2/events/operation:
    parameters:
      - $ref: '#/components/parameters/x-request-id'
      - $ref: '#/components/parameters/x-timestamp'
      - $ref: '#/components/parameters/x-signature'
    post:
      summary: Operation created
      servers:
        - url: 'https://webhook-server.domain/'
      tags:
        - Webhooks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Operation'
      security:
        - Webhook: []
      responses:
        '200':
          description: OK
  /api/v2/events/participant:
    parameters:
      - $ref: '#/components/parameters/x-request-id'
      - $ref: '#/components/parameters/x-timestamp'
      - $ref: '#/components/parameters/x-signature'
    post:
      summary: New participant
      servers:
        - url: 'https://webhook-server.domain/'
      tags:
        - Webhooks
      security:
        - Webhook: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Participant'
      responses:
        '200':
          description: OK
  /api/v2/events/goods-order:
    parameters:
      - $ref: '#/components/parameters/x-request-id'
      - $ref: '#/components/parameters/x-timestamp'
      - $ref: '#/components/parameters/x-signature'
    post:
      summary: New goods order
      servers:
        - url: 'https://webhook-server.domain/'
      tags:
        - Webhooks
      security:
        - Webhook: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoodsOrderDetailed'
      responses:
        '200':
          description: OK
  /goods:
    description: >
      The price list might have 3-level categories and each category might have
      20 subcategories
    get:
      tags:
        - Goods
      summary: List goods
      description: Retrieves a list of goods and categories in the company.
      parameters:
        - $ref: '#/components/parameters/max'
        - $ref: '#/components/parameters/offset'
        - name: nodeId
          description: Filter goods list by category id
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  rows:
                    type: array
                    description: Goods information.
                    items:
                      $ref: '#/components/schemas/GoodsInfoType'
                  total:
                    type: integer
                    description: Goods amount.
              example:
                rows:
                  - id: 100
                    name: Beverages
                    data:
                      type: CATEGORY
                    hidden: false
                    blocked: false
                    nodeId: null
                    externalId: beverages
                    dateCreated: '2024-01-15T10:00:00.000Z'
                  - id: 101
                    name: Espresso
                    data:
                      type: ITEM
                      price: 3.5
                      description: Classic Italian espresso
                      sku: BEV-001
                      offer:
                        offerPrice: 2.8
                        skipLoyalty: false
                      inventory:
                        inStock: null
                    hidden: false
                    blocked: false
                    nodeId: 100
                    externalId: espresso
                    imageUrls: []
                    dateCreated: '2024-01-15T10:05:00.000Z'
                total: 2
      x-codeSamples:
        - lang: curl
          source: >
            // Get price list starting from the top item

            curl -H 'Accept: application/json' \

            -H "X-Origin-Request-Id: $(uuidgen)" \

            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \

            -u "<companyId>:<api_key>"

            -X GET -s https://api.uds.app/partner/v2/goods?max=10&offset=0

            // Get price list items of the category with id=132

            curl -H 'Accept: application/json' \

            -H "X-Origin-Request-Id: $(uuidgen)" \

            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \

            -u "<companyId>:<api_key>"

            -X GET -s
            https://api.uds.app/partner/v2/goods?max=10&offset=0&nodeId=123
        - lang: PHP
          source: >
            /**
             * Get price list from the top item
            **/


            $date = new DateTime();

            $url = "https://api.uds.app/partner/v2/goods?max=10&offset=0";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company


            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'GET',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM)
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;


            /**
             * Get price list items of the category with id=132
            **/


            $date = new DateTime();

            $url =
            "https://api.uds.app/partner/v2/goods?max=10&offset=0&nodeId=123";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company


            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'GET',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM)
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            # Get price list from the top item

            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection
            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='GET',
                url='/partner/v2/goods?max=10&offset=0',
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()

            # Get price list items of the category with id=132

            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection
            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='GET',
                url='/partner/v2/goods?max=10&offset=0&nodeId=123',
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            /**
             * Get price list items of the category with nodeId=132
            **/

            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods?max=10&offset=0',
              'method': 'GET',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                console.log(
                  JSON.parse(response)
                );
              });
            });
            req.end();

            /**
             * Get price list items of the category with id=132
            **/

            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods?max=10&offset=0&nodeId=123',
              'method': 'GET',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                console.log(
                  JSON.parse(response)
                );
              });
            });
            req.end();
    post:
      tags:
        - Goods
      summary: Create goods or category
      description: >
        Creating an item/category in UDS. The ID of a successfully created item
        can be used as a `nodeId`

        to create an item/category in this category and get a list of internal
        items.


        ### Key points

        * The type of the object being created is specified in the `data.type`
        field. Three values are supported:
          - `CATEGORY` — to create a product category
          - `ITEM` — to create a product item
          - `VARYING_ITEM` — to create a product with variants
        * You can create subcategories within categories (up to three levels of
        nesting).

        * You can create up to 20 categories in the main list, 20 subcategories
        per category, and 20 subcategories per subcategory.

        * To create an item without a category, set `nodeId` to `null`.

        * To create an item with unlimited stock, set `inStock` to `null`.


        ### Errors

        | Status | Error Code | Description |

        |--------|------------|-------------|

        | `400` | `badRequest` | Validation errors occurred. See the `errors`
        field for details. |

        | `400` | `goods.nodeIndex.invalid` | Specifying a `nodeId` is not
        allowed when creating a category. |

        | `400` | `goods.limitIsReached` | The product limit has been exceeded.
        |

        | `401` | `unauthorized` | Invalid company ID or API Key. |
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoodsDetailed'
      responses:
        '200':
          description: Created goods item or category
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoodsDetailed'
              example:
                id: 201
                name: T-shirt
                nodeId: 100
                externalId: tshirt
                dateCreated: '2024-11-25T12:00:00.000Z'
                data:
                  type: ITEM
                  price: 25
                  description: Cotton T-shirt
                  sku: CLT-001
                  offer: null
                  inventory:
                    inStock: 50
                hidden: false
                blocked: false
                imageUrls: []
      x-codeSamples:
        - lang: curl
          source: >
            // create category 'Clothers'

            curl -H "accept: application/json" \

            -H "Content-Type: application/json" \

            -H "X-Origin-Request-Id: $(uuidgen)" \

            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \

            -u "<companyId>:<api_key>"

            -d '{ \
              "name": "Clothers", \
              "nodeId": null, \
              "externalId": "clothers", \
              "data": {
                "type": "CATEGORY"
              }
            }' -X POST "https://api.uds.app/partner/v2/goods"


            // create goods item without category, but with variants and array
            of photo imageIds, which have been uploaded in advance using
            /image-upload method

            curl -H "accept: application/json" \

            -H "Content-Type: application/json" \

            -H "X-Origin-Request-Id: $(uuidgen)" \

            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \

            -u "<companyId>:<api_key>"

            -d '{ \
              "name": "Apple", \
              "nodeId": null, \
              "externalId": "apple", \
              "data": {
                "type": "VARYING_ITEM",
                "description": "This is an item without category"
                "photos": [
                  "NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ=="
                ],
                "variants": [
                  {
                    "name": "red apple",
                    "price": 100.0,
                    "inventory":
                      {
                      "inStock": 17
                      }
                  },
                  {
                    "name": "green apple",
                    "price": 150.0,
                    "inventory":
                      {
                      "inStock": 10
                      }
                  }
                ]
              }
            }' -X POST "https://api.uds.app/partner/v2/goods"


            // create goods item in category with id=123 and array of photo
            imageIds, which have been uploaded in advance using /image-upload
            method

            curl -H "accept: application/json" \

            -H "Content-Type: application/json" \

            -H "X-Origin-Request-Id: $(uuidgen)" \

            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \

            -u "<companyId>:<api_key>"

            -d '{ \
              "name": "T-shirt", \
              "nodeId": 123, \
              "externalId": "tshirt", \
              "data": {
                "type": "ITEM",
                "price": 100.0,
                "photos": [
                  "NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ=="
                ],
                "description": "This is an item in category",
                "offer": {
                  "offerPrice": 90.0,
                  "skipLoyalty": true
                },
                "inventory": {
                  "inStock": 10
                }
              }
            }' -X POST "https://api.uds.app/partner/v2/goods"


            // create goods item with measurement

            curl -H "accept: application/json" \

            -H "Content-Type: application/json" \

            -H "X-Origin-Request-Id: $(uuidgen)" \

            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \

            -u "<companyId>:<api_key>"

            -d '{ \
              "name": "Shugar", \
              "externalId": "shugar", \
              "data": {
                "type": "ITEM",
                "price": 0.1,
                "description": "This is an item with measurement"
                "inventory": {
                  "inStock": 300000
                },
                "measurement": "GRAM",
                "increment": 500,
                "minQuantity": 500
              }
            }' -X POST "https://api.uds.app/partner/v2/goods"
        - lang: PHP
          source: >
            $url = "https://api.uds.app/partner/v2/goods";

            $companyId = 123456; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            /**
             * create category 'Clothers'
            **/


            $date = new DateTime();


            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)


            $categoryData = json_encode(
              array(
                'name' => 'Clothers',
                'nodeId' => null,
                'externalId' => 'clothers',
                'data' => array(
                    'type' => 'CATEGORY'
                  )
              )
            );


            $opts = array(
                'http' => array(
                    'method' => 'POST',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "Content-Type: application/json\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $categoryData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;


            /**
             * create goods item without category, but with variants and array of photo imageIds, which have been uploaded in advance using /image-upload method
            **/


            $date = new DateTime();

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)


            $varItemData = json_encode(
              array(
                'name' => 'Apple',
                'nodeId' => null,
                'externalId' => 'category1',
                'data' => array(
                    'type' => 'VARYING_ITEM',
                    'description' => 'This is an item without category',
                    'photos' => array(
                      'NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ=='
                    ),
                    'variants' => array(
                      array(
                        'name' => 'red apple',
                        'price' => 100.0,
                        'inventory' => array(
                            'inStock' => 17
                          )
                      ),
                      array(
                        'name' => 'green apple',
                        'price' => 150.0,
                        'inventory' =>array(
                            'inStock' =>10
                          )
                      ),
                    )
                  )
              )
            );


            $opts = array(
                'http' => array(
                    'method' => 'POST',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "Content-Type: application/json\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $varItemData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;


            /**
             * create goods item in category with id=123 and array of photo imageIds, which have been uploaded in advance using /image-upload method
            **/


            $date = new DateTime();

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)


            $itemData = json_encode(
              array(
                'name' => 'T-shirt',
                'nodeId' => 123,
                'externalId' => 'tshirt',
                'data' => array(
                    'type' => 'ITEM',
                    'price' => 100.0,
                    'description' => 'This is an item in category',
                    'photos' => array(
                      'NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ=='
                    ),
                    'offer'=> array(
                       'offerPrice'=> 90.0,
                       'skipLoyalty'=> true
                      ),
                    'inventory' =>array(
                        'inStock' =>null
                      )
                  )
              )
            );


            $opts = array(
                'http' => array(
                    'method' => 'POST',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "Content-Type: application/json\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $itemData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;


            /**
             * create goods item with measurement
            **/


            $date = new DateTime();

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)


            $itemData = json_encode(
              array(
                'name' => 'Shugar',
                'externalId' => 'shugar',
                'data' => array(
                    'type' => 'ITEM',
                    'price' => 0.1,
                    'description' => 'This is an item with measurement',
                    'inventory' => array(
                        'inStock' => 300000
                    ),
                    'measurement' => 'GRAM',
                    'increment' => 500,
                    'minQuantity' => 500
                  )
              )
            );


            $opts = array(
                'http' => array(
                    'method' => 'POST',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "Content-Type: application/json\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $itemData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection
            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            /**
             * create category 'Clothers'
            **/
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='POST',
                url='/partner/v2/goods',
                body=json.dumps({
                  'name': 'Clothers',
                  'nodeId': None,
                  'externalId': 'clothers',
                  'data': {
                      'type': 'CATEGORY'
                  }
                }),
                headers={
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8"),
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print(con.getresponse().read())
            con.close()
            /**
             * create goods item without category, but with variants and array of photo imageIds, which have been uploaded in advance using /image-upload method
            **/
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='POST',
                url='/partner/v2/goods',
                body=json.dumps({
                  'name': 'Applevdmkfmdkfmd',
                  'nodeId': None,
                  'externalId': 'varying-item-id',
                  'data': {
                    'type': 'VARYING_ITEM',
                    'description': 'This is an item without category',
                    'photos': [
                      'NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ==',
                    ],
                    'variants': [{
                      'name': 'red apple',
                      'price': 100.0,
                      'inventory': {
                        'inStock': 17
                      }
                    },
                    {
                      'name': 'green apple',
                      'price': 150.0,
                      'inventory': {
                        'inStock': 10
                      }
                    }]
                  }
                }),
                headers={
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8"),
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
            /**
             * create goods item in category with id=123 and array of photo imageIds, which have been uploaded in advance using /image-upload method
            **/
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='POST',
                url='/partner/v2/goods',
                body=json.dumps({
                  'name': 'T-shirt',
                  'nodeId': 123,
                  'externalId': 'tshirt',
                  'data': {
                      'type': 'ITEM',
                      'price': 100.0,
                      'description': 'This is an item in category',
                      'photos': [
                          'NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ==',
                      ],
                      'offer': {
                          'offerPrice': 90.0,
                          'skipLoyalty': true
                      },
                      'inventory': {
                        'inStock': null
                      }
                  }
                }),
                headers={
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8"),
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print(con.getresponse().read())
            con.close()
            /**
             * create goods item with measurement
            **/
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='POST',
                url='/partner/v2/goods',
                body=json.dumps({
                  'name': 'Shugar',
                  'externalId': 'shugar',
                  'data': {
                      'type': 'ITEM',
                      'price': 0.1,
                      'description': 'This is an item with measurement',
                      'inventory': {
                        'inStock': 300000
                      },
                      'measurement': 'GRAM',
                      'increment': 500,
                      'minQuantity': 500
                  }
                }),
                headers={
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8"),
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print(con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';
            /**
             * create category 'Clothers'
            **/
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods',
              'method': 'POST',
              'headers': {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                const responseData = JSON.parse(response);
                console.log(responseData);
              });
            });
            const requestData = JSON.stringify({
              'name': 'Clothers',
              'nodeId': null,
              'externalId': 'clothers',
              'data': {
                'type': 'CATEGORY'
              }
            });
            req.write(requestData);
            req.end();
            /**
             * create goods item without category, but with variants and array of photo imageIds, which have been uploaded in advance using /image-upload method
            **/
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods',
              'method': 'POST',
              'headers': {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                const responseData = JSON.parse(response);
                console.log(responseData);
              });
            });
            const requestData = JSON.stringify({
              'name': 'Applevdmkfmdkfmd',
              'nodeId': null,
              'externalId': 'category',
              'data': {
                'type': 'VARYING_ITEM',
                'description': 'This is an item without category',
                'photos': [
                    'NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ==',
                ],
                'variants': [
                  {
                    'name': 'red apple',
                    'price': 100.0,
                    'inventory': {
                      'inStock': 17
                    }
                  },
                  {
                    'name': 'green apple',
                    'price': 150.0,
                    'inventory': {
                      'inStock': 10
                    }
                  }
                ]
              }
            });
            req.write(requestData);
            req.end();
            /**
             * create goods item in category with id=123 and array of photo imageIds, which have been uploaded in advance using /image-upload method
            **/
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods',
              'method': 'POST',
              'headers': {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                const responseData = JSON.parse(response);
                console.log(responseData);
              });
            });
            const requestData = JSON.stringify({
              'name': 'T-shirt',
              'nodeId': 34430,
              'externalId': 'tshirt',
              'data': {
                'type': 'ITEM',
                'price': 100.0,
                'description': 'This is an item in category',
                'photos': [
                    'NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ==',
                ],
                'offer': {
                    'offerPrice': 90.0,
                    'skipLoyalty': true
                },
                'inventory': {
                  'inStock': null
                }
             }
            });
            req.write(requestData);
            req.end();
            /**
             * create goods item with measurement
            **/
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods',
              'method': 'POST',
              'headers': {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                const responseData = JSON.parse(response);
                console.log(responseData);
              });
            });
            const requestData = JSON.stringify({
              'name': 'Shugar',
              'externalId': 'shugar',
              'data': {
                'type': 'ITEM',
                'price': 100.0,
                'description': 'This is an item with measurement',
                'inventory': {
                  'inStock': 300000
                },
                'measurement': 'GRAM',
                'increment': 500,
                'minQuantity': 500
             }
            });
            req.write(requestData);
            req.end();
  '/goods/{id}':
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      tags:
        - Goods
      summary: Get goods/category by id
      description: >-
        Fetches a single goods item or category by its internal UDS ID. Returns
        full details including price, inventory, images, and promotional offers.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoodsDetailed'
              example:
                id: 345
                name: Espresso
                nodeId: 100
                externalId: espresso
                dateCreated: '2024-06-15T09:30:00.000Z'
                data:
                  type: ITEM
                  price: 3.5
                  description: Classic Italian espresso
                  sku: BEV-001
                  offer:
                    offerPrice: 2.8
                    skipLoyalty: false
                  inventory:
                    inStock: null
                hidden: false
                blocked: false
                imageUrls:
                  - 'https://cdn.uds.app/goods/espresso-main.jpg'
      x-codeSamples:
        - lang: curl
          source: |
            curl -H 'Accept: application/json' \
            -H "X-Origin-Request-Id: $(uuidgen)" \
            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
            -u "<companyId>:<api_key>"
            -X GET -s https://api.uds.app/partner/v2/goods/123
        - lang: PHP
          source: >
            $goodsId = 345; //set ID of goods

            $date = new DateTime();

            $url = "https://api.uds.app/partner/v2/goods/".$goodsId;

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'GET',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM)
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection
            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='GET',
                url='/partner/v2/goods/345',
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods/345',
              'method': 'GET',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                console.log(
                  JSON.parse(response)
                );
              });
            });
            req.end();
    put:
      tags:
        - Goods
      summary: Update goods/category by id
      description: >
        Update goods/category by its internal UDS ID.


        ### Key points

        * The type of the object being edited is specified in the `data.type`
        field. Three values are supported:
          - `CATEGORY` — for a category
          - `ITEM` — for a product item
          - `VARYING_ITEM` — for a product with variants
        * To move an item to a different category, specify the target category
        ID in `nodeId`.

        * Moving a category inside another category is not allowed.

        * To remove an item from its category (make it top-level), set `nodeId`
        to `null`.


        ### Errors

        | Status | Error Code | Description |

        |--------|------------|-------------|

        | `400` | `goods.nodeIndex.invalid` | Specifying a `nodeId` is not
        allowed when updating a category. |

        | `400` | `goods.limitIsReached` | The product limit has been exceeded.
        |
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoodsDetailed'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoodsDetailed'
              example:
                id: 345
                name: Espresso Double
                nodeId: 100
                externalId: espresso
                dateCreated: '2024-06-15T09:30:00.000Z'
                data:
                  type: ITEM
                  price: 4.5
                  description: Double shot espresso
                  sku: BEV-001
                  offer: null
                  inventory:
                    inStock: null
                hidden: false
                blocked: false
                imageUrls:
                  - 'https://cdn.uds.app/goods/espresso-main.jpg'
      x-codeSamples:
        - lang: curl
          source: >
            // update category 'Clothers'

            curl -H "accept: application/json" \

            -H "Content-Type: application/json" \

            -H "X-Origin-Request-Id: $(uuidgen)" \

            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \

            -u "<companyId>:<api_key>"

            -d '{ \
              "name": "Clothers and shoes", \
              "nodeId": null, \
              "externalId": "clothers", \
              "data": {
                "type": "CATEGORY"
              },
              "hidden": null
            }' -X PUT "https://api.uds.app/partner/v2/goods/123"


            // update goods item without category, but with variants and with
            array of photo imageIds, which have been uploaded in advance using
            /image-upload method

            curl -H "accept: application/json" \

            -H "Content-Type: application/json" \

            -H "X-Origin-Request-Id: $(uuidgen)" \

            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \

            -u "<companyId>:<api_key>"

            -d '{ \
              "name": "Apple", \
              "nodeId": null, \
              "externalId": "apple", \
              "hidden": null, \
              "data": {
                "type": "VARYING_ITEM",
                "photos": [
                    "NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ==",
                ],
                "description": "This is an item without category"
                "variants": [
                  {
                    "name": "red apple",
                    "price": 110.0
                  },
                  {
                    "name": "green apple",
                    "price": 160.0
                  }
                ]
              }
            }' -X PUT "https://api.uds.app/partner/v2/goods/111"


            // update goods item in category with array of photo imageIds, which
            have been uploaded in advance using /image-upload method

            curl -H "accept: application/json" \

            -H "Content-Type: application/json" \

            -H "X-Origin-Request-Id: $(uuidgen)" \

            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \

            -u "<companyId>:<api_key>"

            -d '{ \
              "name": "T-shirt", \
              "nodeId": 123, \
              "externalId": "tshirt", \
              "hidden": false, \
              "data": {
                "type": "ITEM",
                "price": 110.0,
                "photos": [
                    "NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ==",
                ],
                "description": "This is an item in category"
              }
            }' -X POST "https://api.uds.app/partner/v2/goods/222"


            // update goods item with measurement

            curl -H "accept: application/json" \

            -H "Content-Type: application/json" \

            -H "X-Origin-Request-Id: $(uuidgen)" \

            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \

            -u "<companyId>:<api_key>"

            -d '{ \
              "name": "Shugar", \
              "externalId": "shugar", \
              "data": {
                "type": "ITEM",
                "price": 0.1,
                "description": "This is an item with measurement"
                "inventory": {
                  "inStock": 300000
                },
                "measurement": "GRAM",
                "increment": 500,
                "minQuantity": 500
              }
            }' -X POST "https://api.uds.app/partner/v2/goods/222"
        - lang: PHP
          source: >
            $companyId = 123456; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            /**
             * update category 'Clothers'
            **/

            $date = new DateTime();

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $url = "https://api.uds.app/partner/v2/goods/123";


            $categoryData = json_encode(
              array(
                'name' => 'Clothers',
                'nodeId' => null,
                'hidden' => null,
                'externalId' => 'clothers',
                'data' => array(
                    'type' => 'CATEGORY'
                  )
              )
            );


            $opts = array(
                'http' => array(
                    'method' => 'PUT',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "Content-Type: application/json\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $categoryData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;


            /**
             * update goods item without category, but with variants and with array of photo imageIds, which have been uploaded in advance using /image-upload method
            **/


            $url = "https://api.uds.app/partner/v2/goods/111";

            $date = new DateTime();

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)


            $varItemData = json_encode(
              array(
                'name' => 'Apple',
                'nodeId' => null,
                'hidden' => null,
                'externalId' => 'category1',
                'data' => array(
                    'type' => 'VARYING_ITEM',
                    'description' => 'This is an item without category',
                    'photos' => array(
                      'NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ=='
                    ),
                    'variants' => array(
                      array(
                        'name' => 'red apple',
                        'price' => 100.0
                      ),
                      array(
                        'name' => 'green apple',
                        'price' => 150.0
                      ),
                    )
                  )
              )
            );


            $opts = array(
                'http' => array(
                    'method' => 'PUT',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "Content-Type: application/json\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $varItemData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;


            /**
             * update goods item in category with array of photo imageIds, which have been uploaded in advance using /image-upload method
            **/

            $url = "https://api.uds.app/partner/v2/goods/222";

            $date = new DateTime();


            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)


            $itemData = json_encode(
              array(
                'name' => 'T-shirt',
                'nodeId' => 123,
                'hidden' => false,
                'externalId' => 'tshirt',
                'data' => array(
                    'type' => 'ITEM',
                    'photos' => array(
                      'NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ=='
                    ),
                    'price' => 100.0,
                    'description' => 'This is an item in category'
                  )
              )
            );


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'PUT',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "Content-Type: application/json\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $itemData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;


            /**
             * update goods item with measurement
            **/

            $url = "https://api.uds.app/partner/v2/goods/222";

            $date = new DateTime();

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $itemData = json_encode(
              array(
                'name' => 'Shugar',
                'externalId' => 'shugar',
                'data' => array(
                    'type' => 'ITEM',
                    'price' => 0.1,
                    'description' => 'This is an item with measurement',
                    'inventory' => array(
                        'inStock' => 300000
                    ),
                    'measurement' => 'GRAM',
                    'increment' => 500,
                    'minQuantity' => 500
                )
              )
            );


            // Create a stream

            $opts = array(
                'http' => array(
                    'method' => 'PUT',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "Content-Type: application/json\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $itemData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $cont

            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            import ssl
            from datetime import datetime
            from http.client import HTTPSConnection
            authString = base64.b64encode(b'<companyId>:<apiKey>')
            /**
             * update category 'Clothers'
            **/
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='PUT',
                url='/partner/v2/goods/123',
                body=json.dumps({
                  'name': 'Clothers',
                  'nodeId': None,
                  'hidden': None,
                  'externalId': 'clothers',
                  'data': {
                      'type': 'CATEGORY'
                  }
                }),
                headers={
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8"),
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print(con.getresponse().read())
            con.close()

            /**
             * update goods item without category, but with variants and with array of photo imageIds, which have been uploaded in advance using /image-upload method
            **/
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='PUT',
                url='/partner/v2/goods/123',
                body=json.dumps({
                  'name': 'Apple',
                  'nodeId': None,
                  'hidden': None,
                  'externalId': 'category1',
                  'data': {
                    'type': 'VARYING_ITEM',
                    'description': 'This is an item without category',
                    'photos': [
                      'NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ==',
                    ],
                    'variants': [{
                      'name': 'red apple',
                      'price': 100.0
                    },
                    {
                      'name': 'green apple',
                      'price': 150.0
                    }]
                  }
                }),
                headers={
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8"),
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print(con.getresponse().read())
            con.close()

            /**
             * update goods item in category with array of photo imageIds, which have been uploaded in advance using /image-upload method
            **/
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='PUT',
                url='/partner/v2/goods/222',
                body=json.dumps({
                  'name': 'T-shirе',
                  'nodeId': 123,
                  'hidden': false,
                  'externalId': 'tshirt',
                  'data': {
                    'type': 'ITEM',
                    'photos': [
                      'NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ==',
                    ],
                    'description': 'This is an item in category',
                    'price': 100.0
                  }
                }),
                headers={
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8"),
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print(con.getresponse().read())
            con.close()

            /**
             * update goods item with measurement
            **/
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='PUT',
                url='/partner/v2/goods/222',
                body=json.dumps({
                  'name': 'Shugar',
                  'externalId': 'shugar',
                  'data': {
                    'type': 'ITEM',
                    'price': 0.1,
                    'description': 'This is an item with measurement',
                    'inventory': {
                      'inStock': 300000
                    },
                    'measurement': 'GRAM',
                    'increment': 500,
                    'minQuantity': 500
                  }
                }),
                headers={
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8"),
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print(con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';
            /**
             * update category 'Clothers'
            **/
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods/123',
              'method': 'PUT',
              'headers': {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const requestData = JSON.stringify({
              'name': 'New Clothers',
              'nodeId': null,
              'hidden': null,
              'externalId': 'clothers',
              'data': {
                  'type': 'CATEGORY'
              }
            });
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                console.log(
                  JSON.parse(response)
                );
              });
            });
            req.write(requestData);
            req.end();

            /**
             * update goods item without category, but with variants and with array of photo imageIds, which have been uploaded in advance using /image-upload method
            **/
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods/111',
              'method': 'PUT',
              'headers': {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const requestData = JSON.stringify({
              'name': 'Apple',
              'nodeId': null,
              'hidden': null,
              'externalId': 'category1',
              'data': {
                'type': 'VARYING_ITEM',
                'description': 'This is an item without category',
                'photos': [
                  'NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ==',
                ],
                'variants': [{
                  'name': 'red apple',
                  'price': 100.0
                },
                {
                  'name': 'green apple',
                  'price': 150.0
                }]
              }
            });
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                console.log(
                  JSON.parse(response)
                );
              });
            });
            req.write(requestData);
            req.end();

            /**
             * update goods item in category with array of photo imageIds, which have been uploaded in advance using /image-upload method
            **/
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods/222',
              'method': 'PUT',
              'headers': {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const requestData = JSON.stringify({
                  'name': 'T-shirе',
                  'nodeId': 123,
                  'hidden': false,
                  'externalId': 'external',
                  'data': {
                    'type': 'ITEM',
                    'description': 'This is an item in category',
                    'photos': [
                      'NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ==',
                    ],
                    'price': 100.0
                  }
            });
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                console.log(
                  JSON.parse(response)
                );
              });
            });
            req.write(requestData);
            req.end();

            /**
             * update goods item with measurement
            **/
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods/222',
              'method': 'PUT',
              'headers': {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const requestData = JSON.stringify({
              'name': 'Shugar',
              'externalId': 'shugar',
              'data': {
                'type': 'ITEM',
                'price': 100.0,
                'description': 'This is an item with measurement',
                'inventory': {
                  'inStock': 300000
                },
                'measurement': 'GRAM',
                'increment': 500,
                'minQuantity': 500
              }
            });
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                console.log(
                  JSON.parse(response)
                );
              });
            });
            req.write(requestData);
            req.end();
    delete:
      tags:
        - Goods
      summary: Delete goods/category
      description: Delete goods/category by its ID
      responses:
        '204':
          description: Successfully deleted
      x-codeSamples:
        - lang: curl
          source: |
            curl -H 'Accept: application/json' \
            -H "X-Origin-Request-Id: $(uuidgen)" \
            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
            -u "<companyId>:<api_key>"
            -X DELETE -s https://api.uds.app/partner/v2/goods/123
        - lang: PHP
          source: >
            $goodsId = 345; //set ID of deleting goods

            $date = new DateTime();

            $url = "https://api.uds.app/partner/v2/goods/".$goodsId;

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'DELETE',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM)
                )
            );


            $context = stream_context_create($opts);


            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection
            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='DELETE',
                url='/partner/v2/goods/345',
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods/345',
              'method': 'DELETE',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                console.log(
                  JSON.parse(response)
                );
              });
            });
            req.end();
  '/goods/external/{externalId}':
    parameters:
      - $ref: '#/components/parameters/externalId'
    get:
      tags:
        - Goods
      summary: Get item/category by external id (beta)
      description: >-
        Fetches a single goods item or category by its external identifier in
        the company.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoodsDetailed'
              example:
                id: 345
                name: Espresso
                nodeId: 100
                externalId: espresso
                dateCreated: '2024-06-15T09:30:00.000Z'
                data:
                  type: ITEM
                  price: 3.5
                  description: Classic Italian espresso
                  sku: BEV-001
                  offer: null
                  inventory:
                    inStock: null
                hidden: false
                blocked: false
                imageUrls:
                  - 'https://cdn.uds.app/goods/espresso-main.jpg'
      x-codeSamples:
        - lang: curl
          source: |
            curl -H 'Accept: application/json' \
            -H "X-Origin-Request-Id: $(uuidgen)" \
            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
            -u "<companyId>:<api_key>"
            -X GET -s https://api.uds.app/partner/v2/goods/external/abc123
        - lang: PHP
          source: >
            $goodsExternalId = 345; //set externalId of goods

            $date = new DateTime();

            $url =
            "https://api.uds.app/partner/v2/goods/external/".$goodsExternalId;

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'GET',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM)
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection
            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='GET',
                url='/partner/v2/goods/external/abc345',
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods/external/abc345',
              'method': 'GET',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                console.log(
                  JSON.parse(response)
                );
              });
            });
            req.end();
    put:
      tags:
        - Goods
      summary: Update item/category by external id (beta)
      description: >
        Update item/category by external identifier.


        ### Key points

        * The type of the object being edited is specified in the `data.type`
        field. Three values are supported:
          - `CATEGORY` — for a category
          - `ITEM` — for a product item
          - `VARYING_ITEM` — for a product with variants
        * To move an item to a different category, specify the target category
        ID in `nodeId`.

        * To remove an item from its category (make it top-level), set `nodeId`
        to `null`.


        ### Errors

        | Status | Error Code | Description |

        |--------|------------|-------------|

        | `400` | `goods.nodeIndex.invalid` | Specifying a `nodeId` is not
        allowed when updating a category. |

        | `404` | `notFound` | Item/category with the given external identifier
        was not found. |
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoodsDetailed'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoodsDetailed'
              example:
                id: 345
                name: Espresso Double
                nodeId: 100
                externalId: espresso
                dateCreated: '2024-06-15T09:30:00.000Z'
                data:
                  type: ITEM
                  price: 4.5
                  description: Double shot espresso
                  sku: BEV-001
                  offer: null
                  inventory:
                    inStock: null
                hidden: false
                blocked: false
                imageUrls:
                  - 'https://cdn.uds.app/goods/espresso-main.jpg'
      x-codeSamples:
        - lang: curl
          source: >
            // update category 'Clothers'

            curl -H "accept: application/json" \

            -H "Content-Type: application/json" \

            -H "X-Origin-Request-Id: $(uuidgen)" \

            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \

            -u "<companyId>:<api_key>"

            -d '{ \
              "name": "Clothers and shoes", \
              "nodeId": null, \
              "externalId": "abc123", \
              "data": {
                "type": "CATEGORY"
              },
              "hidden": false
            }' -X PUT "https://api.uds.app/partner/v2/goods/external/abc123"


            // update goods item without category, but with variants and with
            array of photo imageIds, which have been uploaded in advance using
            /image-upload method

            curl -H "accept: application/json" \

            -H "Content-Type: application/json" \

            -H "X-Origin-Request-Id: $(uuidgen)" \

            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \

            -u "<companyId>:<api_key>"

            -d '{ \
              "name": "Apple", \
              "nodeId": null, \
              "externalId": "abc123", \
              "hidden": false, \
              "data": {
                "type": "VARYING_ITEM",
                "photos": [
                    "NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ==",
                ],
                "description": "This is an item without category"
                "variants": [
                  {
                    "name": "red apple",
                    "price": 110.0
                  },
                  {
                    "name": "green apple",
                    "price": 160.0
                  }
                ]
              }
            }' -X PUT "https://api.uds.app/partner/v2/goods/external/abc111"


            // update goods item in category with array of photo imageIds, which
            have been uploaded in advance using /image-upload method

            curl -H "accept: application/json" \

            -H "Content-Type: application/json" \

            -H "X-Origin-Request-Id: $(uuidgen)" \

            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \

            -u "<companyId>:<api_key>"

            -d '{ \
              "name": "T-shirt", \
              "nodeId": 123, \
              "externalId": "abc222", \
              "hidden": false, \
              "data": {
                "type": "ITEM",
                "price": 110.0,
                "photos": [
                    "NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ==",
                ],
                "description": "This is an item in category"
              }
            }' -X POST "https://api.uds.app/partner/v2/goods/external/abc222"


            // update goods item with measurement

            curl -H "accept: application/json" \

            -H "Content-Type: application/json" \

            -H "X-Origin-Request-Id: $(uuidgen)" \

            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \

            -u "<companyId>:<api_key>"

            -d '{ \
              "name": "Sugar", \
              "externalId": "abc222", \
              "data": {
                "type": "ITEM",
                "price": 0.1,
                "description": "This is an item with measurement"
                "inventory": {
                  "inStock": 300000
                },
                "measurement": "GRAM",
                "increment": 500,
                "minQuantity": 500
              }
            }' -X POST "https://api.uds.app/partner/v2/goods/external/abc222"
        - lang: PHP
          source: >
            $companyId = 123456; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            /**
             * update category 'Clothers'
            **/

            $date = new DateTime();

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $url = "https://api.uds.app/partner/v2/goods/external/abc123";


            $categoryData = json_encode(
              array(
                'name' => 'Clothers',
                'nodeId' => null,
                'hidden' => null,
                'externalId' => 'abc123',
                'data' => array(
                    'type' => 'CATEGORY'
                  )
              )
            );


            $opts = array(
                'http' => array(
                    'method' => 'PUT',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "Content-Type: application/json\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $categoryData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;


            /**
             * update goods item without category, but with variants and with array of photo imageIds, which have been uploaded in advance using /image-upload method
            **/


            $url = "https://api.uds.app/partner/v2/goods/external/abc111";

            $date = new DateTime();

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)


            $varItemData = json_encode(
              array(
                'name' => 'Apple',
                'nodeId' => null,
                'hidden' => null,
                'externalId' => 'abc111',
                'data' => array(
                    'type' => 'VARYING_ITEM',
                    'description' => 'This is an item without category',
                    'photos' => array(
                      'NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ=='
                    ),
                    'variants' => array(
                      array(
                        'name' => 'red apple',
                        'price' => 100.0
                      ),
                      array(
                        'name' => 'green apple',
                        'price' => 150.0
                      ),
                    )
                  )
              )
            );


            $opts = array(
                'http' => array(
                    'method' => 'PUT',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "Content-Type: application/json\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $varItemData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;


            /**
             * update goods item in category with array of photo imageIds, which have been uploaded in advance using /image-upload method
            **/

            $url = "https://api.uds.app/partner/v2/goods/external/abc222";

            $date = new DateTime();


            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)


            $itemData = json_encode(
              array(
                'name' => 'T-shirt',
                'nodeId' => 123,
                'hidden' => false,
                'externalId' => 'abc222',
                'data' => array(
                    'type' => 'ITEM',
                    'photos' => array(
                      'NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ=='
                    ),
                    'price' => 100.0,
                    'description' => 'This is an item in category'
                  )
              )
            );


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'PUT',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "Content-Type: application/json\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $itemData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;


            /**
             * update goods item with measurement
            **/

            $url = "https://api.uds.app/partner/v2/goods/external/abc222";

            $date = new DateTime();

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $itemData = json_encode(
              array(
                'name' => 'Shugar',
                'externalId' => 'abc222',
                'data' => array(
                    'type' => 'ITEM',
                    'price' => 0.1,
                    'description' => 'This is an item with measurement',
                    'inventory' => array(
                        'inStock' => 300000
                    ),
                    'measurement' => 'GRAM',
                    'increment' => 500,
                    'minQuantity' => 500
                )
              )
            );


            // Create a stream

            $opts = array(
                'http' => array(
                    'method' => 'PUT',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "Content-Type: application/json\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $itemData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $cont

            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            import ssl
            from datetime import datetime
            from http.client import HTTPSConnection
            authString = base64.b64encode(b'<companyId>:<apiKey>')
            /**
             * update category 'Clothers'
            **/
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='PUT',
                url='/partner/v2/goods/external/abc123',
                body=json.dumps({
                  'name': 'Clothers',
                  'nodeId': None,
                  'hidden': None,
                  'externalId': 'abc123',
                  'data': {
                      'type': 'CATEGORY'
                  }
                }),
                headers={
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8"),
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print(con.getresponse().read())
            con.close()

            /**
             * update goods item without category, but with variants and with array of photo imageIds, which have been uploaded in advance using /image-upload method
            **/
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='PUT',
                url='/partner/v2/goods/external/abc123',
                body=json.dumps({
                  'name': 'Apple',
                  'nodeId': None,
                  'hidden': None,
                  'externalId': 'abc123',
                  'data': {
                    'type': 'VARYING_ITEM',
                    'description': 'This is an item without category',
                    'photos': [
                      'NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ==',
                    ],
                    'variants': [{
                      'name': 'red apple',
                      'price': 100.0
                    },
                    {
                      'name': 'green apple',
                      'price': 150.0
                    }]
                  }
                }),
                headers={
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8"),
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print(con.getresponse().read())
            con.close()

            /**
             * update goods item in category with array of photo imageIds, which have been uploaded in advance using /image-upload method
            **/
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='PUT',
                url='/partner/v2/goods/external/abc222',
                body=json.dumps({
                  'name': 'T-shirt',
                  'nodeId': 123,
                  'hidden': false,
                  'externalId': 'abc222',
                  'data': {
                    'type': 'ITEM',
                    'photos': [
                      'NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ==',
                    ],
                    'description': 'This is an item in category',
                    'price': 100.0
                  }
                }),
                headers={
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8"),
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print(con.getresponse().read())
            con.close()

            /**
             * update goods item with measurement
            **/
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='PUT',
                url='/partner/v2/goods/external/abc222',
                body=json.dumps({
                  'name': 'Shugar',
                  'externalId': 'abc222',
                  'data': {
                    'type': 'ITEM',
                    'price': 0.1,
                    'description': 'This is an item with measurement',
                    'inventory': {
                      'inStock': 300000
                    },
                    'measurement': 'GRAM',
                    'increment': 500,
                    'minQuantity': 500
                  }
                }),
                headers={
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8"),
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print(con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';
            /**
             * update category 'Clothers'
            **/
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods/external/abc123',
              'method': 'PUT',
              'headers': {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const requestData = JSON.stringify({
              'name': 'New Clothers',
              'nodeId': null,
              'hidden': null,
              'externalId': 'abc123',
              'data': {
                  'type': 'CATEGORY'
              }
            });
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                console.log(
                  JSON.parse(response)
                );
              });
            });
            req.write(requestData);
            req.end();

            /**
             * update goods item without category, but with variants and with array of photo imageIds, which have been uploaded in advance using /image-upload method
            **/
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods/external/abc111',
              'method': 'PUT',
              'headers': {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const requestData = JSON.stringify({
              'name': 'Apple',
              'nodeId': null,
              'hidden': null,
              'externalId': 'abc111',
              'data': {
                'type': 'VARYING_ITEM',
                'description': 'This is an item without category',
                'photos': [
                  'NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ==',
                ],
                'variants': [{
                  'name': 'red apple',
                  'price': 100.0
                },
                {
                  'name': 'green apple',
                  'price': 150.0
                }]
              }
            });
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                console.log(
                  JSON.parse(response)
                );
              });
            });
            req.write(requestData);
            req.end();

            /**
             * update goods item in category with array of photo imageIds, which have been uploaded in advance using /image-upload method
            **/
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods/external/abc222',
              'method': 'PUT',
              'headers': {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const requestData = JSON.stringify({
                  'name': 'T-shirе',
                  'nodeId': 123,
                  'hidden': false,
                  'externalId': 'abc222',
                  'data': {
                    'type': 'ITEM',
                    'description': 'This is an item in category',
                    'photos': [
                      'NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ==',
                    ],
                    'price': 100.0
                  }
            });
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                console.log(
                  JSON.parse(response)
                );
              });
            });
            req.write(requestData);
            req.end();

            /**
             * update goods item with measurement
            **/
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods/external/abc222',
              'method': 'PUT',
              'headers': {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const requestData = JSON.stringify({
              'name': 'Shugar',
              'externalId': 'abc222',
              'data': {
                'type': 'ITEM',
                'price': 100.0,
                'description': 'This is an item with measurement',
                'inventory': {
                  'inStock': 300000
                },
                'measurement': 'GRAM',
                'increment': 500,
                'minQuantity': 500
              }
            });
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                console.log(
                  JSON.parse(response)
                );
              });
            });
            req.write(requestData);
            req.end();
    delete:
      tags:
        - Goods
      summary: Delete item/category by external id (beta)
      description: Delete item/category by its external identifier.
      responses:
        '204':
          description: Successfully deleted
      x-codeSamples:
        - lang: curl
          source: |
            curl -H 'Accept: application/json' \
            -H "X-Origin-Request-Id: $(uuidgen)" \
            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
            -u "<companyId>:<api_key>"
            -X DELETE -s https://api.uds.app/partner/v2/goods/external/abc123
        - lang: PHP
          source: >
            $goodsId = 345; //set ID of deleting goods

            $date = new DateTime();

            $url = "https://api.uds.app/partner/v2/goods/".$goodsId;

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'DELETE',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM)
                )
            );


            $context = stream_context_create($opts);


            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection
            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='DELETE',
                url='/partner/v2/goods/external/abc345',
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods/external/abc345',
              'method': 'DELETE',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                console.log(
                  JSON.parse(response)
                );
              });
            });
            req.end();
  '/goods-orders/{id}':
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      tags:
        - Goods Order
      summary: Get goods order detailed info by id (Beta)
      description: Goods order detailed info
      x-codeSamples:
        - lang: curl
          source: |
            curl -H 'Accept: application/json' \
                 -H "X-Origin-Request-Id: $(uuidgen)" \
                 -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
                 -u "<companyId>:<api_key>"
                 -X GET -s https://api.uds.app/partner/v2/goods-orders/123
        - lang: PHP
          source: >
            $date = new DateTime();

            $url = "https://api.uds.app/partner/v2/goods-orders/123";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Create a stream

            $opts = array(
                'http' => array(
                    'method' => 'GET',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM)
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='GET',
                url='/partner/v2/goods-orders/123',
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8"),
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods-orders/123',
              'method': 'GET',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {

                console.log(
                  JSON.parse(response)
                );

              });
            });

            req.end();
      responses:
        '200':
          description: Goods order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoodsOrderDetailed'
              example:
                id: 5001
                dateCreated: '2024-11-20T10:00:00.000Z'
                comment: Please deliver before 6 PM
                state: NEW
                orderStatus: ACCEPTED
                cash: 45
                points: 5
                total: 50
                certificatePoints: 0
                customer:
                  id: 789
                  uid: 23684cea-ca50-4c5c-b399-eb473e85b5ad
                  displayName: John Doe
                  membershipTier:
                    uid: silver-tier
                    name: Silver
                    rate: 7
                delivery:
                  type: DELIVERY
                  receiverName: John Doe
                  receiverPhone: '+12125551234'
                  userComment: Ring doorbell twice
                  deliveryCase:
                    name: Zone A
                    value: 5
                  address: '123 Main St, Apt 4B, New York, NY 10001'
                paymentMethod:
                  type: CASH
                  name: null
                  online: false
                onlinePayment: null
                items:
                  - id: 101
                    externalId: espresso
                    name: Espresso
                    variantName: null
                    sku: BEV-001
                    type: ITEM
                    qty: 2
                    price: 3.5
                    offerPrice: null
                    skipLoyalty: false
                  - id: 102
                    externalId: croissant
                    name: Croissant
                    variantName: null
                    sku: BAK-001
                    type: ITEM
                    qty: 1
                    price: 4
                    offerPrice: 3.2
                    skipLoyalty: false
                purchase:
                  maxPoints: 10
                  total: 50
                  cash: 45
                  points: 5
                  cashBack: 3.15
    put:
      tags:
        - Goods Order
      summary: Change the goods order (Beta)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoodsOrderUpdate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoodsOrderDetailed'
              example:
                id: 5001
                dateCreated: '2024-11-20T10:00:00.000Z'
                comment: Please deliver before 6 PM
                state: NEW
                orderStatus: ACCEPTED
                cash: 220
                points: 0
                total: 220
                certificatePoints: 0
                customer:
                  id: 789
                  uid: 23684cea-ca50-4c5c-b399-eb473e85b5ad
                  displayName: John Doe
                delivery:
                  type: DELIVERY
                  receiverName: John Doe
                  receiverPhone: '+12125551234'
                  deliveryCase:
                    name: new zone
                    value: 0
                  address: '123 Main St, Apt 4B, New York, NY 10001'
                paymentMethod:
                  type: CASH
                  online: false
                items:
                  - id: 111
                    name: Apple
                    variantName: red
                    type: VARYING_ITEM
                    qty: 2
                    price: 100
                    skipLoyalty: false
                  - externalId: '22222'
                    name: new green apple
                    type: ITEM
                    qty: 2
                    price: 110
                    skipLoyalty: false
                purchase:
                  maxPoints: 44
                  total: 220
                  cash: 220
                  points: 0
                  cashBack: 15.4
      x-codeSamples:
        - lang: curl
          source: |
            curl -H "accept: application/json" \
            -H "Content-Type: application/json" \
            -H "X-Origin-Request-Id: $(uuidgen)" \
            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
            -u "<companyId>:<api_key>"
            -d '{ \
                "deliveryCase": {"name": "new zone", "value": 0}, \
                "items": [{
                  "id": 111, \
                  "variantName": "red", \
                  "qty": 2 \
                  },{ \
                  "externalId": 22222, \
                  "name": "new green apple", \
                  "price": 110.0, \
                  "qty": 2, \
                  "skipLoyalty": false \
                  }] \
                }' \
            -X PUT "https://api.uds.app/partner/v2/goods-orders/123"
        - lang: PHP
          source: >
            $date = new DateTime();

            $url = "https://api.uds.app/partner/v2/goods-orders/123";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Change quantity of the one item and add new one unknown for UDS

            $varOrderData = json_encode(
              array(
                'deliveryCase' => array(
                    'name' => 'new zone',
                    'value' => 0
                    ),
                'items' => array(
                    array(
                      'id' => 111,
                      'variantName' => 'red',
                      'qty' => 2
                    ),
                    array(
                      'externalId' => 22222,
                      'name' => 'new green apple',
                      'price' => 110.0,
                      'qty' => 2,
                      'skipLoyalty' => false
                    )
                )
              )
            );


            // Create a stream

            $opts = array(
                'http' => array(
                    'method' => 'PUT',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "Content-Type: application/json\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $varOrderData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            import ssl
            from datetime import datetime
            from http.client import HTTPSConnection
            authString = base64.b64encode(b'<companyId>:<apiKey>')

            /**
             * Change quantity of the one item and add new one unknown for UDS
            **/
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='PUT',
                url='/partner/v2/goods-orders/123',
                body=json.dumps({
                  'deliveryCase': {
                    'name': 'new zone',
                    'value': 0
                  },
                  'items': [
                    {
                      'id': 111,
                      'variantName': 'red',
                      'qty': 2
                    },
                    {
                      'externalId': 22222,
                      'name': 'new green apple',
                      'price': 150.0,
                      'qty': 2,
                      'skipLoyalty': false
                    }
                  ]
                }),
                headers={
                    'Accept': 'application/json',
                    'Content-Type': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8"),
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print(con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';
            /**
             * update goods item without category, but with variants
            **/
            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods-orders/123',
              'method': 'PUT',
              'headers': {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };
            const requestData = JSON.stringify({
              'deliveryCase': {
                'name': 'new zone',
                'value': 0
              },
              'items': [
                {
                  'id': 111,
                  'variantName': 'red',
                  'qty': 2
                },
                {
                  'externalId': 22222,
                  'name': 'new green apple',
                  'price': 150.0,
                  'qty': 2,
                  'skipLoyalty': false
                }
              ]
            });
            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                console.log(
                  JSON.parse(response)
                );
              });
            });
            req.write(requestData);
            req.end();
  '/goods-orders/{id}/external-info':
    parameters:
      - $ref: '#/components/parameters/id'
    post:
      tags:
        - Goods Order
      summary: Change the goods order external store information
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalInfoUpdateModel'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoodsOrderDetailed'
              example:
                id: 5001
                dateCreated: '2024-11-20T10:00:00.000Z'
                comment: Please deliver before 6 PM
                state: NEW
                orderStatus: ACCEPTED
                cash: 220
                points: 0
                total: 220
                certificatePoints: 0
                customer:
                  id: 789
                  uid: 23684cea-ca50-4c5c-b399-eb473e85b5ad
                  displayName: John Doe
                delivery:
                  type: DELIVERY
                  receiverName: John Doe
                  receiverPhone: '+12125551234'
                  deliveryCase:
                    name: new zone
                    value: 0
                  address: '123 Main St, Apt 4B, New York, NY 10001'
                paymentMethod:
                  type: CASH
                  online: false
                items:
                  - id: 111
                    name: Apple
                    variantName: red
                    type: VARYING_ITEM
                    qty: 2
                    price: 100
                    skipLoyalty: false
                  - externalId: '22222'
                    name: new green apple
                    type: ITEM
                    qty: 2
                    price: 110
                    skipLoyalty: false
                purchase:
                  maxPoints: 44
                  total: 220
                  cash: 220
                  points: 0
                  cashBack: 15.4
                externalInfo:
                  link: 'https://www.ozon.ru/my/orderdetails/?order=01100001-0001'
                  id: 01100001-0001
  '/goods-orders/{id}/complete':
    parameters:
      - $ref: '#/components/parameters/id'
    post:
      tags:
        - Goods Order
      summary: Completes the goods order (Beta)
      description: Completes the goods order with the ID and creates a transaction
      x-codeSamples:
        - lang: curl
          source: |
            curl -H "accept: application/json" \
            -H "Content-Type: application/json" \
            -H "X-Origin-Request-Id: $(uuidgen)" \
            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
            -u "<companyId>:<api_key>"
            -X POST "https://api.uds.app/partner/v2/goods-orders/123/complete"
        - lang: PHP
          source: >
            $date = new DateTime();

            $url = "https://api.uds.app/partner/v2/goods-orders/123/complete";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            $opts = array(
                'http' => array(
                    'method' => 'POST',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
              method='POST',
              url='/partner/v2/goods-orders/123/complete',
              headers={
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Content-Type': 'application/json',
                'Authorization': 'Basic ' + authString.decode("utf-8"),
                'X-Origin-Request-Id': str(uuid.uuid4()),
                'X-Timestamp': datetime.now().isoformat(),
              }
            )
            print(con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods-orders/123/complete',
              'method': 'POST',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Content-Type': 'application/json',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                console.log(
                  JSON.parse(response)
                );

              });
            });
            req.end();
      responses:
        '200':
          description: Completed order with transaction
          content:
            application/json:
              schema:
                properties:
                  transaction:
                    type: object
                    description: Transaction information.
                    properties:
                      id:
                        type: integer
                        format: int64
                        description: Transaction ID
                  order:
                    $ref: '#/components/schemas/GoodsOrderDetailed'
              example:
                transaction:
                  id: 10300
                order:
                  id: 5001
                  dateCreated: '2024-11-20T10:00:00.000Z'
                  state: COMPLETED
                  orderStatus: READY
                  cash: 45
                  points: 5
                  total: 50
                  certificatePoints: 0
  '/goods-orders/{id}/code':
    parameters:
      - $ref: '#/components/parameters/id'
    post:
      tags:
        - Goods Order
      summary: Generate code to complete order (Beta)
      description: Generate code to complete order the goods order with the ID
      x-codeSamples:
        - lang: curl
          source: |
            curl -H "accept: application/json" \
            -H "Content-Type: application/json" \
            -H "X-Origin-Request-Id: $(uuidgen)" \
            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
            -u "<companyId>:<api_key>"
            -X POST "https://api.uds.app/partner/v2/goods-orders/123/code"
        - lang: PHP
          source: >
            $date = new DateTime();

            $url = "https://api.uds.app/partner/v2/goods-orders/123/code";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            $opts = array(
                'http' => array(
                    'method' => 'POST',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
              method='POST',
              url='/partner/v2/goods-orders/123/code',
              headers={
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Content-Type': 'application/json',
                'Authorization': 'Basic ' + authString.decode("utf-8"),
                'X-Origin-Request-Id': str(uuid.uuid4()),
                'X-Timestamp': datetime.now().isoformat(),
              }
            )
            print(con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods-orders/123/code',
              'method': 'POST',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Content-Type': 'application/json',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                console.log(
                  JSON.parse(response)
                );

              });
            });
            req.end();
      responses:
        '200':
          description: Generated completion code
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: Payment code to complete the goods order
              example:
                code: '874512'
  '/goods-orders/{id}/change-status':
    parameters:
      - $ref: '#/components/parameters/id'
    post:
      tags:
        - Goods Order
      summary: Change goods order status(Beta)
      description: Change the processing status of a goods order by order ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                orderStatus:
                  description: Order processing status
                  type: string
                  enum:
                    - WAITING_PAYMENT
                    - ACCEPTED
                    - READY
              required:
                - orderStatus
      x-codeSamples:
        - lang: curl
          source: |
            curl -H 'Accept: application/json' \
                 -H "Content-Type: application/json" \
                 -H "X-Origin-Request-Id: $(uuidgen)" \
                 -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
                 -u "<companyId>:<api_key>"
                 -d '{"orderStatus": "ACCEPTED"}'
                 -X POST -s https://api.uds.app/partner/v2/goods-orders/123/change-status
        - lang: PHP
          source: >
            $date = new DateTime();

            $url =
            "https://api.uds.app/partner/v2/goods-orders/123/change-status";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey
             // Set request body

            $postData = json_encode(
              array("orderStatus", "ACCEPTED")  // status of order
            );


            // Create a stream

            $opts = array(
                'http' => array(
                    'method' => 'POST',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $postData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='POST',
                url='/partner/v2/goods-orders/123/change-status',
                body=json.dumps({'orderStatus': 'READY'}),
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Content-Type': 'application/json',
                    'Authorization': 'Basic ' + authString.decode("utf-8"),
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods-orders/123/change-status',
              'method': 'POST',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Content-Type': 'application/json',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const data = JSON.stringify({'orderStatus': 'READY'});

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {

                console.log(
                  JSON.parse(response)
                );

              });
            });

            req.end();
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoodsOrderDetailed'
              example:
                id: 5001
                dateCreated: '2024-11-20T10:00:00.000Z'
                state: NEW
                orderStatus: ACCEPTED
                cash: 45
                points: 5
                total: 50
                certificatePoints: 0
                customer:
                  id: 789
                  uid: 23684cea-ca50-4c5c-b399-eb473e85b5ad
                  displayName: John Doe
                items:
                  - id: 101
                    name: Espresso
                    type: ITEM
                    qty: 2
                    price: 3.5
                    skipLoyalty: false
  '/goods-orders/{id}/cancel':
    parameters:
      - $ref: '#/components/parameters/id'
    post:
      tags:
        - Goods Order
      summary: Cancel goods order (Beta)
      description: Cancel a goods order by order ID.
      x-codeSamples:
        - lang: curl
          source: |
            curl -H 'Accept: application/json' \
                 -H "X-Origin-Request-Id: $(uuidgen)" \
                 -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
                 -u "<companyId>:<api_key>"
                 -X POST -s https://api.uds.app/partner/v2/goods-orders/123/cancel
        - lang: PHP
          source: >
            $date = new DateTime();

            $url = "https://api.uds.app/partner/v2/goods-orders/123/cancel";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Create a stream

            $opts = array(
                'http' => array(
                    'method' => 'POST',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM)
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='POST',
                url='/partner/v2/goods-orders/123/cancel',
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8"),
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/goods-orders/123/cancel',
              'method': 'POST',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {

                console.log(
                  JSON.parse(response)
                );

              });
            });

            req.end();
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoodsOrderDetailed'
              example:
                id: 5001
                dateCreated: '2024-11-20T10:00:00.000Z'
                state: DELETED
                orderStatus: null
                cash: 0
                points: 0
                total: 50
                certificatePoints: 0
                customer:
                  id: 789
                  uid: 23684cea-ca50-4c5c-b399-eb473e85b5ad
                  displayName: John Doe
                items:
                  - id: 101
                    name: Espresso
                    type: ITEM
                    qty: 2
                    price: 3.5
                    skipLoyalty: false
  /image-upload-url:
    post:
      tags:
        - Image uploading
      summary: Generate image upload presigned url.
      x-codeSamples:
        - lang: curl
          source: |
            curl -H "accept: application/json" \
            -H "Content-Type: application/json" \
            -H "X-Origin-Request-Id: $(uuidgen)" \
            -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
            -u "<companyId>:<api_key>"
            -d '{ \
                "contentType": "image/jpeg"
              } \
            }' -X POST "https://api.uds.app/partner/v2/image-upload-url"
        - lang: PHP
          source: >
            $date = new DateTime();

            $url = "https://api.uds.app/partner/v2/image-upload-url";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Set request body


            $postData = json_encode(
              array(
                'contentType' => 'image/jpeg'
              )
            );


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'POST',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Content-Type: application/json\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM),
                    'content' => $postData,
                    'ignore_errors' => true
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='POST',
                url='https://api.uds.app/partner/v2/image-upload-url',
                body=json.dumps({
                  'contentType': 'image/jpeg'
                }),
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Content-Type': 'application/json',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/image-upload-url',
              'method': 'POST',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Content-Type': 'application/json',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const data = JSON.stringify({
              'contentType': 'image/jpeg'
            });

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {
                console.log(
                  JSON.parse(response)
                );
              });
            });

            req.write(data);
            req.end();
      requestBody:
        content:
          application/json:
            schema:
              required:
                - contentType
              properties:
                contentType:
                  type: string
                  description: Image file content type.
                  example: image/jpeg
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                properties:
                  imageId:
                    type: string
                    description: >-
                      Image identifier. This value has to be attached to goods
                      entity, see `/goods` methods
                  headers:
                    type: object
                    properties:
                      Content-Type:
                        type: array
                        description: Array of allowed content-types
                        items:
                          type: string
                          description: Allowed content-type
                          example: image/jpeg
                    description: Headers to include when uploading the image.
                  url:
                    type: string
                    description: Presigned upload url.
                  method:
                    type: string
                    description: Http method name.
                    example: PUT
                  expires:
                    type: number
                    description: Expiration time in epoch milliseconds.
                    example: 1632137293751
              example:
                imageId: >-
                  NTQ5NzU1ODIxNDg5L0dPT0RTLzdiYzBlNTU0LWMyNzMtNDc1MC05MjEyLWY0NWJhNWM1ODZiOQ==
                headers:
                  Content-Type:
                    - image/jpeg
                url: >-
                  https://s3.amazonaws.com/uds-goods/549755821489/GOODS/7bc0e554-c273-4750-9212-f45ba5c586b9?X-Amz-Expires=900
                method: PUT
                expires: 1632137293751
  /tags:
    get:
      tags:
        - Tags
      summary: List all tags
      x-codeSamples:
        - lang: curl
          source: |
            curl -H 'Accept: application/json' \
                 -H "X-Origin-Request-Id: $(uuidgen)" \
                 -H "X-Timestamp: $(date --iso-8601=seconds --utc)" \
                 -u "<companyId>:<api_key>"
                 -X GET -s https://api.uds.app/partner/v2/tags
        - lang: PHP
          source: >
            $date = new DateTime();

            $customerId = 123;

            $url = "https://api.uds.app/partner/v2/tags";

            $uuid_v4 = 'UUID'; //generate universally unique identifier version
            4 (RFC 4122)

            $companyId = 123; //set ID of your company

            $apiKey = 'ZDk1MmE5NzMtODcxNi00YzIwLTllZDMtN2ZjM2NjOGI2YTMz'; //set
            company apikey


            // Create a stream


            $opts = array(
                'http' => array(
                    'method' => 'GET',
                    'header' => "Accept: application/json\r\n" .
                                "Accept-Charset: utf-8\r\n" .
                                "Authorization: Basic ". base64_encode("$companyId:$apiKey")."\r\n" .
                                "X-Origin-Request-Id: ".$uuid_v4."\r\n" .
                                "X-Timestamp: ".$date->format(DateTime::ATOM)
                )
            );


            $context = stream_context_create($opts);

            $result = file_get_contents($url, false, $context);


            echo $result;
        - lang: Python
          source: |
            import json
            import uuid
            import base64
            from datetime import datetime
            from http.client import HTTPSConnection

            authString = base64.b64encode(b'<companyId>:<apiKey>')
            customerId = 123
            con = HTTPSConnection('api.uds.app')
            con.request(
                method='GET',
                url='/partner/v2/tags',
                headers={
                    'Accept': 'application/json',
                    'Accept-Charset': 'utf-8',
                    'Authorization': 'Basic ' + authString.decode("utf-8") ,
                    'X-Origin-Request-Id': str(uuid.uuid4()),
                    'X-Timestamp': datetime.now().isoformat(),
                })
            print (con.getresponse().read())
            con.close()
        - lang: Node
          source: |
            const https = require('https');
            const uuid = require('uuid4');
            const authString = '<companyId>' + ':' + '<apiKey>';
            const customerId = 123;

            const options = {
              'host': 'api.uds.app',
              'port': 443,
              'path': '/partner/v2/tags',
              'method': 'GET',
              'headers': {
                'Accept': 'application/json',
                'Accept-Charset': 'utf-8',
                'Authorization': 'Basic ' + Buffer.from(authString).toString('base64'),
                'X-Origin-Request-Id': uuid(),
                'X-Timestamp': new Date().toISOString()
              }
            };

            const req = https.request(options, function(res) {
              res.setEncoding('utf8');
              res.on('data', function (response) {

                console.log(
                  JSON.parse(response)
                );

              });
            });

            req.end();
      responses:
        '200':
          description: Company tags list
          content:
            application/json:
              schema:
                properties:
                  rows:
                    type: array
                    description: Company tags
                    items:
                      $ref: '#/components/schemas/TagModel'
                  total:
                    type: number
                    description: Total count of tags
              example:
                rows:
                  - id: 1
                    name: VIP
                  - id: 2
                    name: Promo 2024
                  - id: 3
                    name: Regular
                  - id: 7
                    name: Newsletter subscriber
                total: 4
      description: Retrieves the list of company tags.
components:
  securitySchemes:
    Basic:
      type: http
      scheme: basic
      description: >
        In order to call API methods partner applications require to
        authenticate requests with a [Basic
        Auth](https://en.wikipedia.org/wiki/Basic_access_authentication).


        To authorize requests clients MUST set base auth token value in
        `Authorization` http header.

        The auth token value is a string of `Basic <base64-encoded-string>`,
        where <base64-encoded-string> is a base64 encode of
        "<companyId>:<apiKey>"

        Create or get existed apiKey from [API Settings
        page](https://admin.uds.app/admin/integration).


        **Example:**


        ```bash

        curl -X GET -s https://api.uds.app/partner/v2/settings -H Authorization:
        Basic MTIzNDp0b2tlbg==

        ```


        where "MTIzNDp0b2tlbg==" is a base64 encode of "1234:token"


        **Attention:** *In order to protect your token against hacker attacks
        all requests use only HTTPS protocol.*
    Webhook:
      type: apiKey
      in: header
      name: X-Signature
      description: >
        In order to secure the request all webhook calls are signed by a
        signature.


        Signature calculation pseudo code:


        ```

        md5 ( concat ( X-RequestId, X-Timestamp, Client-Id, Api-Key ) )

        ```


        Where:

        * `md5` - is md5 hash function

        * `concat` - string concatenation

        * `X-RequestId` - value of `X-RequestId` http header

        * `X-Timestamp` - value of `X-Timestamp` http header

        * `Client-Id` - client id (or a company id)

        * `Api-Key` - same api key required to authenticate Partner API requests


        ### Example


        For example, partner has a client id equal to `123456` and api key equal
        to `ZWY5ZmI4ZjQtNTgxMC00M2M3LWE2YTYtZGVhMDRmZTAwNzQxCg==`.

        Then a typical webhook request would look like:


        ```

        curl -X POST https://webhook-server.com/api/evetns/operation \
          -H 'X-RequestId: bf7d19b0-8e3c-4d55-98ba-2783915957b3 \
          -H 'X-Timestamp: 2018-10-22T13:52:46,769Z' \
          -H 'X-Signature: 'dc8d4416d3e01a40fd10f1c7bf3f4754' \
          -d '{ ... }'  # body skipped for the sake of example simplicity
        ```


        Where `dc8d4416d3e01a40fd10f1c7bf3f4754` is a result of:


        ```

        $ echo -n
        'bf7d19b0-8e3c-4d55-98ba-2783915957b32018-10-22T13:52:46,769Z123456ZWY5ZmI4ZjQtNTgxMC00M2M3LWE2YTYtZGVhMDRmZTAwNzQxCg=='
        | md5sum

        dc8d4416d3e01a40fd10f1c7bf3f4754  -

        ```
  responses:
    NotFound:
      description: Entity not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
  parameters:
    id:
      name: id
      in: path
      description: Object ID.
      schema:
        type: integer
        format: int64
      required: true
    max:
      name: max
      in: query
      description: Limit results size.
      schema:
        type: integer
        default: 10
        maximum: 50
    offset:
      name: offset
      in: query
      description: Paginate results by given offset.
      schema:
        type: integer
        default: 0
        maximum: 10000
    cursor:
      name: cursor
      in: query
      description: Paginate results by cursor.
      schema:
        type: string
    externalId:
      name: externalId
      in: path
      description: Object external identifier.
      schema:
        type: string
      required: true
    x-request-id:
      name: X-Origin-Request-Id
      in: header
      description: Request identifier (UUID).
      required: true
      schema:
        type: string
    x-timestamp:
      name: X-Timestamp
      in: header
      description: Timestamp in ISO8601 date format.
      required: true
      schema:
        type: string
        format: date-time
    x-signature:
      name: X-Signature
      in: header
      description: Webhook request signature.
      required: true
      schema:
        type: string
  headers:
    X-Request-Id:
      description: Unique request identifier.
      schema:
        type: string
        format: uuid
    X-Timestamp:
      description: Request timestamp.
      schema:
        type: string
        format: date-time
  schemas:
    GeneralError:
      type: object
      description: General error.
      properties:
        errorCode:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: Error description.
      required:
        - errorCode
        - message
    ErrorCode:
      type: string
      description: Short code.
      enum:
        - notFound
        - badRequest
        - forbidden
    CompanySettings:
      type: object
      description: >
        Company loyalty program configuration. Contains discount policies,
        membership tiers,

        reward rates, and operational settings. Retrieved via GET /settings.
      required:
        - id
        - name
        - promoCode
        - marketingSettings
        - currency
        - baseDiscountPolicy
        - purchaseByPhone
        - usePointsByPhone
        - writeInvoice
        - slug
      properties:
        id:
          type: integer
          description: Company ID.
        name:
          type: string
          description: Company name.
        promoCode:
          type: string
          description: >-
            Company invitation promo code. Customers can use this code to join
            your loyalty program.
        currency:
          description: ISO-4217
          nullable: true
          type: string
        baseDiscountPolicy:
          type: string
          description: |
            Defines loyalty program type:

            * `APPLY_DISCOUNT` — apply a discount to an order;

            * `CHARGE_SCORES` base discount won't apply but customer will
            receive points award
              with the same base discount rate applied to `cash` part of purchase operation.
          enum:
            - APPLY_DISCOUNT
            - CHARGE_SCORES
        loyaltyProgramSettings:
          $ref: '#/components/schemas/LoyaltyProgramSettings'
        purchaseByPhone:
          type: boolean
          description: Permission to make purchases by phone number.
        usePointsByPhone:
          type: boolean
          description: Permission to spend points purchases by phone number.
        writeInvoice:
          type: boolean
          description: >-
            Necessity to indicate a bill number when performing transactions
            through UDS Cashier.
        slug:
          type: string
          description: Company slug for web page.
    LoyaltyProgramSettings:
      type: object
      description: >
        Loyalty program settings defining membership tiers, reward rates, and
        referral bonuses.

        Configured in [UDS
        Admin](https://admin.uds.app/admin/marketing/discount).
      required:
        - baseMembershipTier
        - membershipTiers
        - referralCashbackRates
        - cashierAward
        - referralReward
        - discountVip
        - receiptLimit
        - deferPointsForDays
      properties:
        baseMembershipTier:
          $ref: '#/components/schemas/MembershipTier'
        membershipTiers:
          type: array
          description: Status settings.
          items:
            $ref: '#/components/schemas/MembershipTier'
        referralCashbackRates:
          type: array
          description: Rewards for referrals (3 levels)
          items:
            type: number
        cashierAward:
          type: number
          nullable: true
          description: Cashier’s reward rate for the performed transaction.
        referralReward:
          type: number
          nullable: true
          description: Customer’s reward for an effective recommendation.
        receiptLimit:
          type: number
          nullable: true
          description: Maximum transaction amount that can be made through UDS Cashier.
        deferPointsForDays:
          type: number
          nullable: true
          description: >-
            Number of days before earned cashback points become available in the
            customer's balance. A value of 0 means points are available
            immediately.
        firstPurchasePoints:
          type: number
          nullable: true
          minimum: 0.01
          description: Number of points for the first purchase
    Customer:
      type: object
      description: >
        A customer enrolled in your company's loyalty program. Contains UDS
        profile information,

        current point balance, membership tier, and transaction statistics.
        Returned by list and search endpoints.
      properties:
        uid:
          type: string
          description: Customer ID in the UDS.
          nullable: true
        avatar:
          type: string
          description: Avatar URL.
          nullable: true
        displayName:
          type: string
          description: Customer name.
        gender:
          type: string
          nullable: true
          description: Gender.
          allOf:
            - $ref: '#/components/schemas/Gender'
        phone:
          type: string
          description: Participant phone number.
          nullable: true
        birthDate:
          type: string
          nullable: true
          format: date
          readOnly: true
          description: Customer birth date
        participant:
          $ref: '#/components/schemas/Participant'
        channelName:
          type: string
          description: Acquisition channel name
          nullable: true
        email:
          type: string
          description: Customer email
          nullable: true
    CustomerDetail:
      description: >-
        Detailed customer profile including loyalty program data and assigned
        tags. Extends the base Customer schema with tag information for customer
        segmentation.
      allOf:
        - $ref: '#/components/schemas/Customer'
        - type: object
          properties:
            tags:
              description: List of tags
              type: array
              nullable: false
              default: []
              items:
                $ref: '#/components/schemas/TagModel'
    PurchaseTokenAction:
      description: |
        Type of action associated with a customer's purchase token:
        * `PURCHASE` — standard purchase operation
        * `BONUS_ITEMS_PURCHASE` — purchase using bonus items
        * `GOODS_ORDER_COMPLETE` — completing a goods order
        * `CERTIFICATE` — certificate redemption
      type: string
      nullable: false
      enum:
        - PURCHASE
        - BONUS_ITEMS_PURCHASE
        - GOODS_ORDER_COMPLETE
        - CERTIFICATE
    MembershipTier:
      type: object
      description: >
        Membership tier (loyalty level) configuration. Defines the
        discount/cashback rate and

        automatic upgrade conditions based on spending or referral count.
      required:
        - name
        - rate
      properties:
        uid:
          type: string
          description: Tier ID.
          readOnly: true
        name:
          type: string
          description: Tier name.
        rate:
          type: number
          description: Tier rate.
          maximum: 100
          minimum: 0
        maxScoresDiscount:
          type: number
          nullable: true
          description: The maximum discount (in percentage) allowed when redeeming points.
        conditions:
          type: object
          description: Conditions to upgrade customer tiers automatically.
          properties:
            totalCashSpent:
              type: object
              description: Upgrade to tier when customer reaches target `cashSpent`.
              nullable: true
              properties:
                target:
                  type: number
                  description: Amount of cash spent.
            effectiveInvitedCount:
              type: object
              description: >-
                Upgrade to tier when customer reaches target
                `effectiveInvitedCount`.
              nullable: true
              properties:
                target:
                  type: integer
                  description: Amount of invited count.
    Gender:
      type: string
      nullable: true
      description: Customer's gender for personalization and marketing segmentation.
      enum:
        - MALE
        - FEMALE
        - NOT_SPECIFIED
    Participant:
      type: object
      description: >
        Customer's loyalty program details within your company — point balance,
        discount rates,

        transaction statistics, and membership tier. This is the core loyalty
        data for a customer.
      properties:
        id:
          type: integer
          format: int64
          nullable: true
          description: Participant ID.
        inviterId:
          type: integer
          format: int64
          nullable: true
          description: ID of the inviting participant.
        points:
          type: number
          description: >-
            Available loyalty points that the customer can redeem for discounts
            on future purchases.
        discountRate:
          type: number
          description: >-
            Current discount rate (percentage) based on the customer's
            membership tier. Applied to purchases when baseDiscountPolicy is
            APPLY_DISCOUNT.
        cashbackRate:
          type: number
          description: >-
            Current cashback rate (percentage) based on the customer's
            membership tier. Determines points earned per purchase when
            baseDiscountPolicy is CHARGE_SCORES.
        cashSpent:
          type: number
          description: >-
            Total amount the customer has paid in currency across all completed
            purchases (excluding point payments). Used for automatic membership
            tier upgrades based on spending thresholds.
        savedFunds:
          type: number
          description: >-
            Total amount the customer has saved through discounts, point
            redemptions, and certificates across all transactions.
        invitedCount:
          type: integer
          description: >-
            Total number of people this customer has invited to join the loyalty
            program via referral link.
        effectiveInvitedCount:
          type: integer
          description: >-
            Number of invited people who made at least one purchase (effective
            referrals). Used for membership tier upgrade conditions.
        operationsCount:
          type: integer
          description: Total number of completed purchase transactions by this customer.
        fullRefundsCount:
          type: integer
          description: Number of fully refunded transactions for this customer.
        note:
          type: string
          nullable: true
          description: Note.
        membershipTier:
          $ref: '#/components/schemas/MembershipTier'
        dateCreated:
          type: string
          nullable: true
          format: date-time
          readOnly: true
          description: Date and time when customer was registered in company.
        lastTransactionTime:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: Date and time when the customer made the last transaction.
        pointsExpireIn:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: Date and time when the customer's points will be expired.
    Operation:
      type: object
      description: >
        A completed loyalty transaction (purchase, refund, or reward). Contains
        transaction details,

        customer info, cashier info, and point movements. Uses discriminator on
        `action` field.
      required:
        - action
      discriminator:
        propertyName: action
        mapping:
          PURCHASE: '#/components/schemas/PurchaseOperation'
      properties:
        id:
          type: integer
          description: Transaction ID in the UDS database.
          format: int64
          readOnly: true
        dateCreated:
          type: string
          description: Transaction date.
          format: date-time
          readOnly: true
        action:
          $ref: '#/components/schemas/Action'
          description: Operation type.
        state:
          $ref: '#/components/schemas/ActionState'
        customer:
          allOf:
            - $ref: '#/components/schemas/CustomerShortInfo'
            - type: object
              properties:
                uid:
                  nullable: true
                  description: Customer ID in UDS (UID).
        cashier:
          allOf:
            - $ref: '#/components/schemas/CashierInfo'
            - nullable: true
        branch:
          allOf:
            - $ref: '#/components/schemas/BranchInfo'
            - nullable: true
        points:
          type: number
          description: |
            The amount of points which changed customer balance as a result of
            the operation.

            A negative value means write-off of bonus points and a positive
            value means point accrual.
        certificatePoints:
          type: number
          nullable: true
          description: Number of deducted certificate points.
        receiptNumber:
          type: string
          nullable: true
          description: Receipt number.
        origin:
          type: object
          description: Reference to origin operation (for operations in state REVERSAL).
          nullable: true
          properties:
            id:
              type: integer
              format: int64
              description: Origin transaction ID.
    VoucherInfo:
      description: >
        Voucher details returned after creating a voucher via POST
        /operations/voucher.

        Contains the code for printing on the receipt and QR code URLs for
        display.
      properties:
        code:
          type: string
          description: UDS voucher code
        qrCodeText:
          type: string
          description: UDS voucher info for qrcode
        qrCode128:
          type: string
          description: Link for generate qrcode image (size 128)
        qrCode256:
          type: string
          description: Link for generate qrcode image (size 256)
        expiresIn:
          type: string
          format: date-time
          description: Voucher code expires in
        points:
          type: number
          description: Minimum points for withdrawal
    CreateVoucher:
      type: object
      required:
        - receipt
      properties:
        nonce:
          type: string
          nullable: true
          description: Nonce for voucher (UUID)
        cashier:
          type: object
          nullable: true
          description: Cashier information.
          properties:
            externalId:
              type: string
              description: Cashier identifier.
            name:
              type: string
              nullable: true
              description: Cashier name.
        receipt:
          type: object
          description: Receipt information.
          required:
            - total
            - cash
            - points
          properties:
            total:
              type: number
              description: Total receipt amount (in currency units).
            number:
              type: string
              nullable: true
              description: Receipt number.
            skipLoyaltyTotal:
              type: number
              nullable: true
              description: >-
                A part of the bill amount for which cashback is not credited and
                to which the discount does not apply (in currency units).
    CreateOperation:
      type: object
      description: >
        Request body for creating a purchase operation. Identify the customer
        via promo code, UID,

        or phone number. The `receipt.cash` value must come from POST
        /operations/calc — do not

        calculate it manually.
      required:
        - receipt
      properties:
        code:
          type: string
          nullable: true
          description: UDS promo-code.
        participant:
          type: object
          nullable: true
          description: Customer information.
          properties:
            uid:
              type: string
              nullable: true
              description: Customer ID in the UDS.
            phone:
              type: string
              nullable: true
              description: Customer phone number.
        nonce:
          type: string
          nullable: true
          description: Nonce for operation (UUID)
        cashier:
          type: object
          nullable: true
          description: Cashier information.
          properties:
            externalId:
              type: string
              description: Cashier identifier.
            name:
              type: string
              nullable: true
              description: Cashier name.
        receipt:
          type: object
          description: Receipt information.
          required:
            - total
            - cash
            - points
          properties:
            total:
              type: number
              description: Total receipt amount (in currency units).
            cash:
              type: number
              description: Payment amount (in currency units).
            points:
              type: number
              description: Points amount.
            number:
              type: string
              nullable: true
              description: Receipt number.
            skipLoyaltyTotal:
              type: number
              nullable: true
              description: >-
                A part of the bill amount for which cashback is not credited and
                to which the discount does not apply (in currency units).
            unredeemableTotal:
              type: number
              nullable: true
              description: A part of total that cannot be redeemed with points
        tags:
          type: array
          nullable: true
          description: 'List of tag ids to be set to customer, null means no changes'
          items:
            $ref: '#/components/schemas/TagId'
        items:
          type: array
          nullable: true
          description: List of receipt line items (products/services).
          items:
            $ref: '#/components/schemas/OperationItem'
    OperationItem:
      type: object
      description: A single line item in the receipt.
      required:
        - price
        - qty
      properties:
        itemId:
          type: string
          nullable: true
          maxLength: 256
          description: Item identifier.
        itemCode:
          type: string
          nullable: true
          minLength: 2
          maxLength: 256
          description: Item code.
        type:
          type: string
          nullable: true
          maxLength: 256
          description: 'Item type (e.g. "product", "service").'
        name:
          type: string
          nullable: true
          maxLength: 256
          description: Item name.
        measure:
          type: string
          nullable: true
          minLength: 2
          maxLength: 256
          description: 'Unit of measure (e.g. "pcs", "kg", "litre").'
        vatCode:
          type: string
          nullable: true
          minLength: 2
          maxLength: 256
          description: 'VAT code (e.g. "vat20", "vat10", "vat0").'
        price:
          type: number
          minimum: 0.01
          description: Unit price (in currency units).
        discountPrice:
          type: number
          nullable: true
          minimum: 0.01
          description: >-
            Discounted unit price (in currency units). If set, this price is
            used instead of `price`.
        qty:
          type: number
          minimum: 0.01
          description: Quantity.
        sku:
          type: string
          nullable: true
          minLength: 2
          maxLength: 256
          description: Stock keeping unit.
        isAlcohol:
          type: boolean
          nullable: true
          description: Whether the item is an alcohol product.
        isTobacco:
          type: boolean
          nullable: true
          description: Whether the item is a tobacco product.
        excise:
          type: number
          nullable: true
          description: Excise tax amount.
        classificationCode:
          type: string
          nullable: true
          minLength: 2
          maxLength: 256
          description: Item classification code.
        modifiers:
          type: array
          nullable: true
          description: Item modifiers as a list of key-value pairs.
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
        attributes:
          type: object
          nullable: true
          description: Arbitrary key-value attributes for the item.
          additionalProperties:
            type: string
    PurchaseCalcRequest:
      description: >
        Request body for calculating purchase discounts and cashback. Provide
        the customer identifier

        (code, uid, or phone) and receipt total to receive the loyalty
        calculation.
      type: object
      required:
        - receipt
      properties:
        code:
          type: string
          nullable: true
          description: UDS promo-code.
        participant:
          type: object
          nullable: true
          description: Customer information.
          properties:
            uid:
              type: string
              nullable: true
              description: Customer ID in the UDS.
            phone:
              type: string
              nullable: true
              description: Customer phone number.
        receipt:
          type: object
          description: Receipt information.
          required:
            - total
          properties:
            total:
              type: number
              description: Total receipt amount (in currency units).
            skipLoyaltyTotal:
              type: number
              description: >-
                A part of the bill amount for which cashback is not credited and
                to which the discount does not apply (in currency units).
            unredeemableTotal:
              type: number
              description: A part of total that cannot be redeemed with points
            points:
              type: number
              description: |
                Desired points to withdraw. Not required, would be max possible
                if not specified.
    PurchaseCalcResponse:
      type: object
      required:
        - user
        - purchase
      properties:
        user:
          $ref: '#/components/schemas/CustomerDetail'
        purchase:
          $ref: '#/components/schemas/PurchaseCalc'
    PurchaseCalc:
      type: object
      description: >
        Loyalty program calculation result for a purchase. Shows discount
        amounts, point values,

        final cash payment, and projected cashback. All monetary values are in
        company currency units.
      properties:
        maxPoints:
          type: number
          description: >-
            Maximum number of loyalty points the customer can redeem for this
            purchase, considering their balance and tier limits.
        total:
          type: number
          description: >-
            Original purchase total before any loyalty benefits are applied (in
            currency units).
        skipLoyaltyTotal:
          type: number
          description: >-
            Portion of the purchase total excluded from loyalty program benefits
            — no discount applied, no cashback earned (e.g., alcohol, tobacco,
            gift cards). In currency units.
        unredeemableTotal:
          type: number
          description: >-
            Portion of the purchase total that cannot be paid with loyalty
            points (in currency units).
        discountAmount:
          description: >-
            Discount amount in currency units. Only applicable when
            baseDiscountPolicy is APPLY_DISCOUNT.
          type: number
        discountPercent:
          description: >-
            Discount as a percentage of the total. Only applicable when
            baseDiscountPolicy is APPLY_DISCOUNT.
          type: number
        points:
          type: number
          description: >-
            Number of loyalty points being redeemed (deducted from customer
            balance) for this purchase.
        pointsPercent:
          description: Points redemption as a percentage of the total purchase amount.
          type: number
        netDiscount:
          description: >-
            Total combined discount from both loyalty discount and point
            redemption (in currency units).
          type: number
        netDiscountPercent:
          description: >-
            Total combined discount as a percentage (loyalty discount + point
            redemption).
          type: number
        certificatePoints:
          description: >-
            Number of certificate points deducted (separate from regular loyalty
            points).
          type: number
        cash:
          type: number
          description: >-
            Final amount the customer pays in currency after all discounts and
            point redemptions. Use this value in POST /operations.
        cashTotal:
          type: number
          description: >-
            Total amount to be paid including extra charges like delivery fees
            (in currency units).
        cashBack:
          type: number
          description: >-
            Loyalty points the customer will earn from this purchase. Applied
            after operation is completed (may be deferred by deferPointsForDays
            setting).
        extras:
          type: object
          description: >-
            Additional payments will not be taken into account by the loyalty
            program.
          properties:
            delivery:
              type: number
              description: Delivery cost (in currency units).
        maxScoresDiscount:
          type: number
          description: The maximum discount (in percentage) allowed when redeeming points.
    Action:
      type: string
      description: Transaction type.
      enum:
        - PURCHASE
    ActionState:
      type: string
      description: >
        Transaction lifecycle status:

        * `NORMAL` — active transaction, loyalty benefits applied

        * `CANCELED` — transaction was canceled, no loyalty impact

        * `REVERSAL` — transaction was refunded, loyalty benefits reversed
        (points returned, cashback deducted)
      enum:
        - NORMAL
        - CANCELED
        - REVERSAL
    PurchaseOperation:
      allOf:
        - $ref: '#/components/schemas/Operation'
        - type: object
          properties:
            total:
              type: number
              description: Receipt total amount (in currency units).
            cash:
              type: number
              description: Payment amount (in currency units).
      description: Customer ID in UDS (UID).
    Reference:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Identifier.
        displayName:
          type: string
          description: Name.
    CashierInfo:
      type: object
      description: Cashier information.
      properties:
        id:
          type: integer
          format: int64
          description: Cashier ID.
        displayName:
          type: string
          description: Cashier name.
    ParticipantShortInfo:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Customer ID in the company.
        displayName:
          type: string
          description: Customer name.
    BranchInfo:
      type: object
      description: Branch information.
      properties:
        id:
          type: integer
          format: int64
          description: Branch ID.
        displayName:
          type: string
          description: Branch name.
    GoodsInfoType:
      type: object
      description: >-
        Product catalog item — can be a category, a simple item, or an item with
        variants (VARYING_ITEM).
      required:
        - name
        - data
      properties:
        id:
          type: integer
          readOnly: true
          description: Goods ID.
        name:
          type: string
          description: Goods name.
        data:
          $ref: '#/components/schemas/GoodsData'
        hidden:
          type: boolean
          description: Is the goods hidden.
        blocked:
          type: boolean
          description: Is the goods blocked.
          readOnly: true
        nodeId:
          type: integer
          nullable: true
          description: ID of the category in which the product is included
        imageUrls:
          description: Array of imageId from presigned url response
          type: array
          nullable: false
          readOnly: true
          items:
            type: string
            nullable: false
        externalId:
          type: string
          nullable: true
          description: External goods identifier.
        dateCreated:
          type: string
          format: date-time
          readOnly: true
          description: Date item created.
    GoodsDetailed:
      description: Goods properties.
      required:
        - name
        - data
      properties:
        id:
          type: integer
          readOnly: true
          description: Goods ID.
        name:
          type: string
          description: Goods name.
        nodeId:
          type: integer
          nullable: true
          description: ID of the category in which the item is included.
        externalId:
          type: string
          nullable: true
          description: External goods identifier.
        dateCreated:
          type: string
          format: date-time
          readOnly: true
          description: Date item created.
        data:
          $ref: '#/components/schemas/GoodsData'
        hidden:
          type: boolean
          nullable: true
          description: Is the goods hidden.
        blocked:
          type: boolean
          nullable: true
          readOnly: true
          description: Is the goods blocked.
        imageUrls:
          description: Array of imageId from presigned url response
          type: array
          nullable: false
          readOnly: true
          items:
            type: string
            nullable: false
    GoodsData:
      type: object
      description: |
        Product type-specific properties. Uses discriminator on `type` field:
        CATEGORY — a folder for organizing items,
        ITEM — a simple product with price and inventory,
        VARYING_ITEM — a product with multiple variants (e.g., sizes, colors).
      oneOf:
        - $ref: '#/components/schemas/GoodsCategoryType'
        - $ref: '#/components/schemas/GoodsItemType'
        - $ref: '#/components/schemas/GoodsVaryingItemType'
      discriminator:
        propertyName: type
        mapping:
          CATEGORY: '#/components/schemas/GoodsCategoryType'
          ITEM: '#/components/schemas/GoodsItemType'
          VARYING_ITEM: '#/components/schemas/GoodsVaryingItemType'
    GoodsCategoryType:
      type: object
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/GoodsType'
    GoodsItemType:
      type: object
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/GoodsType'
        sku:
          type: string
          nullable: true
          description: Item stock number.
        price:
          type: number
          description: Item price.
        description:
          type: string
          nullable: true
          description: Item description.
        offer:
          allOf:
            - $ref: '#/components/schemas/GoodsOffer'
            - nullable: true
        inventory:
          $ref: '#/components/schemas/GoodsInventory'
        photos:
          $ref: '#/components/schemas/GoodsPhotos'
        measurement:
          $ref: '#/components/schemas/GoodsMeasurement'
        increment:
          type: number
          nullable: true
          description: >-
            Amount of the item that the buyer can increase or decrease by 1
            interval
        minQuantity:
          type: number
          nullable: true
          description: Minimal quantity of item for order
        vatCode:
          allOf:
            - $ref: '#/components/schemas/VatCode'
            - nullable: true
        paymentSubject:
          allOf:
            - $ref: '#/components/schemas/PaymentSubject'
            - nullable: true
    GoodsVaryingItemType:
      type: object
      description: >-
        A product with multiple variants (e.g., sizes, colors, flavors). Each
        variant has its own name, price, and inventory.
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/GoodsType'
        variants:
          type: array
          description: Variants of item.
          items:
            allOf:
              - $ref: '#/components/schemas/GoodsVariantType'
        description:
          type: string
          nullable: true
          description: Variant description.
        photos:
          $ref: '#/components/schemas/GoodsPhotos'
        vatCode:
          allOf:
            - $ref: '#/components/schemas/VatCode'
            - nullable: true
        paymentSubject:
          allOf:
            - $ref: '#/components/schemas/PaymentSubject'
            - nullable: true
    GoodsVariantType:
      properties:
        name:
          type: string
          description: Variant name.
        sku:
          type: string
          nullable: true
          description: Variant stock number.
        price:
          type: number
          description: Variant price.
        offer:
          allOf:
            - $ref: '#/components/schemas/GoodsOffer'
            - nullable: true
        inventory:
          $ref: '#/components/schemas/GoodsInventory'
    GoodsOffer:
      type: object
      description: Promotional information.
      properties:
        offerPrice:
          type: number
          nullable: true
          description: Discount price.
        skipLoyalty:
          type: boolean
          description: >-
            Flag of goods item price which cashback is not credited and to which
            the discount does not apply (in currency units).
    GoodsInventory:
      type: object
      nullable: true
      description: Item quantity in stock.
      properties:
        inStock:
          type: integer
          description: Item quantity in stock. The "null" value means unlimited quantity.
          nullable: true
    GoodsType:
      type: string
      enum:
        - CATEGORY
        - ITEM
        - VARYING_ITEM
    GoodsPhotos:
      type: array
      nullable: false
      description: Array of image identifiers
      items:
        type: string
        description: Base64 encoded photo path
    GoodsOrderDetailed:
      type: object
      description: >
        Detailed goods order from the UDS marketplace. Contains order items,
        delivery info,

        payment method, loyalty calculation, and processing status.
      properties:
        id:
          type: integer
          description: Order ID.
        dateCreated:
          type: string
          format: date-time
          description: Order date.
        comment:
          type: string
          nullable: true
          description: Comment on the order.
        state:
          $ref: '#/components/schemas/GoodsOrderState'
          description: Order status.
        orderStatus:
          nullable: true
          description: Order processing status
          allOf:
            - $ref: '#/components/schemas/GoodsOrderUpdateStatus'
        cash:
          type: number
          description: Amount payable in currency units.
        points:
          type: number
          description: Number of deducted points.
        total:
          type: number
          description: Total order amount.
        certificatePoints:
          type: number
          description: Number of deducted certificate points.
        customer:
          $ref: '#/components/schemas/CustomerShortInfo'
        delivery:
          $ref: '#/components/schemas/DeliveryType'
        onlinePayment:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/OnlinePayment'
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethod'
        items:
          type: array
          description: Items information.
          items:
            allOf:
              - $ref: '#/components/schemas/GoodsOrderItem'
        purchase:
          type: object
          nullable: false
          allOf:
            - $ref: '#/components/schemas/PurchaseCalc'
        externalOrder:
          type: object
          nullable: true
          properties:
            id:
              type: string
              nullable: true
              description: external order id
            link:
              type: string
              nullable: false
              description: external order link
    GoodsOrderUpdate:
      type: object
      properties:
        deliveryCase:
          $ref: '#/components/schemas/DeliveryCase'
        items:
          type: array
          description: Items information.
          items:
            oneOf:
              - $ref: '#/components/schemas/GoodsOrderItemUpdate'
              - $ref: '#/components/schemas/GoodsOrderItemNew'
    GoodsOrderItemUpdate:
      type: object
      properties:
        id:
          type: integer
          description: Item ID in the UDS.
        variantName:
          type: string
          description: Name of goods variant if this goods type is VARYING_ITEM.
        qty:
          type: integer
          description: Quantity.
    GoodsOrderItemNew:
      type: object
      properties:
        externalId:
          type: string
          description: External item identifier.
        name:
          type: string
          description: Goods name.
        variantName:
          type: string
          description: Name of goods variant if this goods type is VARYING_ITEM
        qty:
          type: integer
          description: Quantity.
        price:
          type: number
          description: Item price.
        skipLoyalty:
          type: boolean
          default: false
          description: Don’t apply loyalty program terms.
    OnlinePayment:
      type: object
      nullable: true
      description: Online payment information.
      properties:
        paymentProvider:
          type: string
          description: Payment provider type.
          enum:
            - B2P
            - CLOUD_PAYMENTS
            - YOOKASSA
            - PAYTURE
            - CUSTOM
        id:
          type: string
          description: Payment identifier in external payment system.
        completed:
          type: boolean
          description: Payment status.
    PaymentMethod:
      type: object
      description: Payment information.
      properties:
        type:
          type: string
          description: Payment type.
          enum:
            - BEST_TO_PAY
            - CLOUD_PAYMENTS
            - CASH
            - MANUAL
            - CUSTOM
        name:
          type: string
          description: Manual type name.
          nullable: true
        online:
          type: boolean
          description: Is payment online.
        providerType:
          type: string
          description: Payment provider type.
          nullable: true
    GoodsOrderItem:
      type: object
      description: Item information.
      properties:
        id:
          type: integer
          description: Item ID.
        externalId:
          type: string
          nullable: true
          description: External item identifier.
        name:
          type: string
          description: Goods name.
        variantName:
          type: string
          nullable: true
          description: Name of goods variant if this goods type is VARYING_ITEM.
        sku:
          type: string
          nullable: true
          description: Item stock number.
        type:
          type: string
          description: Item type.
          enum:
            - ITEM
            - VARYING_ITEM
        qty:
          type: integer
          description: Quantity.
        price:
          type: number
          description: Item price.
        offerPrice:
          type: number
          nullable: true
          description: Discount price.
        skipLoyalty:
          type: boolean
          default: false
          description: Don’t apply loyalty program terms.
        measurement:
          $ref: '#/components/schemas/GoodsMeasurement'
        dataMatrixCodes:
          type: array
          nullable: true
          description: Data matrix codes (Честный знак) for the item.
          items:
            type: string
        deliveryState:
          $ref: '#/components/schemas/DeliveryState'
    DeliveryState:
      type: object
      nullable: true
      readOnly: true
      description: Delivery state of the order item.
      properties:
        deliveredQty:
          type: number
          description: Quantity of delivered items.
        canceledQty:
          type: number
          description: Quantity of canceled items.
    DeliveryType:
      type: object
      description: Method of receiving the order.
      oneOf:
        - $ref: '#/components/schemas/Pickup'
        - $ref: '#/components/schemas/Delivery'
      discriminator:
        propertyName: type
        mapping:
          PICKUP: '#/components/schemas/Pickup'
          DELIVERY: '#/components/schemas/Delivery'
    ReceiverInfo:
      type: object
      description: Receiver information.
      properties:
        receiverName:
          type: string
          description: Name of the customer who will pick up the order.
        receiverPhone:
          type: string
          description: Phone number of the customer who will pick up the order.
        userComment:
          type: string
          nullable: true
          description: Customer comment on the order.
    DeliveryTypes:
      type: string
      description: Type of receiving the order.
      enum:
        - PICKUP
        - DELIVERY
    Pickup:
      type: object
      description: Pickup of the order.
      required:
        - type
      allOf:
        - $ref: '#/components/schemas/ReceiverInfo'
        - type: object
          properties:
            branch:
              $ref: '#/components/schemas/BranchInfo'
            type:
              $ref: '#/components/schemas/DeliveryTypes'
    Delivery:
      type: object
      description: Order delivery.
      required:
        - type
      allOf:
        - $ref: '#/components/schemas/ReceiverInfo'
        - type: object
          properties:
            deliveryCase:
              $ref: '#/components/schemas/DeliveryCase'
            address:
              type: string
              nullable: true
              description: Delivery address.
            type:
              $ref: '#/components/schemas/DeliveryTypes'
    DeliveryCase:
      properties:
        name:
          type: string
          description: Delivery name.
          example: zone A
        value:
          type: number
          description: Cost of delivery.
          example: 0.1
      description: Delivery information.
    CustomerShortInfo:
      type: object
      description: Customer information.
      allOf:
        - $ref: '#/components/schemas/ParticipantShortInfo'
        - properties:
            uid:
              type: string
              description: Customer UID in the UDS.
            membershipTier:
              $ref: '#/components/schemas/MembershipTier'
    GoodsOrderState:
      type: string
      description: |
        Order lifecycle status:
        * `NEW` — order just created, awaiting processing
        * `COMPLETED` — order fulfilled and transaction created
        * `DELETED` — order canceled
        * `WAITING_PAYMENT` — awaiting online payment confirmation
        * `NEED_ACK` — order requires merchant acknowledgment
      enum:
        - NEW
        - COMPLETED
        - DELETED
        - WAITING_PAYMENT
        - NEED_ACK
    GoodsOrderUpdateStatus:
      type: string
      description: |
        Order processing status set by the merchant:
        * `ACCEPTED` — merchant has accepted the order and is preparing it
        * `READY` — order is ready for pickup or delivery
      enum:
        - ACCEPTED
        - READY
    GoodsMeasurement:
      type: string
      description: Goods measurement.
      enum:
        - PIECE
        - CENTIMETRE
        - METRE
        - MILLILITRE
        - LITRE
        - GRAM
        - KILOGRAM
        - TON
        - SQUARE_METRE
        - CUBIC_METRE
        - DAY
        - HOUR
        - MINUTE
        - KILOMETRE
    VatCode:
      type: string
      description: VAT rate codes
      enum:
        - NO_NDS
        - NDS_0
        - NDS_10
        - NDS_20
        - NDS_10_110
        - NDS_20_120
    PaymentSubject:
      type: string
      description: |
        Payment item attribute:
        * COMMODITY - Commodity
        * EXCISE - Excise
        * SERVICE - Service
      enum:
        - COMMODITY
        - EXCISE
        - SERVICE
    TaxSystemCode:
      type: string
      description: |
        Tax system codes
        * OSN - General taxation system
        * USN_INCOME - Simplified (USN, income)
        * USN_INCOME_EXPENSES - Simplified (USN, income minus expenses)
        * ENVD - A single tax on imputed income (ENVD)
        * ESN - Unified agricultural tax (ESN)
        * PSN - Patent tax system
      enum:
        - OSN
        - USN_INCOME
        - USN_INCOME_EXPENSES
        - ENVD
        - ESN
        - PSN
    TagId:
      type: integer
      format: int64
      example: 1
      description: Tag identifier
    TagModel:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/TagId'
        name:
          description: Tag name
          type: string
      description: Tag.
    ExternalInfoUpdateModel:
      type: object
      properties:
        link:
          type: string
          nullable: true
          description: external order link
          example: 'https://www.ozon.ru/my/orderdetails/?order=00099999-04011'
        orderId:
          type: string
          description: 'external order id, regex `^(\w|-|\+)+$`'
          minLength: 1
          maxLength: 256
