openapi: 3.1.0
info:
  description: >
    The Private Portal API provides access to your Portal information. For the
    moment this covers Trade data, as well as Trade deliveries and their
    associated documents.  


    Trades represent the agreement reached at the end of a negotiation between
    buyer and seller. Trades typically reference one or more Trade deliveries.
    They are the equivalent of a purchase order in your ERP.  


    Within a Trade, the number of items in productTerms and deliveries can vary
    depending on deliveryType:

    - `SINGLE_PRODUCT`: productTerms contains exactly 1 item, deliveries can
    contain 1 or more items.

    - `CALL_OFF`: productTerms contains exactly 1 item, deliveries can contain 0
    or more items. Their number is expected to grow as more deliveries are
    called off.

    - `COMBINED_SHIPMENT`: productTerms contains 1 or more items, deliveries
    contains exactly 1 item.


    When polling the API you should filter by lastUpdate. Since users can freely
    edit Trades and add/edit Trade deliveries, the UI provides a readyToSync
    flag, which you can filter by. These Trades and Trade deliveries should have
    all the necessary ERP fields filled in.

    ## Trace headers

    In addition to the standard headers that you would expect, each response
    contains 2 specific headers. When asking for support, please provide them as
    reference if possible:


    | Header             |
    Description                                                                          
    |

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

    | `X-Trace-Id`       | Trace identifier used to track each request against
    internal logs                     |

    | `X-Server-Version` | Version of the server that
    responded                                                  |


    ## Errors

    Kemiex uses conventional HTTP response codes to indicate the success or
    failure of an API request. In general: Codes in the `2xx` range indicate
    success. Codes in the `4xx` range indicate an error that failed given the
    information provided. Codes in the `5xx` range indicate an error with
    Kemiex’s servers.


    Unsuccessful responses contain 2 parts: an error code, and user-friendly
    message describing the issue. You can expect the following errors, though
    more may be added in the future:


    | <div style="min-width: 315px;">Error Code</div> |
    Description                                                                                                                        
    |

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

    | `BAD_REQUEST_RESOURCE_NOT_FOUND`         | Client-side error: the URL
    address is
    wrong                                                                                               
    |

    | `BAD_REQUEST_METHOD_NOT_SUPPORTED`       | Client-side error: the HTTP
    method used in the request is not supported by the
    endpoint                                                    |

    | `BAD_REQUEST_MISSING_REQUIRED_PARAMETER` | Client-side error: at least one
    of the required parameters is not
    provided                                                                 |

    | `BAD_REQUEST_PARAMETER_TYPE_MISMATCH`    | Client-side error: a parameter
    value does not match its expected
    type                                                                      |

    | `BAD_REQUEST_PARAMETER_VALUE_ILLEGAL`    | Client-side error: a parameter
    value is outside the range of values
    allowed                                                                |

    | `BAD_REQUEST`                            | General client-side error: The
    request cannot be processed. This is a catch-all error thrown when the
    errors above do not apply            |

    | `FORBIDDEN`                              | The API key is not provided, or
    the provided value is incorrect, or the associated account does not have
    access to the requested resource  |

    | `INTERNAL_SERVER_ERROR`                  | An unexpected condition was
    encountered on the
    server                                                                                     
    |
  title: Private Portal API
  version: 1.0.0
servers:
  - url: https://api.kemiex.com
    description: Production API
tags:
  - name: Trades
    description: Trade-related operations
  - name: Trade deliveries
    description: Operations related to trade deliveries
  - name: Files
    description: File-related operations
paths:
  /pp/v1/trades:
    get:
      tags:
        - Trades
      summary: List all trades
      description: >-
        Returns a list of Trades, ordered by lastUpdated descending. Trades
        include only limited information. Use the UUID value to perform a full
        entity retrieval.
      operationId: getTradeList
      parameters:
        - name: lastUpdateFrom
          in: query
          description: >-
            Only return items items updated after the given date/time (ISO 8601
            format).
          required: true
          schema:
            type: string
            format: date-time
          examples:
            Timestamp with timezone offset:
              description: Timestamp in UTC+1 timezone.
              value: '2024-11-23T21:15:30+01:00'
            Timestamp in UTC/Zulu timezone:
              description: Timestamp in Zulu timezone
              value: '2024-11-23T20:15:30Z'
        - name: lastUpdateTo
          in: query
          description: >-
            Only return items items updated before the given date/time (ISO 8601
            format). If omitted, the current date/time is implied
          required: false
          schema:
            type: string
            format: date-time
          examples:
            Timestamp with timezone offset:
              description: Timestamp in UTC+1 timezone.
              value: '2024-11-23T21:15:30+01:00'
            Timestamp in UTC/Zulu timezone:
              description: Timestamp in Zulu timezone
              value: '2024-11-23T20:15:30Z'
        - name: readyToSync
          in: query
          description: >-
            Only return Trades that are ready to sync. These Trades have at
            least one delivery marked as ERP ready.
          required: false
          schema:
            type: boolean
          example: true
        - name: page
          in: query
          description: The page number to retrieve. Starts from 1.
          required: false
          schema:
            type: integer
            format: int32
            default: 1
            minimum: 1
          example: 1
        - name: pageSize
          in: query
          description: The number of items to return per page.
          required: false
          schema:
            type: integer
            format: int32
            default: 100
            maximum: 500
            minimum: 1
          example: 50
      responses:
        '200':
          description: OK
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageTradeListing'
        '400':
          description: Bad Request
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad Request Example:
                  summary: Example of a 400 Bad Request error
                  description: Bad Request Example
                  value:
                    errorCode: BAD_REQUEST_MISSING_REQUIRED_PARAMETER
                    errorMessage: >-
                      Required request parameter 'lastUpdateFrom' for method
                      parameter type OffsetDateTime is not present
        '403':
          description: Forbidden
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Forbidden Example:
                  summary: Example of a 403 Forbidden response
                  description: Forbidden Example
                  value:
                    errorCode: FORBIDDEN
                    errorMessage: >-
                      Access denied. Please ensure your API key is correctly
                      provided and that your account has access to the requested
                      resource.
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Internal Server Error Example:
                  summary: Example of a 500 Internal Server Error
                  description: Internal Server Error Example
                  value:
                    errorCode: INTERNAL_SERVER_ERROR
                    errorMessage: An unexpected error occurred.
      security:
        - apiKey: []
  /pp/v1/trades/{tradeUuid}:
    get:
      tags:
        - Trades
      summary: Retrieve a Trade
      description: 'Returns a Trade object.  '
      operationId: getTrade
      parameters:
        - name: tradeUuid
          in: path
          description: The universal unique identifier of the desired trade
          required: true
          schema:
            type: string
            format: uuid
          example: b43dd825-8a99-4676-aae7-9b91817c2c3c
      responses:
        '200':
          description: OK
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trade'
        '400':
          description: Bad Request
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad Request Example:
                  summary: Example of a 400 Bad Request error
                  description: Bad Request Example
                  value:
                    errorCode: BAD_REQUEST_PARAMETER_TYPE_MISMATCH
                    errorMessage: >-
                      Cannot convert value 'abc' to required type
                      'java.util.UUID' for parameter 'tradeUuid'
        '403':
          description: Forbidden
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Forbidden Example:
                  summary: Example of a 403 Forbidden response
                  description: Forbidden Example
                  value:
                    errorCode: FORBIDDEN
                    errorMessage: >-
                      Access denied. Please ensure your API key is correctly
                      provided and that your account has access to the requested
                      resource.
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Internal Server Error Example:
                  summary: Example of a 500 Internal Server Error
                  description: Internal Server Error Example
                  value:
                    errorCode: INTERNAL_SERVER_ERROR
                    errorMessage: An unexpected error occurred.
      security:
        - apiKey: []
  /pp/v1/files/{fileUuid}:
    get:
      tags:
        - Files
      summary: Retrieve a File
      description: >-
        Returns the download URL of a file uploaded on a Trade or Trade
        delivery.
      operationId: downloadFile
      parameters:
        - name: fileUuid
          in: path
          description: The universal unique identifier of the file
          required: true
          schema:
            type: string
            format: uuid
          example: b43dd825-8a99-4676-aae7-9b91817c2c3c
      responses:
        '200':
          description: OK
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileContent'
        '400':
          description: Bad Request
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad Request Example:
                  summary: Example of a 400 Bad Request error
                  description: Bad Request Example
                  value:
                    errorCode: BAD_REQUEST_PARAMETER_TYPE_MISMATCH
                    errorMessage: >-
                      Cannot convert value 'abc' to required type
                      'java.util.UUID' for parameter 'fileUuid'
        '403':
          description: Forbidden
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Forbidden Example:
                  summary: Example of a 403 Forbidden response
                  description: Forbidden Example
                  value:
                    errorCode: FORBIDDEN
                    errorMessage: >-
                      Access denied. Please ensure your API key is correctly
                      provided and that your account has access to the requested
                      resource.
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Internal Server Error Example:
                  summary: Example of a 500 Internal Server Error
                  description: Internal Server Error Example
                  value:
                    errorCode: INTERNAL_SERVER_ERROR
                    error: An unexpected error occurred.
      security:
        - apiKey: []
  /pp/v1/deliveries:
    get:
      tags:
        - Trade deliveries
      summary: List all Trade deliveries
      description: >-
        Returns a list of Trade Deliveries, ordered by lastUpdated descending.
        Trade deliveries include only limited information. Use the UUID value to
        perform a full entity retrieval.
      operationId: getTradeDeliveryList
      parameters:
        - name: lastUpdateFrom
          in: query
          description: >-
            Only return items updated after the given date/time (ISO 8601
            format).
          required: true
          schema:
            type: string
            format: date-time
          examples:
            Timestamp with timezone offset:
              description: Timestamp in UTC+1 timezone.
              value: '2024-11-23T21:15:30+01:00'
            Timestamp in UTC/Zulu timezone:
              description: Timestamp in Zulu timezone
              value: '2024-11-23T20:15:30Z'
        - name: lastUpdateTo
          in: query
          description: >-
            Only return items items updated before the given date/time (ISO 8601
            format). If omitted, thecurrent date/time is implied.
          required: false
          schema:
            type: string
            format: date-time
          examples:
            Timestamp with timezone offset:
              description: Timestamp in UTC+1 timezone.
              value: '2024-11-23T21:15:30+01:00'
            Timestamp in UTC/Zulu timezone:
              description: Timestamp in Zulu timezone
              value: '2024-11-23T20:15:30Z'
        - name: readyToSync
          in: query
          description: >-
            Only return Trade deliveries that are marked as Ready to sync into
            ERP.
          required: false
          schema:
            type: boolean
          example: true
        - name: page
          in: query
          description: Desired page number of results. First page is 1.
          required: false
          schema:
            type: integer
            format: int32
            default: 1
            minimum: 1
          example: 1
        - name: pageSize
          in: query
          description: >-
            Maximum number of results that should be returned per page. Please
            keep it constant for requests across multiple pages, in order to
            correctly receive all results.
          required: false
          schema:
            type: integer
            format: int32
            default: 100
            maximum: 500
            minimum: 1
          example: 50
      responses:
        '200':
          description: OK
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PageTradeDeliveryListing'
        '400':
          description: Bad Request
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad Request Example:
                  summary: Example of a 400 Bad Request error
                  description: Bad Request Example
                  value:
                    errorMessage: >-
                      Method parameter 'lastUpdateFrom': Failed to convert value
                      of type 'java.lang.String' to required type
                      'java.time.OffsetDateTime'; Failed to convert from type
                      [java.lang.String] to type
                      [@io.swagger.v3.oas.annotations.Parameter
                      @org.springframework.web.bind.annotation.RequestParam
                      java.time.OffsetDateTime] for value [2024-12-25]
        '403':
          description: Forbidden
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Forbidden Example:
                  summary: Example of a 403 Forbidden response
                  description: Forbidden Example
                  value:
                    errorCode: FORBIDDEN
                    errorMessage: >-
                      Access denied. Please ensure your API key is correctly
                      provided and that your account has access to the requested
                      resource.
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Internal Server Error Example:
                  summary: Example of a 500 Internal Server Error
                  description: Internal Server Error Example
                  value:
                    errorCode: INTERNAL_SERVER_ERROR
                    errorMessage: An unexpected error occurred.
      security:
        - apiKey: []
  /pp/v1/deliveries/{tradeDeliveryUuid}:
    get:
      tags:
        - Trade deliveries
      summary: Retrieve a Trade delivery
      description: 'Returns a Trade delivery object.  '
      operationId: getTradeDelivery
      parameters:
        - name: tradeDeliveryUuid
          in: path
          description: The universal unique identifier of the desired trade delivery
          required: true
          schema:
            type: string
            format: uuid
          example: b43dd825-8a99-4676-aae7-9b91817c2c3c
      responses:
        '200':
          description: OK
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeDelivery'
        '400':
          description: Bad Request
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad Request Example:
                  summary: Example of a 400 Bad Request error
                  description: Bad Request Example
                  value:
                    errorMessage: >-
                      Method parameter 'tradeDeliveryUuid': Failed to convert
                      value of type 'java.lang.String' to required type
                      'java.util.UUID'; Invalid UUID string: abc
        '403':
          description: Forbidden
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Forbidden Example:
                  summary: Example of a 403 Forbidden response
                  description: Forbidden Example
                  value:
                    errorCode: FORBIDDEN
                    errorMessage: >-
                      Access denied. Please ensure your API key is correctly
                      provided and that your account has access to the requested
                      resource.
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
          headers:
            X-Server-Version:
              description: Server version that generated the request
              style: simple
              schema:
                example: 1.0.0
            X-Trace-Id:
              description: >-
                Trace identifier present in all logs generated while servicing
                that request
              style: simple
              schema:
                example: 21dc97ca0e24cab7
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Internal Server Error Example:
                  summary: Example of a 500 Internal Server Error
                  description: Internal Server Error Example
                  value:
                    errorCode: INTERNAL_SERVER_ERROR
                    errorMessage: An unexpected error occurred.
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Api-Key
  schemas:
    ErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: >-
            A predefined code representing the error encountered by the server
            while processing the request
          enum:
            - BAD_REQUEST
            - BAD_REQUEST_RESOURCE_NOT_FOUND
            - BAD_REQUEST_METHOD_NOT_SUPPORTED
            - BAD_REQUEST_MISSING_REQUIRED_PARAMETER
            - BAD_REQUEST_PARAMETER_TYPE_MISMATCH
            - BAD_REQUEST_PARAMETER_VALUE_ILLEGAL
            - FORBIDDEN
            - INTERNAL_SERVER_ERROR
        errorMessage:
          type: string
          description: A more detailed, human-readable error description
    PageTradeListing:
      type: object
      properties:
        results:
          type: array
          description: The list of results on this page
          items:
            $ref: '#/components/schemas/TradeListing'
        pageNumber:
          type: integer
          format: int32
          description: >-
            The current page number of the results. It will be 1 for the first
            page
          example: 3
          minimum: 1
        pageSize:
          type: integer
          format: int32
          description: The number of results on this page
          example: 40
          minimum: 0
        totalResults:
          type: integer
          format: int64
          description: >-
            The total number of results available on server, taking into account
            the applied filters
          example: 193
          minimum: 0
        totalPages:
          type: integer
          format: int64
          description: >-
            The total number of pages necessary to display all results available
            on server, taking into account the desired number of results per
            page
          example: 5
          minimum: 0
    TradeListing:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          description: Universal unique identifier for the object.
          example: b43dd825-8a99-4676-aae7-9b91817c2c3c
        id:
          type: string
          deprecated: true
          description: >-
            Internal identifier, as shown in the UI. Its format will change - do
            not use as reference.
          example: 4321
        created:
          type: string
          format: date-time
          description: The creation timestamp of the trade, in UTC/Zulu timezone.
          example: '2025-02-27T07:48:46.185364Z'
        lastUpdated:
          type: string
          format: date-time
          description: >-
            The timestamp of the last update, in UTC/Zulu timezone. This value
            is updated whenever a Trade value is updated, typically by a buyer
            making an edit. State changes, as well as file adds and removals by
            any side also update this value. Moreover, these exact types of
            changes on any of the referenced Trade deliveries will also update
            this value.
          example: '2025-02-27T08:06:22.136545Z'
        readyToSync:
          type: boolean
          description: >-
            Whether the Trade has at least one Trade delivery that a user marked
            as Ready to sync into ERP.
    DeliveryTerms:
      type: object
      properties:
        incotermType:
          type: string
          description: The type of shipment incoterm
          enum:
            - CFR
            - CIF
            - CIP
            - CPT
            - DAP
            - DDP
            - DPU
            - EXW
            - FAS
            - FCA
            - FOB
        via:
          type: string
          description: The way of transportation
          enum:
            - air
            - land
            - sea
        source:
          $ref: '#/components/schemas/Location'
          description: >-
            Place of departure. Depending on the incoterm, it can be defined or
            not. If it is defined, it can be a sea port, an airport, a city, a
            country etc. Examples: { "type": "Airport", "name": "Zaragoza
            Airport", "displayName": "Zaragoza, ZAZ", "code": "ZAZ",
            "countryCode": "ES" }, { "type": "Port", "name": "Shanghai",
            "displayName": "Shanghai, CN SGH", "code": "CN SGH", "countryCode":
            "CN" }, { "type": "Land location", "name": "Toulouse",
            "displayName": "Toulouse, FR", "code": null, "countryCode": "FR" },
            { "type": "Country", "name": "Switzerland", "displayName":
            "Switzerland", "code": "CHE", "countryCode": "CH" }, { "type":
            "Region", "name": "North America", "displayName": "North America",
            "code": null, "countryCode": null }
          example:
            type: Airport
            name: Zaragoza Airport
            displayName: Zaragoza, ZAZ
            code: ZAZ
            countryCode: ES
        destination:
          $ref: '#/components/schemas/Location'
          description: >-
            Place of destination. Depending on the incoterm, it can be defined
            or not. If it is defined, it can be a sea port, an airport, a city
            etc
          example:
            type: Airport
            name: Southampton Airport
            displayName: Southampton, SOU
            code: SOU
            countryCode: GB
    FileDetails:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          description: The universal unique identifier of the file
          example: b43dd825-8a99-4676-aae7-9b91817c2c3c
        name:
          type: string
          description: >-
            The name of the file. It is derived from the document type, document
            details and original file extension
          example: Sales confirmation [Final version].pdf
        created:
          type: string
          format: date-time
          description: The creation timestamp of the file, in UTC/Zulu timezone
          example: '2025-02-27T07:48:46.185364Z'
        documentType:
          type: string
          description: The document type of the file
          example: Sales confirmation
        documentDetails:
          type: string
          description: File additional details
          example: Final version
    IdentifiableEntity:
      type: object
      properties:
        uuid:
          type: string
          description: The universal unique identifier of the entity
          example: b43dd825-8a99-4676-aae7-9b91817c2c3c
    Location:
      type: object
      properties:
        type:
          type: string
          description: The type of location
          enum:
            - Airport
            - Port
            - Land location
            - Country
            - Region
        name:
          type: string
          description: The name of the location. Its value depends on the location type.
          examples:
            - Zaragoza Airport
            - Shanghai
            - Toulouse
            - Switzerland
            - North America
        code:
          type: string
          description: >-
            The location code. It is a standard value, depending on the location
            type.
          examples:
            - ZAZ
            - CN SGH
            - 'null'
            - CHE
            - 'null'
        countryCode:
          type: string
          description: 2 letter country code (ISO 3166).
          examples:
            - ES
            - CN
            - FR
            - CH
            - 'null'
        displayName:
          type: string
          description: >-
            A user friendly render of the location, as shown in the platform.
            Its format depends on the location type.
          examples:
            - Zaragoza, ZAZ
            - Shanghai, CN SGH
            - Toulouse, FR
            - Switzerland
            - North America
    NamedEntity:
      type: object
      properties:
        name:
          type: string
          description: The name of this entity
          example: A wonderful name
    PackingType:
      type: object
      properties:
        name:
          type: string
          description: The packaging type
          example: Small bag
        quantity:
          $ref: '#/components/schemas/Quantity'
          description: The capacity of one package unit
    PeriodOfDays:
      type: object
      properties:
        startDate:
          type: string
          format: date
          description: The start calendar date
          example: '2024-03-21'
        endDate:
          type: string
          format: date
          description: The end calendar date
          example: '2024-08-25'
    Price:
      type: object
      properties:
        value:
          type: number
          description: The price amount
        currency:
          type: string
          description: The currency used for price
    Quantity:
      type: object
      properties:
        value:
          type: number
          description: The quantity amount
        uom:
          type: string
          description: The unit of measure used for the capacity
          enum:
            - g
            - kg
            - MT
            - kgA
            - BOU
            - MIU
            - L
    Trade:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          description: Universal unique identifier for the object.
          example: b43dd825-8a99-4676-aae7-9b91817c2c3c
        id:
          type: string
          deprecated: true
          description: >-
            Internal identifier, as shown in the UI. Its format will change - do
            not use as reference.
          example: 4321
        created:
          type: string
          format: date-time
          description: The creation timestamp of the trade, in UTC/Zulu timezone.
          example: '2025-02-27T07:48:46.185364Z'
        lastUpdated:
          type: string
          format: date-time
          description: >-
            The timestamp of the last update, in UTC/Zulu timezone. This value
            is updated whenever a Trade value is updated, typically by a buyer
            making an edit. State changes, as well as file adds and removals by
            any side also update this value. Moreover, these exact types of
            changes on any of the referenced Trade deliveries will also update
            this value.
          example: '2025-02-27T08:06:22.136545Z'
        buyerEmail:
          type: string
          description: The email address of the trade buyer.
          example: john.smith@example.com
        buyerCompany:
          $ref: '#/components/schemas/NamedEntity'
          description: Trade buyer company properties.
        sellerCompany:
          $ref: '#/components/schemas/NamedEntity'
          description: Trade seller company properties.
        deliveryType:
          type: string
          description: The type of delivery.
          enum:
            - SINGLE_PRODUCT
            - CALL_OFF
            - COMBINED_SHIPMENT
        deliveryTerms:
          $ref: '#/components/schemas/DeliveryTerms'
          description: Agreed Shipping details.
        calloffTerms:
          $ref: '#/components/schemas/PeriodOfDays'
          description: Agreed call-off delivery period.
        readyToSync:
          type: boolean
          description: >-
            Whether the Trade has at least one Trade delivery that a user marked
            as Ready to sync into ERP.
        state:
          type: string
          description: The current state of the trade.
          enum:
            - OPEN
            - FINALIZED
            - CANCELLED
        confirmationDate:
          type: string
          format: date
          description: The calendar date of the trade confirmation.
          example: '2024-03-21'
        contractId:
          type: string
          description: The customer-specific contract identifier.
        fxHedgeNeeded:
          type: boolean
          description: Fx Hedge flag.
        productTerms:
          type: array
          description: Full specifications of the traded products.
          items:
            $ref: '#/components/schemas/TradeProductTerms'
        deliveries:
          type: array
          description: A list of Trade Deliveries attached to this Trade.
          items:
            $ref: '#/components/schemas/IdentifiableEntity'
        buyerDocuments:
          type: array
          description: The documents attached by the Buyer to this Trade.
          items:
            $ref: '#/components/schemas/FileDetails'
        sellerDocuments:
          type: array
          description: The documents attached by the Seller to this Trade.
          items:
            $ref: '#/components/schemas/FileDetails'
    TradeProductTerms:
      type: object
      properties:
        packingType:
          $ref: '#/components/schemas/PackingType'
          description: The type of the package used to deliver the product
        quantity:
          $ref: '#/components/schemas/Quantity'
          description: The total product quantity delivered in this packing type
        unitPrice:
          $ref: '#/components/schemas/Price'
          description: The total price for the product delivered in this packing type
        productName:
          type: string
          description: The name of the product delivered in this packing type
        grade:
          type: string
          description: The grade of the product
          enum:
            - Agriculture
            - Cosmetic
            - Feed
            - Food
            - Pet
            - Pharma
            - Technical
            - Vet
        form:
          type: string
          description: The form of the product
          enum:
            - Beadlets
            - Bolus
            - Coated
            - Compacted
            - Concentrate
            - Corn carrier
            - Corn cob
            - Crystals
            - Flakes
            - Granular
            - Injectable
            - Isolate
            - Liquid
            - Micronized
            - Oil
            - Pellets
            - Powder
            - Prills
            - Solution
            - Spray dried
            - Sterile
            - Water soluble
            - Winterized oil
        additionalSpecifications:
          type: string
          description: Other product specifications
    FileContent:
      type: object
      properties:
        fileName:
          type: string
          description: >-
            The name of the file. It is derived from the document type, document
            details and original file extension
          examples:
            - Sales confirmation [Final version].pdf
            - Sales contract countersigned.pdf
        downloadUrl:
          type: string
          description: >-
            The URL that can be used to download the file content. Its validity
            is limited to 10 minutes
    PageTradeDeliveryListing:
      type: object
      properties:
        results:
          type: array
          description: The list of results on this page
          items:
            $ref: '#/components/schemas/TradeDeliveryListing'
        pageNumber:
          type: integer
          format: int32
          description: >-
            The current page number of the results. It will be 1 for the first
            page
          example: 3
          minimum: 1
        pageSize:
          type: integer
          format: int32
          description: The number of results on this page
          example: 40
          minimum: 0
        totalResults:
          type: integer
          format: int64
          description: >-
            The total number of results available on server, taking into account
            the applied filters
          example: 193
          minimum: 0
        totalPages:
          type: integer
          format: int64
          description: >-
            The total number of pages necessary to display all results available
            on server, taking into account the desired number of results per
            page
          example: 5
          minimum: 0
    TradeDeliveryListing:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          description: Universal unique identifier for the object.
          example: b43dd825-8a99-4676-aae7-9b91817c2c3c
        id:
          type: string
          deprecated: true
          description: >-
            Internal identifier, as shown in the UI. Its format will change - do
            not use as reference.
          example: 4321-03
        created:
          type: string
          format: date-time
          description: The creation timestamp of the trade delivery, in UTC/Zulu timezone.
          example: '2025-02-27T07:48:46.185364Z'
        lastUpdated:
          type: string
          format: date-time
          description: >-
            The timestamp of the last update, in UTC/Zulu timezone. This value
            is updated whenever a Trade delivery value is updated, typically by
            a buyer making an edit. State changes, as well as file adds and
            removals by any side also update this value.
          example: '2025-02-27T08:06:22.136545Z'
        readyToSync:
          type: boolean
          description: >-
            Whether a user has marked this Trade delivery as Ready to sync into
            ERP.
    DayDeliveryDate:
      allOf:
        - $ref: '#/components/schemas/DeliveryDate'
        - type: object
          properties:
            type:
              type: string
              description: The value representing a delivery date schema of type day.
              enum:
                - DAY
              example: DAY
            date:
              type: string
              format: date
              description: The exact day value.
              example: '2025-03-21'
      description: Day-based delivery date
      example:
        type: DAY
        date: '2025-03-21'
    DeliveryDate:
      type: object
      description: >-
        Represents a date specification that can be one of PROMPT, DAY, WEEK, or
        MONTH_PART
      discriminator:
        propertyName: type
      properties:
        type:
          type: string
          description: >-
            The type of delivery date schema. There will always be a date value,
            but its meaning changes with the date type.
          enum:
            - PROMPT
            - DAY
            - WEEK
            - MONTH_PART
    MonthPartDeliveryDate:
      allOf:
        - $ref: '#/components/schemas/DeliveryDate'
        - type: object
          properties:
            type:
              type: string
              description: >-
                The value representing a delivery date schema of type month
                part.
              enum:
                - MONTH_PART
              example: MONTH_PART
            partOfMonth:
              type: string
              description: The delivery period represented as one of 3 month parts.
              enum:
                - EARLY
                - MID
                - LATE
              example: MID
            date:
              type: string
              format: date
              description: >-
                The first day of the selected month part. `EARLY` is represented
                by 1, `MID` by 11, `LATE` by 21.
              example: '2025-03-11'
      description: Month part-based delivery date
      example:
        type: MONTH_PART
        partOfMonth: LATE
        date: '2025-03-21'
    PromptDeliveryDate:
      allOf:
        - $ref: '#/components/schemas/DeliveryDate'
        - type: object
          properties:
            type:
              type: string
              description: The value representing a delivery date schema of type prompt.
              enum:
                - PROMPT
              example: PROMPT
            date:
              type: string
              format: date
              description: >-
                "Prompt" means "as soon as possible" and therefore cannot be
                meaningfully represented by a date. The date value only stores
                the date at the time of entity creation.
              example: '2025-03-27'
      description: Prompt (ASAP) delivery date
      example:
        type: PROMPT
        date: '2025-03-27'
    TradeDelivery:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          description: Universal unique identifier for the object.
          example: b43dd825-8a99-4676-aae7-9b91817c2c3c
        id:
          type: string
          deprecated: true
          description: >-
            Internal identifier, as shown in the UI. Its format will change - do
            not use as reference.
          example: 4321-03
        created:
          type: string
          format: date-time
          description: The creation timestamp of the trade delivery, in UTC/Zulu timezone.
          example: '2025-02-27T07:48:46.185364Z'
        lastUpdated:
          type: string
          format: date-time
          description: >-
            The timestamp of the last update, in UTC/Zulu timezone. This value
            is updated whenever a Trade delivery value is updated, typically by
            a buyer making an edit. State changes, as well as file adds and
            removals by any side also update this value.
          example: '2025-02-27T08:06:22.136545Z'
        state:
          type: string
          description: The current state of the trade delivery.
          enum:
            - OPEN
            - FINALIZED
            - CANCELLED
        authorEmail:
          type: string
          description: The email address of the trade delivery author.
          example: john.smith@example.com
        readyToSync:
          type: boolean
          description: >-
            Whether a user has marked this Trade delivery as Ready to sync into
            ERP.
        providerCode:
          type: string
          description: Provider code as per your ERP.
        purchaseOrganizationCode:
          type: string
          description: Purchase organization code as per your ERP.
        customerCode:
          type: string
          description: Customer code as per your ERP.
        deliveryTerms:
          $ref: '#/components/schemas/DeliveryTerms'
          description: Shipping details.
        deliveryDate:
          description: >-
            The delivery date. It can be a PromptDeliveryDate, DayDeliveryDate,
            WeekDeliveryDate, or MonthPartDeliveryDate. Its meaning is highly
            dependent of the incoterm type of the delivery terms
          example:
            type: WEEK
            weekNumber: 2025-W01
            date: '2024-12-30'
          oneOf:
            - $ref: '#/components/schemas/DayDeliveryDate'
            - $ref: '#/components/schemas/MonthPartDeliveryDate'
            - $ref: '#/components/schemas/PromptDeliveryDate'
            - $ref: '#/components/schemas/WeekDeliveryDate'
        eta:
          description: >-
            The estimated time of arrival. The estimated time of arrival. Its
            logical meaning depends on the incoterm in deliveryTerms
          example:
            type: DAY
            date: '2024-12-20'
          oneOf:
            - $ref: '#/components/schemas/DayDeliveryDate'
            - $ref: '#/components/schemas/MonthPartDeliveryDate'
            - $ref: '#/components/schemas/PromptDeliveryDate'
            - $ref: '#/components/schemas/WeekDeliveryDate'
        etd:
          description: >-
            The estimated time of departure. Its logical meaning depends on the
            incoterm in deliveryTerms.
          example:
            type: DAY
            date: '2024-11-27'
          oneOf:
            - $ref: '#/components/schemas/DayDeliveryDate'
            - $ref: '#/components/schemas/MonthPartDeliveryDate'
            - $ref: '#/components/schemas/PromptDeliveryDate'
            - $ref: '#/components/schemas/WeekDeliveryDate'
        blDate:
          description: >-
            The transport date as per shipping company: BL Date (Sea), AWB Date
            (Air) or CMR Date (Land).
          example:
            type: DAY
            date: '2024-11-26'
          oneOf:
            - $ref: '#/components/schemas/DayDeliveryDate'
            - $ref: '#/components/schemas/MonthPartDeliveryDate'
            - $ref: '#/components/schemas/PromptDeliveryDate'
            - $ref: '#/components/schemas/WeekDeliveryDate'
        blNumber:
          type: string
          description: The transport identifier as provided by shipping company.
        productTerms:
          type: array
          description: Full specifications of the traded products.
          items:
            $ref: '#/components/schemas/TradeDeliveryProductTerms'
        buyerDocuments:
          type: array
          description: The documents attached by the Buyer to this Trade delivery.
          items:
            $ref: '#/components/schemas/FileDetails'
        sellerDocuments:
          type: array
          description: The documents attached by the Seller to this Trade delivery.
          items:
            $ref: '#/components/schemas/FileDetails'
    TradeDeliveryProductTerms:
      type: object
      properties:
        packingType:
          $ref: '#/components/schemas/PackingType'
          description: The type of the package used to deliver the product
        quantity:
          $ref: '#/components/schemas/Quantity'
          description: The total product quantity delivered in this packing type
        unitPrice:
          $ref: '#/components/schemas/Price'
          description: The total price for the product delivered in this packing type
        productName:
          type: string
          description: The name of the product delivered in this packing type
        grade:
          type: string
          description: The grade of the product
          enum:
            - Agriculture
            - Cosmetic
            - Feed
            - Food
            - Pet
            - Pharma
            - Technical
            - Vet
        form:
          type: string
          description: The form of the product
          enum:
            - Beadlets
            - Bolus
            - Coated
            - Compacted
            - Concentrate
            - Corn carrier
            - Corn cob
            - Crystals
            - Flakes
            - Granular
            - Injectable
            - Isolate
            - Liquid
            - Micronized
            - Oil
            - Pellets
            - Powder
            - Prills
            - Solution
            - Spray dried
            - Sterile
            - Water soluble
            - Winterized oil
        additionalSpecifications:
          type: string
          description: Other product specifications
        materialCode:
          type: string
          description: The material code as per your ERP.
        manufacturerCode:
          type: string
          description: The manufacturer code as per your ERP.
        salesOrderCode:
          type: string
          description: The sales order code as per your ERP.
    WeekDeliveryDate:
      allOf:
        - $ref: '#/components/schemas/DeliveryDate'
        - type: object
          properties:
            type:
              type: string
              description: The value representing a delivery date schema of type week.
              enum:
                - WEEK
              example: WEEK
            weekNumber:
              type: string
              description: The delivery period represented as a week in ISO-8601 format
              example: 2025-W01
            date:
              type: string
              format: date
              description: The first day of the week
              example: '2024-12-30'
      description: Week-based delivery date
      example:
        type: WEEK
        weekNumber: 2025-W01
        date: '2024-12-30'
