openapi: 3.0.1
info:
  title: Order Management
  description: Documentation of the 1NCE API for Order Management.
  contact:
    name: 1NCE GmbH
    url: https://1nce.com
    email: info@1nce.com
  version: v2.0
servers:
- url: https://api.1nce.com/management-api
tags:
- name: Orders
  description: Order Management
paths:
  /v1/orders:
    get:
      tags:
      - Orders
      summary: Get All Orders
      description: Get a complete list of all 1NCE orders for the given account.
      operationId: getOrdersUsingGET
      parameters:
      - name: page
        in: query
        description: Number index of the requested order list page.  Use this parameter to iterate through all orders on the
          different pages. The total amount of pages is listed in the response header.
        allowEmptyValue: false
        schema:
          minimum: 1
          exclusiveMinimum: false
          type: integer
          default: 1
      - name: pageSize
        in: query
        description: Defines the size of a page, the number of individual orders listed on one page. The maximum allowed value
          is 10.
        allowEmptyValue: false
        schema:
          maximum: 10
          exclusiveMaximum: false
          minimum: 1
          exclusiveMinimum: false
          type: integer
          default: 10
      - name: sort
        in: query
        description: Sort the order list by specific keys (order_number, order_status and/or order_date) in a comma seperated
          list. The default is order_number if no paramter is given.
        allowEmptyValue: false
        schema:
          type: string
          default: order_number
          example: order_status,order_date
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
            application/json;charset=UTF-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
      deprecated: false
      security:
      - BearerAuthentication: []
    post:
      tags:
      - Orders
      summary: Create Order
      description: Trigger an order using a POST request.
      operationId: postOrderUsingPOST
      requestBody:
        description: Detail prameters about the to be placed order.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Additional_Order'
          application/json;charset=UTF-8:
            schema:
              $ref: '#/components/schemas/Additional_Order'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Additional_Order'
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/Additional_Order'
        '201':
          description: Created
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
      deprecated: false
      security:
      - BearerAuthentication: []
      x-codegen-request-body-name: order
  /v1/orders/{order_number}:
    get:
      tags:
      - Orders
      summary: Get Single Order
      description: Get a single Order, identified by its order_number.
      operationId: getOrderUsingGET
      parameters:
      - name: order_number
        in: path
        description: Order number identifying one specific order.
        required: true
        schema:
          type: integer
        example: 1234
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
      deprecated: false
      security:
      - BearerAuthentication: []
components:
  schemas:
    Additional_Order:
      title: Additional Order
      required:
      - products
      type: object
      properties:
        products:
          type: array
          description: The specific products to be ordered.
          items:
            $ref: '#/components/schemas/Ordered_product'
        delivery_address:
          $ref: '#/components/schemas/DeliveryAddress'
        customer_reference:
          type: string
          description: Optional customer-specific reference for the order.
          example: <customer_reference>
      description: Parameters of the order to be placed.
    DeliveryAddress:
      title: Delivery Address
      type: object
      properties:
        salutation:
          type: string
          description: Salutation, supported values are '1' for 'Mr' and '2' for 'Ms'.
          default: '1'
          enum:
          - '1'
          - '2'
        first_name:
          type: string
          description: First Name
        last_name:
          type: string
          description: Last Name
        company:
          type: string
          description: Company Name
        street:
          type: string
          description: Street Name
        address_line2:
          type: string
          description: Second Address Line
        house_number:
          type: string
          description: House Number
        zip:
          type: string
          description: ZIP Code
        city:
          type: string
          description: City
        country:
          type: string
          description: ISO 3166-1 Alpha-2 Country Code
          example: DE
        phone:
          type: string
          description: Phone Number with international prefix.
      description: Address where the products of the order should be delivered to. If no additional address is provided here,
        the ordered products will be sent to the existing single delivery address. If more than one default delivery address
        is configured in the 1NCE organization, please provide a valid shipping address in the order request.
    Link:
      title: Link
      type: object
      properties:
        rel:
          type: string
          description: Relation of SIM link.
          example: self
        href:
          type: string
          description: Link for getting details about the specific SIM.
          example: https://api.1nce.com/api/v1/sims/9999999999000000001
    Order:
      title: Order
      type: object
      properties:
        order_number:
          type: number
          description: Order Number, a unique numerical identifier for a order.
          example: 2000000001
        order_type:
          type: string
          description: The order type indicates whether this is a first order, additional order or a topup.
          example: FIRST_ORDER
          enum:
          - FIRST_ORDER
          - ADDITIONAL_ORDER
          - TOPUP
          - BULK_TOPUP
          - TARIFF_CHANGE
        order_date:
          type: string
          description: Date when the order was placed.
          format: date-time
        order_status:
          type: string
          description: Current status of the ordering process.
          example: COMPLETED
        invoice_number:
          type: string
          description: Invoice Number, a unique alphanumerical identifier for the corresponding order invoice.
          example: '20000002'
        invoice_amount:
          type: string
          description: The gross value which this order amounts to, as printed on the invoice.
          example: '19.99'
        currency:
          type: string
          description: ISO 4217 currency code used for the invoice amount.
          example: EUR
        shipping_address:
          $ref: '#/components/schemas/DeliveryAddress'
        sims:
          type: array
          description: List of SIMs included or affected by this order.
          items:
            $ref: '#/components/schemas/SIM'
        products:
          type: array
          description: Product id and quantity of ordered products.
          items:
            $ref: '#/components/schemas/Product_information'
      description: Detailed information about an order.
    Ordered_product:
      title: Product Order
      type: object
      properties:
        productId:
          type: integer
          description: Specific id of the product to be ordered. For reference, check past orders or the product API call
            for avaliable product ids.
          example: 1001
        quantity:
          minimum: 1
          type: integer
          description: Quantity to be ordered of the given product.
      description: Product id and order quantity of the specific product.
    Product_information:
      title: Product Information
      type: object
      properties:
        product_id:
          type: integer
          description: Specific id of the product ordered. For reference, check past orders or the product API call for avaliable
            product ids.
          example: 1001
        quantity:
          type: integer
          description: Quantity of SIMs with this product id ordered.
          example: 1
      description: General information about an ordered product
    SIM:
      title: SIM
      type: object
      properties:
        iccid:
          type: string
          description: ICCID of a specific 1NCE SIM.
          example: '8988280666000000000'
        _links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
      description: Details about a 1NCE SIM card.
  securitySchemes:
    BearerAuthentication:
      type: http
      scheme: bearer
      description: Bearer Authentication Token used to gain access to the 1NCE API. Please refer to the Open Authorization
        (/oauth/token) request for obtaining a Bearer Token.
x-readme:
  explorer-enabled: true
  proxy-enabled: true