Emporix Sites API

openapi: 3.2.0
info:
  title: Emporix Sites API
  version: ''
  contact:
    name: Emporix
    url: https://emporix.com
    email: documentation@emporix.com
  description: 'Operations tagged Sites across 2 of this provider''s published API definitions: emporix-shipping-openapi.yml, emporix-shipping-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emporix.io
security:
- oAuth2: []
tags:
- name: Sites
  description: Find shipping related sites
paths:
  /shipping/{tenant}/findSite:
    parameters:
    - $ref: '#/components/parameters/tenant'
    post:
      summary: Finding sites by postal code
      tags:
      - Sites
      description: Retrieves a list of sites with zones where the postal code matches the `postalCode` passed in the request body.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FindSiteRequest'
            example:
              postalCode: '70190'
              country: DE
      parameters:
      - $ref: '#/components/parameters/tenant'
      - $ref: '#/components/parameters/windowsLimit'
      responses:
        '200':
          description: Resource successfully retrieved.
          content:
            application/json:
              example:
              - id: main
                zones:
                - id: deliveryarea
                  name:
                    en: Delivery area Mordor
                  shipTo:
                  - country: DE
                    postalCode: '70190'
                  methods:
                  - id: 1-2_hours_timeframe
                    name:
                      en: 1-2_hours_timeframe
                      de: 1-2 Stunden Lieferzeitfenster
                    maxOrderValue:
                      amount: 1000
                      currency: EUR
                    active: true
                    fees:
                    - minOrderValue:
                        amount: 0
                        currency: EUR
                      cost:
                        amount: 40
                        currency: EUR
                    - minOrderValue:
                        amount: 0
                        currency: EUR
                      cost:
                        amount: 0
                        currency: EUR
                      shippingGroupId: group1
                    - minOrderValue:
                        amount: 50
                        currency: EUR
                      cost:
                        amount: 12
                        currency: EUR
                      shippingGroupId: group2
                    shippingTaxCode: HALF
                  - id: 3_hours_timeframe
                    name:
                      en: 3_hours_timeframe
                      de: 3 Stunden Lieferzeitfenster
                    maxOrderValue:
                      amount: 1000
                      currency: EUR
                    active: true
                    fees:
                    - minOrderValue:
                        amount: 0
                        currency: EUR
                      cost:
                        amount: 30
                        currency: EUR
                    - minOrderValue:
                        amount: 30
                        currency: EUR
                      cost:
                        amount: 31
                        currency: EUR
                      shippingGroupId: group1
                    - minOrderValue:
                        amount: 50
                        currency: EUR
                      cost:
                        amount: 32
                        currency: EUR
                      shippingGroupId: group2
                    shippingTaxCode: HALF
                  - id: 4-more_hours_timeframe
                    name:
                      en: 4-more hours timeframe
                      de: 4-mehr Stunden Lieferzeitfenster
                    maxOrderValue:
                      amount: 2000
                      currency: EUR
                    active: true
                    fees:
                    - minOrderValue:
                        amount: 0
                        currency: EUR
                      cost:
                        amount: 20
                        currency: EUR
                    - minOrderValue:
                        amount: 30
                        currency: EUR
                      cost:
                        amount: 41
                        currency: EUR
                      shippingGroupId: group1
                    - minOrderValue:
                        amount: 50
                        currency: EUR
                      cost:
                        amount: 42
                        currency: EUR
                      shippingGroupId: group2
                    shippingTaxCode: ZERO
                  - id: pickup
                    name:
                      en: pickup
                      de: pickup
                    maxOrderValue:
                      amount: 1000
                      currency: EUR
                    active: true
                    fees:
                    - minOrderValue:
                        amount: 0
                        currency: EUR
                      cost:
                        amount: 18
                        currency: EUR
                    - minOrderValue:
                        amount: 50
                        currency: EUR
                      cost:
                        amount: 55
                        currency: EUR
                      shippingGroupId: group1
                    shippingTaxCode: ZERO
                  actualDeliveryWindows:
                  - id: 5b5572a71cf31a000f31eee6
                    deliveryDate: '2020-12-08T12:00:00.000Z'
                    deliveryTimeRange:
                      startTime: '15:00'
                      endTime: '22:00'
                    zoneId: deliveryarea
                    deliveryMethod: method1
                    cutOffTime: '2020-12-08T11:00:00.000Z'
                    slotId: 1234567890abcdef123abgi
                    deliveryCycle: 2020-12-08-11
                  - id: 5b5572a71cf31a000f31eee6
                    deliveryDate: '2020-12-15T12:00:00.000Z'
                    deliveryTimeRange:
                      startTime: '15:00'
                      endTime: '22:00'
                    deliveryCycle: 2020-12-15-10
                    zoneId: deliveryarea
                    deliveryMethod: method1
                    cutOffTime: '2020-12-15T10:00:00.000Z'
                    slotId: 1234567890abcdef123abgh
                metadata:
                  createdAt: '2020-10-19T13:04:09.894Z'
                  modifiedAt: '2020-10-19T13:04:10.979Z'
                  version: 1
              schema:
                $ref: '#/components/schemas/Sites'
        '400':
          $ref: '#/components/responses/yaasAware_400'
        '401':
          $ref: '#/components/responses/unauthorized_401'
        '404':
          $ref: '#/components/responses/notFound_404'
        '500':
          $ref: '#/components/responses/internalError_500'
      operationId: POST-shipping-find-sites
      security:
      - oAuth2: []
    servers:
    - url: https://api.emporix.io
components:
  schemas:
    Zone:
      title: Zone
      description: The zone is an area where shipments can be delivered.
      type: object
      properties:
        id:
          description: Delivery zone's unique identifier.
          type: string
        default:
          description: Flag indicating whether the zone is the default delivery zone for the site.
          type: boolean
        name:
          $ref: '#/components/schemas/LocalizedValue'
        shipTo:
          $ref: '#/components/schemas/ShipTo'
        methods:
          $ref: '#/components/schemas/Methods'
      required:
      - id
      - name
      - shipTo
    MonetaryAmount:
      title: Monetary amount
      description: Amount of money in a given currency.
      type: object
      properties:
        currency:
          description: Three-letter currency code, compliant with the ISO 4217 standard.
          type: string
        amount:
          type: number
          minimum: 0
          description: Amount in specified currency.
      required:
      - currency
      - amount
    ActualDeliveryWindow:
      title: Actual delivery window
      description: Delivery window is a range of times when the shipment can be delivered to the customers.
      type: object
      properties:
        id:
          description: Delivery window’s unique identifier.
          type: string
        deliveryDate:
          description: Delivery date compliant with the ISO 8601 standard.
          type: string
        deliveryTimeRange:
          $ref: '#/components/schemas/TimeRange'
        deliveryCycle:
          description: Delivery cycle.
          type: string
        zoneId:
          description: Delivery zone’s unique identifier.
          type: string
        deliveryMethod:
          description: Delivery method name.
          type: string
        cutOffTime:
          description: This denotes the latest point in time by which an action (such as an order or request) must be completed for a specific Delivery Time. Date is compliant with the ISO 8601 standard.
          type: string
        slotId:
          description: Delivery time slot's unique identifier.
          type: string
        metadata:
          $ref: '#/components/schemas/MetaData'
      required:
      - deliveryDate
    Method:
      title: Shipping method
      description: Shipping methods define the types of deliveries and properties such as delivery fees.
      type: object
      properties:
        id:
          type: string
        name:
          $ref: '#/components/schemas/LocalizedValue'
        maxOrderValue:
          $ref: '#/components/schemas/MonetaryAmount'
        active:
          description: Flag indicating whether the shipping method is active.
          type: boolean
        fees:
          $ref: '#/components/schemas/Fees'
        shippingTaxCode:
          description: Shipping method's tax code.
          type: string
        shippingGroupId:
          description: Shipping groups unique identifier.
          type: string
      required:
      - id
      - name
      - fees
    ZoneWithActualDeliveryWindows:
      type: object
      allOf:
      - $ref: '#/components/schemas/Zone'
      - type: object
        properties:
          actualDeliveryWindows:
            $ref: '#/components/schemas/ActualDeliveryWindows'
    LocalizedValue:
      oneOf:
      - type: string
        description: String value in the specified language.
        example: FedEx 2Day
      - type: object
        additionalProperties:
          type: string
        description: 'Map of translations in form of language:translation pairs.

          The keys (languages) should be ISO language codes.'
        example:
          en: FedEx 2Day
    TimeRange:
      title: Time range
      description: A `from` to `to` time range for which the object is valid
      type: object
      properties:
        startTime:
          pattern: ^(2[0-3]|[01]?[0-9]):([0-5]?[0-9])$
          type: string
          description: Time from which the object is valid, provided in local time (e.g. 10:00)
        endTime:
          pattern: ^(2[0-4]|[01]?[0-9]):([0-5]?[0-9])$
          type: string
          description: Time to which the object is valid, provided in local time (e.g. 10:00).
      required:
      - startTime
      - endTime
    errorMessage:
      title: error
      description: Schema for API specified errors.
      type: object
      properties:
        status:
          minimum: 100
          maximum: 599
          description: original HTTP error code, should be consistent with the response HTTP code
          type: integer
        type:
          pattern: '[a-z]+[a-z_]*[a-z]+'
          description: classification of the error type, lower case with underscore eg validation_failure
          type: string
        message:
          description: descriptive error message for debugging
          type: string
        moreInfo:
          type: string
          description: link to documentation to investigate further and finding support
        errorCode:
          type: string
          description: The error code which specify the problem
        details:
          description: list of problems causing this error
          type: array
          items:
            title: errorDetail
            description: schema for specific error cause
            anyOf:
            - type: string
            - type: object
              properties:
                field:
                  description: a bean notation expression specifying the element in request data causing the error, eg shipTo[0].country, this can be empty if violation was not field specific
                  type: string
                type:
                  pattern: '[a-z]+[a-z_]*[a-z]+'
                  description: classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.
                  type: string
                message:
                  description: descriptive error detail message for debugging
                  type: string
                moreInfo:
                  type: string
                  description: link to documentation to investigate further and finding support for error detail
      required:
      - status
      - type
    FindSiteRequest:
      title: Find site request payload
      description: Payload with parameters for price finding.
      type: object
      properties:
        postalCode:
          type: string
          description: Postal code containing numbers and/or letters.
        country:
          type: string
          description: ISO2 or ISO3 formatted country code.
      required:
      - postalCode
    ShipTo:
      title: ShipTo
      description: Collection of shipping destinations
      type: array
      items:
        $ref: '#/components/schemas/ShipToItem'
    Sites:
      title: Collection of sites.
      type: array
      items:
        $ref: '#/components/schemas/Site'
      description: ''
    Methods:
      title: Collection of shipping methods
      type: array
      items:
        $ref: '#/components/schemas/Method'
    Fees:
      title: Collection of fees
      type: array
      items:
        $ref: '#/components/schemas/Fee'
    ShipToItem:
      title: shipToItem
      description: Shipping destination containing country and postal code.
      type: object
      properties:
        country:
          type: string
          description: ISO2 or ISO3 formatted country code.
        postalCode:
          type: string
          description: PostalCode containing numbers and/or letters. Can be incomplete and followed by single '*' to match all the postalCodes starting with the same numbers/letters.
      required:
      - country
    MetaData:
      type: object
      properties:
        createdAt:
          type: string
          description: Date and time when the object was created, compliant with the ISO 8601 format.
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?([zZ]|([\+-])([01]\d|2[0-3]):?([0-5]\d)?)?$
        modifiedAt:
          type: string
          description: Date and time when the object was last modified, compliant with the ISO 8601 format.
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?([zZ]|([\+-])([01]\d|2[0-3]):?([0-5]\d)?)?$
        version:
          minimum: 1
          type: integer
    Site:
      title: Site
      description: A site is a specific virtual or real shop.
      type: object
      properties:
        id:
          description: Site unique identifier.
          type: string
        defaultZoneId:
          description: Default shippingzone’s unique identifier. A shipping zone is an area where shipments can be delivered.
          type: string
        zones:
          type: array
          items:
            $ref: '#/components/schemas/ZoneWithActualDeliveryWindows'
        metadata:
          $ref: '#/components/schemas/MetaData'
    ActualDeliveryWindows:
      title: Collection of actual delivery windows
      type: array
      items:
        $ref: '#/components/schemas/ActualDeliveryWindow'
    Fee:
      title: Fee
      description: Fee is a shipping cost for a given shipping method and parameters.
      type: object
      properties:
        cost:
          $ref: '#/components/schemas/MonetaryAmount'
        minOrderValue:
          $ref: '#/components/schemas/MonetaryAmount'
        shippingGroupId:
          description: Shipping group unique identifier.
          type: string
      required:
      - cost
      - minOrderValue
  responses:
    notFound_404:
      description: 'The requested resource does not exist.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            Not Found:
              value:
                status: 404
                message: The requested URI does not map to a single element resource.
                errorCode: ENTITY-GET-404001
                moreInfo: ''
                type: element_resource_non_existing
    unauthorized_401:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              fault:
                type: object
                properties:
                  faultstring:
                    type: string
                  detail:
                    type: object
                    properties:
                      errorcode:
                        type: string
          examples:
            Invalid access token:
              value:
                fault:
                  faultstring: Invalid access token
                  detail:
                    errorcode: oauth.v2.InvalidAccessToken
    yaasAware_400:
      description: Request syntactically incorrect. Details of the error are included in the response payload.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            Bad request:
              value:
                status: 400
                message: There are validation problems, see details section for more information
                moreInfo: ''
                type: validation_violation
                details:
                - field: tenant
                  message: size must be between 2 and 16
                  type: invalid_header
    internalError_500:
      description: 'Some server side error occurred.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            Internal Server Error:
              value:
                status: 500
                message: Something went wrong while processing the request. Please contact the administrator.
                errorCode: ENTITY-500001
                moreInfo: ''
                type: internal_service_error
  parameters:
    tenant:
      name: tenant
      in: path
      required: true
      description: 'Your Emporix tenant name.


        **Note**: The tenant should always be written in lowercase.

        '
      schema:
        pattern: ^[a-z][a-z0-9]+$
        minLength: 3
        maxLength: 16
        type: string
    windowsLimit:
      description: '* The **windowsLimit** parameter is optional.

        * The **windowsLimit** parameter determines the maximum amount of the nearest delivery windows that should be returned for each zone in retrieved sites.

        * If you do not set the **windowsLimit** parameter, there will be no delivery window arrays in the response.

        * If you set the **windowsLimit** parameter to 0, there will be empty delivery window arrays in the response.'
      name: windowsLimit
      in: query
      required: false
      schema:
        type: number
        minimum: 0
  securitySchemes:
    oAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.emporix.io/oauth/token
          scopes:
            shipping.shipping_manage: Needed to manage shipping settings.
            shipping.shipping_read: Needed to read shipping settings.
x-refined-from:
- emporix-shipping-openapi.yml
- emporix-shipping-openapi.yml