openapi: 3.0.1
info:
  title: OSCA DC Order Interface API
  description: Setlog Service for import purchase orders
  contact:
    name: Setlog GmbH
    url: https://www.setlog.com
    email: interfaces@setlog-support.com
  version: 1.0.0
servers:
  - url: https://{your-customer-domain}.setlog.com/order-interface/api
    description: Generated server url
security:
  - basicAuth: []
paths:
  /order:
    put:
      tags:
        - Upload purchase orders
      operationId: uploadPurchaseOrder
      summary: Upload purchase orders from ERP-System
      description: Upload new or changed purchase orders from ERP-System into your OSCA System.
      requestBody:
        description: an object with a list of new or changed purchase orders
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseOrderPayload'
        required: true
      responses:
        '200':
          description: The uploaded purchase orders are saved successfully. It could be that due to the configuration in your OSCA System, some values for the shipment are overridden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
        '400':
          description: This means that the entity has the required fields but some fields are missing during the process. This can occur, when you define default fields but they are not taken.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
        '401':
          description: This means that you are unauthorized.
          content:
            application/json:
              schema:
                type: object
        '422':
          description: This means that the request is not well-formed, or syntactically incorrect, or violates schema.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
  /item:
    put:
      tags:
        - Upload items
      operationId: uploadItems
      summary: Upload items from ERP-System
      description: Upload new or changed itmes from ERP-System into your OSCA System.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemPayload'
        required: true
      responses:
        '200':
          description: The items are saved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
        '400':
          description: This means that the entity has the required fields but some fields are missing during the process. This can occur, when you define default fields but they are not taken.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
        '401':
          description: This means that you are unauthorized.
          content:
            application/json:
              schema:
                type: object
        '422':
          description: This means that the request is not well-formed, or syntactically incorrect, or violates schema.
          content:
            application/json:
              schema:
                type: string
components:
  schemas:
    Breakdown:
      required:
        - id
        - quantity
      type: object
      properties:
        id:
          type: string
          description: 'Unique id for breakdown. ID is optional. If it is not set, ID is a concatenation of EAN and size (both fields are mandatory in that case). If ID is explicitly set, EAN and size are optional.'
        itemNumber:
          type: string
          description: 'Number of item'
        color:
          type: string
          description: 'Color id'
        colorText:
          type: string
          description: 'Color description as text'
        size:
          type: string
          description: 'Size description as text. If ID is explicitly set, EAN and size are optional.'
        sort:
          type: integer
          description: 'Sort order in which the size is shown in the system'
          format: int32
        ean:
          type: string
          description: 'European Article Number (EAN). If ID is explicitly set, EAN and size are optional.'
        quantity:
          type: integer
          description: 'Order breakdown quantity'
          format: int32
        price:
          type: number
          description: 'Purchase cost'
          format: float
        weight:
          type: number
          description: 'SKU weight in kg'
          format: float
        volume:
          type: number
          description: 'SKU volume in cbm'
          format: float
        lotFactor:
          type: integer
          description: 'Only for lots: quantity of pieces in this lot'
          format: int64
        finishFlag:
          type: boolean
          description: 'Inward Delivery Completed Indicator: if true, pretend that open order quantity is zero in any calculations made'
        customAttributes:
          type: object
          additionalProperties:
            type: object
          description: 'Additional attributes as a custom object. Unknown fields on Breakdown Position will be interpreted as being part of this object instead.'
      description: 'color-size break down'
    Item:
      required:
        - itemNumber
      type: object
      properties:
        itemNumber:
          type: string
          description: 'Unique article number'
        itemText:
          type: string
          description: 'Item description as text'
        brand:
          type: string
          description: 'Brand name of the item'
        collection:
          type: string
          description: 'Collection of the item'
        theme:
          type: string
          description: 'Thematic summary of certain items'
        productType:
          type: string
          description:   'First level of classification of an item'
        productGroup:
          type: string
          description: 'Second level of classification of an item'
        mainProductGroup:
          type: string
          description: 'Third level of classification of an item'
        unit:
          type: string
          description: 'Unit in which an item is ordered'
        quantityPerUnit:
          type: integer
          description: 'Quantity of items within one unit'
          format: int32
        weight:
          type: number
          description: 'Weight of an item'
          format: double
        weightUnitId:
          type: integer
          format: int32
          description: 'Weight unit id'
        volume:
          type: number
          description: 'Volume of an item'
          format: double
        volumeUnitId:
          type: integer
          format: int32
          description: 'Volume unit id'
        style:
          type: string
          description: 'Style/design/ pattern of an item'
        styleText:
          type: string
          description: 'Style description as text'
        material:
          type: string
          description: 'Material of an item'
        materialText:
          type: string
          description: 'Material description as text'
        materialComposition:
          type: string
          description: 'Material composition of an item'
        color:
          type: string
          description: 'Color id'
        colorText:
          type: string
          description: 'Color description as text'
        size:
          type: string
          description: 'Size description as text'
        ean:
          type: string
          description: 'European Article Number (EAN)'
        commodity:
          type: string
          description: 'Commodity'
        season:
          type: string
          description: 'Season of the item'
        nos:
          type: boolean
          description: 'Never out of stock'
        customsTariffNumber:
          type: string
          description: 'Customs tariff number. If it is set it could be shared with your integrated forwarder or customs agency'
        customsCategory:
          type: string
          description: 'Customs category'
        dimension:
          type: string
          description: 'Dimension of an item'
        dangerousGoods:
          type: string
          description: 'Dangerous Goods. If it is set it could be shared with your integrated forwarder'
        batchNumberRequired:
          type: boolean
          description: 'Is batch number required'
        countryOfOrigin:
          type: string
          writeOnly: true
          description: 'Country of origin: unlocode (2 digit), https://unece.org/trade/cefact/unlocode-code-list-country-and-territory'
        customAttributes:
          type: object
          additionalProperties:
            type: object
          description: 'Additional attributes as a custom object. Unknown fields on Item will be interpreted as being part of this object instead.'
      description: 'Product as described in item'
    PurchaseOrderPayload:
      type: object
      properties:
        purchaseOrder:
          type: array
          items:
            $ref: '#/components/schemas/PurchaseOrder'
          description: 'List of purchase orders to upload'
    Partner:
      required:
        - number
      type: object
      properties:
        number:
          type: string
          description: 'Unique partner number'
        name:
          type: string
          description: 'Name of the partner. This is visible in your OSCA application. If it is not set, the number is set as name.'
        shortname:
          type: string
          description: 'Short name of the partner'
        city:
          type: string
          description: 'Location of the partner: 5-Digit unlocode; https://unece.org/trade/cefact/unlocode-code-list-country-and-territory'
        country:
          type: string
          description: 'Country of the location of the partner: 2-Digit unlocode; https://unece.org/trade/cefact/unlocode-code-list-country-and-territory'
        address:
          type: string
          description: 'Address of the partner'
        address2:
          type: string
          description: 'Additional address of the partner'
        zip:
          type: string
          description: 'ZIP-Code of the partner'
        telephone:
          type: string
          description: 'Telephone'
        fax:
          type: string
          description: 'Fax number'
        email:
          type: string
          description: 'E-Mail'
        description:
          type: string
          description: 'Description'
        partnertype:
          type: string
          description: 'Type of the partner'
          enum:
          - company
          - supplier
          - agent
          - forwarder
          - haulageForwarder
          - inspector
          - laboratory
          - refinisher
          - distributionCenter
          - serviceProvider
      description: 'Company that provides further services during inbound process'
    PurchaseOrder:
      required:
        - purchaseOrderLine
        - purchaseOrderNumber
        - supplier
      type: object
      properties:
        purchaseOrderNumber:
          type: string
          description: 'Purchase Order Number. This value must be unique and also case insensitive. If any existing value is used, then OSCA matches existing "PurchaseOrder" with this "PurchaseOrder" and updates (or cancelled, if cancelled field for all "PurchaseOrderLine"s is set to true) the existing "PurchaseOrder".'
        supplier:
          $ref: '#/components/schemas/Partner'
        purchaseOrderLine:
          type: array
          description: Purchase order lines
          items:
            $ref: '#/components/schemas/PurchaseOrderLine'
        company:
          $ref: '#/components/schemas/Partner'
        agent:
          $ref: '#/components/schemas/Partner'
        purchaser:
          type: string
          description: 'This is the information about person, who responsible for purchasing.'
        department:
          type: string
          description: 'This is the information about department of an enterprise, which is responsible for this order.'
        division:
          type: string
          description: 'This is the information about devision of an enterprise, which is responsible for this order.'
        orderDate:
          type: string
          description: 'Date of order creation.'
          format: date
        orderKind:
          type: string
          description: 'This is the information about the kind of the PurchaseOrder.'
        orderType:
          type: string
          description: 'This is the information about the typification of the PurchaseOrder.'
        paymentTerms:
          type: string
          description: 'Conditions concerning the payment obligations of a purchaser'
        currency:
          type: string
          description: 'Currency in which supplier is payed by the customer, 3 character ISO-Code according to ISO 4217'
        buyingTeam:
          type: string
          description: 'Team of purchasers that is responsible for the purchase of certain items'
        accountingArea:
          type: string
          description: 'Accounting separation of an area of an enterprise'
        customAttributes:
          type: object
          additionalProperties:
            type: object
          description: 'Additional attributs as a custom object. Unknown fields on PurchaseOrder will be interpreted as being part of this object instead.'
        cancelled:
          type: boolean
          description: 'If set to true, all related positions will be cancelled. Additionally only the "purchaseOrderNumber" and "cancelled" field are required. To cancel individual Purchase Order Lines, set the cancelled flag within the corresponding PurchaseOrderLine'
    PurchaseOrderLine:
      required:
        - item
        - position
      type: object
      properties:
        position:
          type: string
          description: 'Position of the purchase order line, unique for each line of the purchase order'
        item:
          type: array
          description: 'Product as described in item'
          items:
            $ref: '#/components/schemas/Item'
        quantity:
          type: integer
          description: 'Order quantity for the position'
          format: int32
        price:
          type: number
          description: 'Purchase cost for position'
          format: double
        unitOfPrice:
          type: integer
          description: 'Unit of price'
          format: int32
        factory:
          $ref: '#/components/schemas/Partner'
        crd:
          type: string
          description: 'Cargo ready date'
          format: date
        exFactoryDate:
          type: string
          description: 'Date when items leave /are intended to leave the factory'
          format: date
        handoverDate:
          type: string
          description: 'Date when items are handed over/are intended to be handed over from factory to forwarder'
          format: date
        mot:
          type: string
          description: 'Mode of transportation between POL and POA'
          enum:
          - SEA
          - AIR
          - SEA-AIR
          - TRUCK
          - RAIL
          - COURIER
        incoterm:
          type: string
          description: 'International commercial terms:3 digit (2020); https://en.wikipedia.org/wiki/Incoterms'
        service:
          type: string
          description: 'Service level of a type of transport (especially for airfreight, a distinction is made between different service levels (A, B, C).'
        dispatchType:
          type: string
          description: 'The way products are transported, flat packed or hanging'
          enum:
          - flat packed
          - hanging
        pol:
          type: string
          description: 'Port of loading: 5-Digit unlocode; https://unece.org/trade/cefact/unlocode-code-list-country-and-territory'
        poa:
          type: string
          description: 'Port of arrival: 5-Digit unlocode; https://unece.org/trade/cefact/unlocode-code-list-country-and-territory'
        etd:
          type: string
          description: 'Estimated Time of Departure'
          format: date
        eta:
          type: string
          description: 'Estimated Date of Arrival'
          format: date
        forwarder:
          $ref: '#/components/schemas/Partner'
        haulageForwarder:
          $ref: '#/components/schemas/Partner'
        inspector:
          $ref: '#/components/schemas/Partner'
        distributionCenter:
          $ref: '#/components/schemas/Partner'
        laboratory:
          $ref: '#/components/schemas/Partner'
        refinisher:
          $ref: '#/components/schemas/Partner'
        serviceProvider:
          $ref: '#/components/schemas/Partner'
        motHaulage:
          type: string
          description: 'Mode of transporation for on carriage'
          enum:
          - TRUCK
          - RAIL
          - BARGE
          - COURIER
        targetDate1:
          type: string
          description: 'First planning date, when goods should be at the destination'
          format: date
        targetDate2:
          type: string
          description: 'Second planning date, when goods should be at the destination'
          format: date
        targetDate3:
          type: string
          description: 'Third planning date, when goods should be at the destination'
          format: date
        toleranceHigh:
          type: number
          description: 'Tolerance for overdelivery in percent'
          format: double
        toleranceLow:
          type: number
          description: 'Tolerance for underdelivery in percent'
          format: double
        channel:
          type: string
          description: 'Name of distribution channel or customer or target group'
        channelIncoterm:
          type: string
          description: 'Incoterm from customers warehouse/ DC to its customer'
        contractNumber:
          type: string
          description: 'Contract order number that precedes a normal purchase order and to which a purchase order can refer to'
        contractPosition:
          type: integer
          description: 'Position of a contract order'
          format: int32
        campaign:
          type: string
          description: 'Special advertisement or marketing campaign a purchase order refers to'
        orderSet:
          type: string
          description: 'Link/connection to other orders'
        countryOfOrigin:
          maxLength: 2
          minLength: 2
          type: string
          description: 'Country of origin: unlocode (2 digit), https://unece.org/trade/cefact/unlocode-code-list-country-and-territory'
        priority:
          type: boolean
          description: 'Defines the priority of the order line. The default value is false'
        breakdown:
          type: array
          description: 'Color-size break down'
          items:
            $ref: '#/components/schemas/Breakdown'
        customAttributes:
          type: object
          additionalProperties:
            type: object
          description: 'Individual attributes (fields) as a freely structured json object for a purchase order line'
        remark:
          maxLength: 1000
          type: string
          description: 'Purchase Order Line remark'
        cancelled:
          type: boolean
          description: 'Defines if a position is cancelled. The default value is false'
      description: 'A purchase order line defines all details about the goods and the deliveries'
    ItemPayload:
      type: object
      description: 'List of items to upload'
      properties:
        item:
          type: array
          items:
            $ref: '#/components/schemas/Item'
    MetaData:
      type: object
      description: 'The metadata of the execution of the request'
      properties:
        transactionId:
          type: string
          description: 'The transaction id of the request'
        timestamp:
          type: string
          format: date-time
          description: 'The timestamp of the request'
    ResponseError:
      type: object
      properties:
        code:
          type: integer
          format: int32
          description: 'The technical code of the error.'
        message:
          type: string
          description: 'The human readable description of the error.'
        reference:
          type: string
          description: 'The reference of the object the error is refer to.'
    ServiceResponse:
      type: object
      description: 'The response of the upload.'
      properties:
        metaData:
          $ref: '#/components/schemas/MetaData'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ResponseError'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ResponseError'
        infos:
          type: array
          items:
            $ref: '#/components/schemas/ResponseError'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic