openapi: 3.0.1
info:
  title: Kemiex SAP API
  version: 0.1.14
  description: >
    > **Deprecated:** This API will be sunset soon. Please use the [Private
    portal API](https://developers.kemiex.com/apis/pp) instead.


    The Kemiex APIs provide methods for connecting your systems directly with
    the Kemiex application. 


    They emerged out of Kemiex customers' need to integrate with their SAP
    workflows. For this reason, they are designed around this primary need but
    will evolve to cover more generic usage. 


    ## The trade object

    - A Trade object is the agreement reached at the end of a negotiation
    between buyer and seller.

    - Each Trade can have one or more `Trade.productTerms` (if
    `Trade.deliveryType = 'combinedShipment'`).

    - Each Trade can have one or more `Trade.deliveries`, which is the
    equivalent of a Purchase Order in SAP.

    - Deliveries can be added or modified by Buyer, so they contain the final
    product terms, `Trade.deliveries.productTerms`, including SAP fields like
    `providerCode`.


    ## Flattened schemas

    - `DeliveryTerms.source`,  `DeliveryTerms.destination`  
      Platform users can select 3 types of locations, depending on the Via parameter: A Google Places API object, an internal Port object, or an internal Airport object.  
      However, the API returns a flattened string, e.g. _El Dorado International Airport (Bogotá) BOG_.

    ## Rate limits


    A rate limit of 300 quota units per minute is enforced. Exceeding this limit
    returns HTTP code 429. The table below lists the corresponding quota units
    consumed per api endpoint.


    | Endpoint | Quota units |

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

    | `/files/{fileUuid}` | 5 units |

    | `/trades` | 1 unit |

    | `/trades/{tradeUUID}` | 1 unit |
servers:
  - url: https://{environment}.kemiex.com/sap/v1
    variables:
      environment:
        default: api
        enum:
          - dev.api
          - stage.api
          - api
tags:
  - name: trade
    description: >
      The trade object contains only SAP-relevant attributes of a Kemiex trade
      object.
paths:
  /trades:
    get:
      deprecated: true
      tags:
        - trade
      summary: List trades
      description: Use parameter filters to narrow down results.
      operationId: getSapTrades
      parameters:
        - name: dateFrom
          in: query
          description: Return trades updated later than date-time.
          required: true
          schema:
            type: string
            format: date-time
            example: '2020-11-21T08:30:00Z'
        - name: dateTo
          in: query
          description: Return trades updated earlier than date-time.
          required: false
          schema:
            type: string
            format: date-time
            example: '2020-11-21T08:30:00Z'
        - name: sapReady
          in: query
          description: Return trades that have at least one delivery marked as SAP Ready.
          required: false
          schema:
            type: boolean
            example: 'true'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int64
                      example: 3421
                    created:
                      type: string
                      format: date-time
                    lastUpdated:
                      type: string
                      format: date-time
                    sapReady:
                      type: boolean
                      description: >-
                        True if at least one of the Trade deliveries is
                        `sapReady = True`
        '400':
          description: Bad Request
        '403':
          description: Access Denied
        '429':
          description: Too Many Requests
      security:
        - ApiKey: []
  /trades/{tradeUuid}:
    get:
      deprecated: true
      tags:
        - trade
      summary: Find trade by UUID
      description: Returns a single trade
      operationId: getSapTradeByUuid
      parameters:
        - name: tradeUuid
          in: path
          description: UUID of trade to return
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SapTrade'
            application/xml:
              schema:
                $ref: '#/components/schemas/SapTrade'
        '400':
          description: Invalid ID supplied
        '403':
          description: Access Denied
        '404':
          description: Trade Not Found
        '429':
          description: Too Many Requests
      security:
        - ApiKey: []
  /files/{fileUuid}:
    get:
      deprecated: true
      tags:
        - trade
      summary: Find file by UUID
      description: Returns a single file
      operationId: getFileByUuid
      parameters:
        - name: fileUuid
          in: path
          description: UUID of file to return
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              schema:
                type: object
                properties:
                  file-name:
                    type: string
                    example: Trade_741_Confirmation_of_transaction_2021-08-09_10-44.pdf
        '400':
          description: Invalid UUID Supplied
        '403':
          description: Access Denied
        '404':
          description: File Not Found
        '429':
          description: Too Many Requests
      security:
        - ApiKey: []
components:
  schemas:
    SapTrade:
      required:
        - uuid
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          example: 88d53ba0-b8fa-4f98-8417-f771fb01bcd7
        id:
          type: integer
          format: int64
          example: 3421
        created:
          type: string
          format: date-time
        lastUpdated:
          type: string
          format: date-time
        buyerEmail:
          type: string
          format: email
          example: buyer@example.com
          description: Email of trade counterparty that has the buyer role.
        buyerCompany:
          allOf:
            - $ref: '#/components/schemas/Company'
        sellerCompany:
          allOf:
            - $ref: '#/components/schemas/Company'
        deliveryType:
          type: string
          enum:
            - SINGLE_PRODUCT
            - COMBINED_SHIPMENT
            - CALL_OFF
        deliveryTerms:
          allOf:
            - $ref: '#/components/schemas/DeliveryTerms'
        calloffTerms:
          allOf:
            - $ref: '#/components/schemas/CalloffTerms'
        sapReady:
          type: boolean
          description: True if at least one of the Trade deliveries is `sapReady = True`
        state:
          type: string
          enum:
            - OPEN
            - CANCELLED
            - FINALIZED
          example: OPEN
        confirmationDate:
          type: string
          format: date-time
        contractId:
          type: string
          example: ID 1234
          description: Contract ID from external system.
        fxHedgeNeeded:
          type: boolean
          description: FX hedge needed
        productTerms:
          type: array
          items:
            $ref: '#/components/schemas/SapMasterProductTerms'
        deliveries:
          type: array
          items:
            $ref: '#/components/schemas/SapTradeDelivery'
        buyerDocuments:
          type: array
          items:
            $ref: '#/components/schemas/File'
        sellerDocuments:
          type: array
          items:
            $ref: '#/components/schemas/File'
    SapMasterProductTerms:
      type: object
      properties:
        packingType:
          type: object
          properties:
            name:
              type: string
            quantity:
              type: number
              format: double
            uom:
              type: string
          example:
            name: small bag
            quantity: '25'
            uom: kg
        quantity:
          type: object
          properties:
            value:
              type: number
              format: double
            uom:
              type: string
              description: Unit of measurement
              enum:
                - g
                - kg
                - kgA
                - BOU
                - L
                - MT
          example:
            value: 15
            uom: MT
        unitPrice:
          type: object
          properties:
            value:
              type: number
              format: double
            currency:
              type: string
              enum:
                - EUR
                - USD
          example:
            value: 2950
            currency: EUR
          description: Unit price excluding VAT
        productName:
          type: string
          example: L-Lysine Sulfate
        grade:
          type: string
          enum:
            - Pharma
            - Vet
            - Food
            - Feed
            - Cosmetic
            - Technical
          example: Feed
        form:
          type: string
          example: Powder
        additionalSpecifications:
          type: string
          example: 98.5%
    SapProductTerms:
      type: object
      properties:
        materialCode:
          type: string
          example: A23456789012345678
        manufacturerCode:
          type: string
          example: A23456789012345678
        salesOrderCode:
          type: string
          example: A23456789012345678
        packingType:
          type: object
          properties:
            name:
              type: string
            quantity:
              type: number
              format: double
            uom:
              type: string
          example:
            name: small bag
            quantity: '25'
            uom: kg
        quantity:
          type: object
          properties:
            value:
              type: number
              format: double
            uom:
              type: string
              description: Unit of measurement
              enum:
                - g
                - kg
                - kgA
                - BOU
                - L
                - MT
          example:
            value: 15
            uom: MT
        unitPrice:
          type: object
          properties:
            value:
              type: number
              format: double
            currency:
              type: string
              enum:
                - EUR
                - USD
          example:
            value: 2950
            currency: EUR
          description: Unit price excluding VAT
        productName:
          type: string
          example: L-Lysine Sulfate
        grade:
          type: string
          enum:
            - Pharma
            - Vet
            - Food
            - Feed
            - Cosmetic
            - Technical
          example: Feed
        form:
          type: string
          example: Powder
        additionalSpecifications:
          type: string
          example: 98.5%
    SapTradeDelivery:
      type: object
      required:
        - id
        - created
        - lastUpdated
        - sapReady
      properties:
        id:
          type: integer
        created:
          type: string
          format: date-time
        lastUpdated:
          type: string
          format: date-time
        state:
          type: string
          enum:
            - OPEN
            - CANCELLED
            - FINALIZED
          example: OPEN
        authorEmail:
          type: string
          format: email
          example: author@example.com
          description: Email of user that created the delivery request.
        sapReady:
          type: boolean
        providerCode:
          type: string
          example: A234567890
        purchaseOrganizationCode:
          type: string
          example: AP12
        customerCode:
          type: string
          example: customer01
        deliveryTerms:
          allOf:
            - $ref: '#/components/schemas/DeliveryTerms'
        deliveryDate:
          type: object
          anyOf:
            - type: object
              title: Prompt
              properties:
                dateType:
                  type: string
                  enum:
                    - PROMPT
            - type: object
              title: Day
              properties:
                dateType:
                  type: string
                  enum:
                    - DAY
                date:
                  type: string
                  format: date
            - type: object
              title: Week
              properties:
                dateType:
                  type: string
                  enum:
                    - WEEK
                weekNumber:
                  type: string
                  example: '202154'
                date:
                  type: string
                  format: date
            - type: object
              title: Month part
              properties:
                dateType:
                  type: string
                  enum:
                    - MONTH_PART
                partOfMonth:
                  type: string
                  enum:
                    - EARLY
                    - MID
                    - LATE
                date:
                  type: string
                  format: date
        eta:
          type: object
          anyOf:
            - type: object
              title: Day
              properties:
                dateType:
                  type: string
                  enum:
                    - DAY
                date:
                  type: string
                  format: date
            - type: object
              title: Week
              properties:
                dateType:
                  type: string
                  enum:
                    - WEEK
                weekNumber:
                  type: string
                  example: '202154'
            - type: object
              title: Month part
              properties:
                dateType:
                  type: string
                  enum:
                    - MONTH_PART
                partOfMonth:
                  type: string
                  enum:
                    - EARLY
                    - MID
                    - LATE
                date:
                  type: string
                  format: date
        etd:
          type: object
          anyOf:
            - type: object
              title: Day
              properties:
                dateType:
                  type: string
                  enum:
                    - DAY
                date:
                  type: string
                  format: date
            - type: object
              title: Week
              properties:
                dateType:
                  type: string
                  enum:
                    - WEEK
                weekNumber:
                  type: string
                  example: '202154'
            - type: object
              title: Month part
              properties:
                dateType:
                  type: string
                  enum:
                    - MONTH_PART
                partOfMonth:
                  type: string
                  enum:
                    - EARLY
                    - MID
                    - LATE
                date:
                  type: string
                  format: date
        blDate:
          type: object
          anyOf:
            - type: object
              title: Day
              properties:
                dateType:
                  type: string
                  enum:
                    - DAY
                date:
                  type: string
                  format: date
            - type: object
              title: Week
              properties:
                dateType:
                  type: string
                  enum:
                    - WEEK
                weekNumber:
                  type: string
                  example: '202154'
            - type: object
              title: Month part
              properties:
                dateType:
                  type: string
                  enum:
                    - MONTH_PART
                partOfMonth:
                  type: string
                  enum:
                    - EARLY
                    - MID
                    - LATE
                date:
                  type: string
                  format: date
        blNumber:
          type: string
        productTerms:
          type: array
          items:
            $ref: '#/components/schemas/SapProductTerms'
        buyerDocuments:
          type: array
          items:
            $ref: '#/components/schemas/File'
        sellerDocuments:
          type: array
          items:
            $ref: '#/components/schemas/File'
    DeliveryTerms:
      type: object
      properties:
        incotermsType:
          type: string
          enum:
            - EXW
            - FCA
            - DAT
            - DAP
            - DDP
            - FAS
            - FOB
            - CFR
            - CIF
            - CPT
            - CIP
        via:
          type: string
          enum:
            - LAND
            - AIR
            - SEA
        source:
          type: string
        destination:
          type: string
    Company:
      type: object
      properties:
        name:
          type: string
          example: Last Inc
    CalloffTerms:
      type: object
      properties:
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
    File:
      required:
        - uuid
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          example: 9b08257c-c35d-4ab2-873f-f3030d4c7693
        created:
          type: string
          format: date-time
        name:
          type: string
          example: Purchase order [PO 123].pdf
          description: Calculated value, made out of documentType and documentDetail.
        documentType:
          type: string
          example: Purchase order
          enum:
            - COA
            - Packing list
            - Cargo insurance
            - Certificate of origin
            - Bill of lading
            - Invoice
            - Sales confirmation
            - MSDS
            - Shipping instructions
            - Payment confirmation
            - Label template
            - Label copy
            - Sales contract
            - Sales contract countersigned
            - Signed sales confirmation
            - Proforma invoice
            - Purchase order
            - Other
          description: >-
            Can be one of the enum values. The list is updated periodically but
            may be incomplete.
        documentDetail:
          type: string
          example: PO 123
        fileName:
          type: string
          example: PO_123_xx.pdf
          description: Original file name.
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          format: int32
        type:
          type: string
        message:
          type: string
  securitySchemes:
    ApiKey:
      type: apiKey
      name: Api-Key
      in: header
