Topi shipment API

openapi: 3.0.3
info:
  title: topi Seller catalog shipment API
  description: '# Localization


    Strings returned can be localized when the _Accept-Language_ header is provided in the request. It should follow the [RFC-2616 convention](http://www.ietf.org/rfc/rfc2616.txt).

    '
  version: 1.0.0
servers:
- url: https://seller-api-sandbox.topi-sandbox.eu
- url: https://seller-api.topi.eu
- url: https://seller-api.topi-staging.eu
- url: https://seller-api-sandbox.topi-sandbox-staging.eu
tags:
- name: shipment
  description: '#### Assets without serial numbers


    Some assets might not have a serial number (e.g. accessories). In order to send them with the shipment, explicitly pass an empty string `""` as the `serial_number` for this asset.


    > Note, that every asset, that has a **rent option**, requires a serial number even if it has been directly purchased. The request will fail with an according message if such a serial number is missing.


    > Also note, that every item of an order has to be shipped for the order to be completed. This can be done in multiple shipments.'
paths:
  /v1/shipment:
    post:
      tags:
      - shipment
      summary: Create a shipment
      description: Add shipment info for an order. Partial shipments are allowed and will update the order status to "partially_fulfilled". All items must have shipment info before an order is considered "completed".
      operationId: shipment#create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRequestBody'
            example:
              metadata:
                tracking_number: '123456'
              order_id: 739b63c2-9e58-4964-b38d-4ebb424de242
              serial_numbers:
              - seller_product_reference:
                  reference: 123ab-5343
                  source: sap
                serial_number: BA-3456786-334-9
              tracking_url: https://example.com/foo
      responses:
        '200':
          description: OK response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
              example:
                metadata:
                  tracking_number: '123456'
                serial_numbers:
                - seller_product_reference:
                    reference: 123ab-5343
                    source: sap
                  serial_number: BA-3456786-334-9
                tracking_url: https://example.com/foo
        '400':
          description: 'BadRequest: Bad Request response.'
          content:
            application/vnd.goa.error:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'Unauthorized: Unauthorized response.'
          content:
            application/json:
              schema:
                type: string
                example: abc123
              example: abc123
        '403':
          description: 'InvalidScopes: Forbidden response.'
          content:
            application/json:
              schema:
                type: string
                example: abc123
              example: abc123
        '404':
          description: 'NotFound: Not Found response.'
          content:
            application/vnd.goa.error:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - OAuth2Seller_header_Authorization:
        - seller-shipment:edit
      x-code-samples:
      - lang: curl
        label: cURL
        source: "curl -X POST https://seller-api.topi.eu/v1/shipment \\\n  -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"metadata\": {\n    \"tracking_number\": \"123456\"\n  },\n  \"order_id\": \"739b63c2-9e58-4964-b38d-4ebb424de242\",\n  \"serial_numbers\": [\n    {\n      \"seller_product_reference\": {\n        \"reference\": \"123ab-5343\",\n        \"source\": \"sap\"\n      },\n      \"serial_number\": \"BA-3456786-334-9\"\n    }\n  ],\n  \"tracking_url\": \"https://example.com/foo\"\n}'\n"
      - lang: javascript
        label: JavaScript (fetch)
        source: "const response = await fetch('https://seller-api.topi.eu/v1/shipment', {\n  method: 'POST',\n  headers: {\n    'Authorization': `Bearer ${ACCESS_TOKEN}`,\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify({\n  \"metadata\": {\n    \"tracking_number\": \"123456\"\n  },\n  \"order_id\": \"739b63c2-9e58-4964-b38d-4ebb424de242\",\n  \"serial_numbers\": [\n    {\n      \"seller_product_reference\": {\n        \"reference\": \"123ab-5343\",\n        \"source\": \"sap\"\n      },\n      \"serial_number\": \"BA-3456786-334-9\"\n    }\n  ],\n  \"tracking_url\": \"https://example.com/foo\"\n})\n});\n\nconst data = await response.json();\nconsole.log(data);\n"
components:
  schemas:
    Shipment:
      type: object
      properties:
        metadata:
          type: object
          description: Metadata that you can attach to an order. You can store any JSON information.
          example:
            tracking_number: '123456'
          additionalProperties:
            type: string
            example: aaa
            maxLength: 400
        serial_numbers:
          type: array
          items:
            $ref: '#/components/schemas/SerialNumberByAsset'
          description: The products' serial numbers to register
          example:
          - seller_product_reference:
              reference: 123ab-5343
              source: sap
            serial_number: BA-3456786-334-9
        tracking_url:
          type: string
          description: The tracking URL of the asset
          example: https://example.com/foo
          format: uri
      example:
        metadata:
          tracking_number: '123456'
        serial_numbers:
        - seller_product_reference:
            reference: 123ab-5343
            source: sap
          serial_number: BA-3456786-334-9
        tracking_url: https://example.com/foo
      required:
      - serial_numbers
    SerialNumberByAsset:
      type: object
      properties:
        seller_product_reference:
          $ref: '#/components/schemas/SellerProductReference'
        serial_number:
          type: string
          description: The serial number given by the device manufacturer, usually found on the packaging
          example: BA-3456786-334-9
      example:
        seller_product_reference:
          reference: 123ab-5343
          source: sap
        serial_number: BA-3456786-334-9
      required:
      - seller_product_reference
      - serial_number
    CreateRequestBody:
      type: object
      properties:
        metadata:
          type: object
          description: Metadata that you can attach to an order. You can store any JSON information.
          example:
            tracking_number: '123456'
          additionalProperties:
            type: string
            example: aaa
            maxLength: 400
        order_id:
          type: string
          description: topi order ID
          example: 739b63c2-9e58-4964-b38d-4ebb424de242
          format: regexp
          pattern: ^[0-9A-Za-z\-]+$
        serial_numbers:
          type: array
          items:
            $ref: '#/components/schemas/SerialNumberByAsset'
          description: The products' serial numbers to register
          example:
          - seller_product_reference:
              reference: 123ab-5343
              source: sap
            serial_number: BA-3456786-334-9
        tracking_url:
          type: string
          description: The tracking URL of the asset
          example: https://example.com/foo
          format: uri
      example:
        metadata:
          tracking_number: '123456'
        order_id: 739b63c2-9e58-4964-b38d-4ebb424de242
        serial_numbers:
        - seller_product_reference:
            reference: 123ab-5343
            source: sap
          serial_number: BA-3456786-334-9
        tracking_url: https://example.com/foo
      required:
      - order_id
      - serial_numbers
    SellerProductReference:
      type: object
      properties:
        reference:
          type: string
          description: The ID related with the source. This value should be unique for that source.
          example: 123ab-5343
          pattern: '[a-zA-Z0-9._-]'
          minLength: 1
        source:
          type: string
          description: The seller internal source name for this reference type.
          example: sap
          minLength: 1
      example:
        reference: 123ab-5343
        source: sap
      required:
      - source
      - reference
    Error:
      type: object
      properties:
        fault:
          type: boolean
          description: Is the error a server-side fault?
          example: false
        id:
          type: string
          description: ID is a unique identifier for this particular occurrence of the problem.
          example: 123abc
        message:
          type: string
          description: Message is a human-readable explanation specific to this occurrence of the problem.
          example: parameter 'p' must be an integer
        name:
          type: string
          description: Name is the name of this class of errors.
          example: bad_request
        temporary:
          type: boolean
          description: Is the error temporary?
          example: false
        timeout:
          type: boolean
          description: Is the error a timeout?
          example: false
      example:
        fault: false
        id: 123abc
        message: parameter 'p' must be an integer
        name: bad_request
        temporary: false
        timeout: false
      required:
      - name
      - id
      - message
      - temporary
      - timeout
      - fault
  securitySchemes:
    OAuth2Seller_header_Authorization:
      type: oauth2
      description: 'Read our [Integration Guide](https://docs.topi.eu/docs/integration-guide/authentication) for detailed instructions on how to authenticate.

        '
      flows:
        clientCredentials:
          tokenUrl: https://identity.topi.eu/oauth2/token
          refreshUrl: https://identity.topi.eu/oauth2/token
          scopes:
            seller-branding:read: read seller branding config
            seller-catalog:edit: add product to catalog
            seller-catalog:read: view and search catalog
            seller-metrics:read: read metrics urls
            seller-offer:edit: edit offer details
            seller-offer:read: read offer details
            seller-order:edit: edit order details
            seller-order:read: read order details
            seller-scenario-simulations:run: run scenario simulations
            seller-shipment:edit: edit shipment details
            seller-shipping-method:edit: edit seller shipping method details
            seller-shipping-method:read: read seller shipping method details
            user-info:read: read user info