---
openapi: 3.0.1
info:
  title: API Equipment
  description: API specifications for API Equipment interface issued by SOGET. The
    output is the equipment information relating to the handling unit.
  contact:
    name: SOGET S.A.
    url: https://www.soget.fr/
    email: hello@soget.fr
  license:
    name: Copyright © SOGET
    url: https://www.soget.fr/
  version: v1
paths:
  "/equipments":
    get:
      operationId: filter-equipment
      tags:
      - Equipment
      summary: 'Filter the equipment information by reference or by S)ONE ID. '
      description: "Sample request :\r\n\r\n    GET /equipments?reference=AAAU1234566&spi=CNI1234567890&limit=5&offset=0&desc=true"
      parameters:
      - name: reference
        in: query
        description: Handling unit reference with which to filter.
        required: false
        style: form
        explode: true
        schema:
          type: string
          default: ''
      - name: spi
        in: query
        description: Handling unit ID with which to filter. ID corresponds to the
          single passage identificator in S)ONE.
        required: false
        style: form
        explode: true
        schema:
          type: string
          default: ''
      - name: desc
        in: query
        description: Boolean that indicates the sort order. If it is set to true,
          results will be sorted by descending order.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: false
      - name: limit
        in: query
        description: Number of results to be returned. Max value is 10.
        required: false
        style: form
        explode: true
        schema:
          maximum: 10
          type: integer
          format: int32
          default: 5
      - name: offset
        in: query
        description: Index of the first returned result.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          default: 0
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/EquipmentItemsResponseModel"
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/HttpBusinessError"
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/HttpBusinessError"
components:
  schemas:
    EquipmentItemsResponseModel:
      type: object
      properties:
        total:
          type: integer
          description: Total amount of objects matching given parameters.
          example: 3
        returned:
          type: integer
          description: Amount of objects returned by the paginated query.
          example: 1
        first:
          type: integer
          description: Index of the first returned object.
          example: 0
        items:
          type: array
          items:
            "$ref": "#/components/schemas/Equipment"
          description: Items returned by the query.
          nullable: true
      additionalProperties: false
      description: "Object containing several results returned by a query, along with
        additionnal information about the results.\r\n<br>Object result types : <br>-
        EquipmentItemsResponseModel :  List of returned equipments"
    Dimensions:
      type: object
      properties:
        length:
          "$ref": "#/components/schemas/Measure"
        width:
          "$ref": "#/components/schemas/Measure"
        height:
          "$ref": "#/components/schemas/Measure"
    Equipment:
      type: object
      properties:
        spi:
          type: string
          description: Equipment spi
        reference:
          type: string
          description: Equipment reference
        seals:
          type: array
          description: List of seals.
          items:
            "$ref": "#/components/schemas/Seal"
        measures:
          "$ref": "#/components/schemas/Measures"
        dimensions:
          "$ref": "#/components/schemas/Dimensions"
        supplier:
          type: string
    Seal:
      type: object
      properties:
        number:
          type: string
        origin:
          type: string
    HttpBusinessError:
      type: object
      properties:
        status:
          type: string
          description: Http error status.
          nullable: true
          example: NotFound
        timestamp:
          type: string
          description: "Error date.\r\n<br>ISO 8601 Extended Format"
          format: date-time
          example: '2022-11-17T15:40:39.838Z'
        code:
          type: string
          description: "Business error code.\r\n<br>The possible values are :<br>-
            R001 : No handling unit was found<br>- R002 : The handling unit is null<br>-
            R003 : The handling unit is not correctly formated"
          nullable: true
          example: R001
        message:
          type: string
          description: Error message.
          nullable: true
          example: No handling unit was found
      additionalProperties: false
      description: Business error management.
    Measure:
      type: object
      properties:
        value:
          type: number
          description: Measure value.
          format: decimal
        unit:
          maxLength: 5
          minLength: 0
          type: string
          description: Value which comes from the international system of units.
      description: "This object concerns the following fields :   \r\n<br>- Length
        (the default unit is MTR)<br>- Width (the default unit is MTR)<br>- Height
        (the default unit is MTR)<br>- Volume (the default unit is DMQ)"
    Measures:
      type: object
      properties:
        volume:
          "$ref": "#/components/schemas/Measure"
  securitySchemes:
    bearer_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
    api_key:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
x-topics:
- title: Get Started
  content: "# Format\n\nSoget API platform exposes RESTful APIs. \n\nOur API uses
    the HTTP methods to connect to our data sources. It returns responses in JSON
    format in UTF-8 encoding. It uses:\n\n- ISO-8601 format for date and time,\n-
    JSON object or JSON array in the body of POST and PUT methods,\n- *Application/json;
    charset=UTF-8* in the parameter *Content-Type* of the header\n\n# Parameters\n\nParameters
    must be passed:\n\n- in the URL’s query string for GET and DELETE requests;\n-
    in the request’s body for PUT and POST requests.\n\nIf the call requires other
    parameters, add them as well with the appropriate values.\n\nParameters passed
    in the **URL** must be properly URL-encoded, using UTF-8 encoding for non-ASCII
    characters. Also, the plus character (*+*) is interpreted as a space (so it’s
    an alternative to *%20*).  Unless otherwise stated, arrays passed in the URL can
    be specified either:\n\n-\tas a comma-separated string; example: *attributesToRetrieve=title,description*;
    or\n-\tas a JSON array (which must be properly URL-encoded, of course);\n  \n>
    __example__: *attributesToRetrieve=%5B%22title%22,%22description%22%5D*.\n\nArrays
    passed in the **body** should always be regular JSON arrays.\n\n# What You Need
    \n\nIn order to make requests, you must have an account and update your password.\n**THEN**,\n\n1.
    Create an organization\n2. Create a client application\n3. Retrieve your authentication
    tokens : [Authentication](#topic-authentication)\n4. Subscribe to an offer\n5.
    Retrieve your API Key : [Authentication](#topic-authentication) \n\n# Make your
    first request\n\nFor the first examples, you can use your terminal, with curl,
    sending the request.\n\nIt returns a JSON response like this:\n```json\n{\n    \"code\":
    \"CCGM\",\n    \"name\": \"CMA CGM\",\n    \"type\": \"FB\",\n    \"location\":
    \"FR\",\n    \"organization\": \"CMA CGM\"\n}\n```"
- title: Authentication
  content: "Soget API use double authentication to identify the application and the
    customer.\nThe first authentication is performed by the OAuth2 token to identify
    application and the second authentication is performed by the API key to identify
    the customer.\n\n# OAuth2 token\n\nTo authenticate your application, you need
    register for the API Portal and create an application.  \n\n- Get and use client_id
    and client_secret to get the $ACCESS_TOKEN\n- Use the $ACCESS_TOKEN to call our
    API services\n\nNote that the access token url is : https://soget-api-integration.azure-api.net/soget-connect/v1/openid-connect/token.\n\n#
    API Key\n\nTo authenticate the customer, you need register for the API Portal
    and subscribe to an offer.\n\n- Get and use the $API_KEY to call our API services\n\nNote,
    that you should use the $API_KEY in the `Ocp-Apim-Subscription-Key` header of
    your request."
  example: |-
    ## Request an access token

    ```
    curl -X POST https://soget-api-integration.azure-api.net/soget-connect/v1/openid-connect/token --data-urlencode "client_id=$YOUR_CLIENT_ID" --data-urlencode "client_secret=$YOUR_CLIENT_SECRET"
    ```

    ## Request an API
    ````
    curl \
      -X GET https://soget-api-integration.azure-api.net \
      -H "Authorization: Bearer $ACCESS_TOKEN"
      -H "Ocp-Apim-Subscription-Key: $API_KEY"
    ```
security:
- bearer_token: []
  api_key: []
servers:
- url: https://soget-api-integration.azure-api.net/api-equipment/v1