---
openapi: 3.0.1
info:
  title: API Tracing Libelle In Mass
  description: "API specifications for API Private Tracing Handling Units interface
    issued\r\n    by SOGET. The output of these services contains the meaning of the
    reference\r\n    datas coming from the S)ONE system."
  contact:
    name: SOGET S.A.
    url: https://www.soget.fr/
    email: hello@soget.fr
  license:
    name: Copyright © SOGET
    url: https://www.soget.fr/
  version: 1.0.0
paths:
  "/handling-units/search":
    get:
      tags:
      - HandlingUnits
      summary: Filter the list of handling-units linked to a shipment.
      description: "Sample request :\r\n\r\n    GET /handling-units/search?documentReference=3714238101"
      parameters:
      - name: documentReference
        in: query
        description: Announcement document reference.
        required: true
        schema:
          type: string
      - name: customsFlag
        in: query
        description: Type of flow.
        schema:
          "$ref": "#/components/schemas/CustomsFlag"
      - name: freightAgent
        in: query
        description: Agent code of shipping company.
        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.
        schema:
          type: boolean
          default: false
      - name: limit
        in: query
        description: Number of results to be returned. Max value is 10.
        schema:
          type: integer
          format: int32
          default: 5
      - name: offset
        in: query
        description: Index of the first returned result.
        schema:
          type: integer
          format: int32
          default: 0
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/HandlingUnitItemsResponseModel"
        '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:
    Actor:
      type: object
      properties:
        code:
          type: string
          description: Code of actor.
          nullable: true
        name:
          type: string
          description: Name of actor.
          nullable: true
      additionalProperties: false
      description: Actor referenced in the S)ONE application
    Actors:
      type: object
      properties:
        freightAgent:
          "$ref": "#/components/schemas/Actor"
        freightForwarder:
          "$ref": "#/components/schemas/Actor"
      additionalProperties: false
      description: Actors
    Country:
      type: object
      properties:
        name:
          type: string
          description: Name of country.
          nullable: true
        alphaCode3:
          type: string
          description: Three letter code of country.
          nullable: true
      additionalProperties: false
      description: Country information base on ISO 3166 standard.
    CustomsFlag:
      enum:
      - Unknown
      - Import
      - Export
      - Transhipment
      - Transit
      type: string
      description: 'List of possible customs flag information :   <br>- Unknown (undefined
        flag - default value)<br>- Import<br>- Export<br>- Transhipment<br>- Transit'
    DangerousCode:
      type: object
      properties:
        code:
          type: string
          description: Dangerous code
          nullable: true
        description:
          type: string
          description: Description of dangerous code
          nullable: true
      additionalProperties: false
      description: Dangerous Code which is based on Dangerous Goods List of UNECE
    DocumentType:
      type: object
      properties:
        code:
          type: number
          description: Code of the type of document.
          format: double
        name:
          type: string
          description: Name of the type of document
          nullable: true
      additionalProperties: false
      description: Actor referenced in the S)ONE application
    EmptyReturn:
      type: object
      properties:
        dueDate:
          type: string
          description: Due date  <br>ISO 8601 Extended Format
          format: date-time
          nullable: true
        finishDateEarliest:
          type: string
          description: Finish date earliest  <br>ISO 8601 Extended Format
          format: date-time
          nullable: true
        finishDateLatest:
          type: string
          description: Finish date latest  <br>ISO 8601 Extended Format
          format: date-time
          nullable: true
      additionalProperties: false
      description: Empty return  information.
    EventInformation:
      type: object
      properties:
        eventWay:
          "$ref": "#/components/schemas/Way"
        eventType:
          "$ref": "#/components/schemas/EventType"
        eventDate:
          type: string
          description: Event date.  <br>ISO 8601 Extended Format
          format: date-time
          nullable: true
        eventPlace:
          "$ref": "#/components/schemas/Location"
        eventLocation:
          "$ref": "#/components/schemas/Location"
        eventTransportMode:
          "$ref": "#/components/schemas/TransportMode"
      additionalProperties: false
      description: An event corresponds to a movement or an authorization on the handling
        unit, occured on a location.
    EventType:
      type: object
      properties:
        code:
          type: string
          description: Code of event.
          nullable: true
        name:
          type: string
          description: Name of event.
          nullable: true
      additionalProperties: false
      description: Type of events defined in the S)ONE application.
    FreightFamily:
      enum:
      - Container
      - BreakBulk
      - SolidBulk
      - LiquidBulk
      - MobileUnits
      type: string
      description: 'The freight family handled by this service is only Container and
        Breakbulk.  <br>- Container : Toys, televisions, DVDs, clothing, meat and
        computers; containers are the best way to transport these and many similar
        products. By efficiently loading the goods, they can be transported simultaneously
        in large quantities. The standard sizes mean containers fit on sea-going vessels,
        lorries, inland barges and train wagons.<br>- BreakBulk : Paper, wood, bags
        of cocoa, rolls of steel, parts of wind turbines; these are all products that
        can be transported in a container or simply put on a vessel.'
    HandlingUnit:
      type: object
      properties:
        freightFamily:
          "$ref": "#/components/schemas/FreightFamily"
        customsFlag:
          "$ref": "#/components/schemas/CustomsFlag"
        reference:
          type: string
          description: Handling unit reference.  <br>e.g. if the handling unit is
            an an equipment, this reference should follow the BIC ISO Container Identification
            Number where possible.
          nullable: true
        pswId:
          type: string
          description: Internal identifier of the handling unit.  <br>This unique
            identifier is composed of a prefix(3 characters) and a number(10 digits).
          nullable: true
        sizeType:
          "$ref": "#/components/schemas/SizeType"
        packagingCode:
          "$ref": "#/components/schemas/PackagingCode"
        measures:
          "$ref": "#/components/schemas/Measures"
        indicators:
          "$ref": "#/components/schemas/Indicators"
        references:
          type: array
          items:
            "$ref": "#/components/schemas/Reference"
          description: 'Linked references. This reference should be :  <br>a sequence
            number for export process,<br>a rank reference for export process.'
          nullable: true
        huLocation:
          "$ref": "#/components/schemas/HuLocation"
        actors:
          "$ref": "#/components/schemas/Actors"
        temperatures:
          "$ref": "#/components/schemas/Temperatures"
        shipments:
          type: array
          items:
            "$ref": "#/components/schemas/Shipment"
          description: Shipments information.  <br>This corresponds to the documentary
            information related to the handling unit, such as booking or bill of lading
            information.
          nullable: true
        transport:
          "$ref": "#/components/schemas/Transport"
        events:
          type: array
          items:
            "$ref": "#/components/schemas/EventInformation"
          description: Events information.
          nullable: true
        hazardousItems:
          type: array
          items:
            "$ref": "#/components/schemas/HazardousItem"
          description: Hazardous information.
          nullable: true
        emptyReturn:
          "$ref": "#/components/schemas/EmptyReturn"
      additionalProperties: false
      description: Handling unit information  <br>An handling unit corresponds to
        a container or a good.
    HandlingUnitItemsResponseModel:
      type: object
      properties:
        total:
          type: integer
          description: Total amount of objects matching given parameters.
          format: int32
        returned:
          type: integer
          description: Amount of objects returned by the paginated query.
          format: int32
        first:
          type: integer
          description: Index of the first returned object.
          format: int32
        items:
          type: array
          items:
            "$ref": "#/components/schemas/HandlingUnit"
          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.
    HazardousItem:
      type: object
      properties:
        imoClass:
          "$ref": "#/components/schemas/DangerousCode"
        limitedQuantity:
          type: boolean
          description: Limited quantity
          nullable: true
      additionalProperties: false
      description: Hazardous item.
    HttpBusinessError:
      type: object
      properties:
        status:
          type: string
          description: Http error status.
          nullable: true
        timestamp:
          type: string
          description: Error date.  <br>ISO 8601 Extended Format
          format: date-time
        code:
          type: string
          description: 'Business error code.  <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
        message:
          type: string
          description: Error message.
          nullable: true
      additionalProperties: false
      description: Business error management.
    HuLocation:
      type: object
      properties:
        place:
          "$ref": "#/components/schemas/Location"
        location:
          "$ref": "#/components/schemas/Location"
      additionalProperties: false
      description: Current location information
    Indicators:
      type: object
      properties:
        hazardous:
          type: boolean
          description: Hazardous indicator.
        empty:
          type: boolean
          description: Indicator to denote whether the equipment is empty or laden.   <br>Applicable
            for the container only.
        reefer:
          type: boolean
          description: Reefer indicator.
        pollutant:
          type: boolean
          description: Pollutant indicator.
        fumigation:
          type: boolean
          description: Fumigation indicator.
        quarantine:
          type: boolean
          description: Quarantine indicator.
        outOfGauge:
          type: boolean
          description: Out of Gauge indicator.
      additionalProperties: false
      description: Handling unit indicators.
    Location:
      type: object
      properties:
        code:
          type: string
          description: Code of location.
          nullable: true
        name:
          type: string
          description: Name of location.
          nullable: true
      additionalProperties: false
      description: Locations represented ports, airports, warehouse, berth, ... referenced
        in the S)ONE application.
    MeansIdType:
      enum:
      - IMONumber
      - CallSign
      - IATA
      - ICAO
      type: string
      description: 'Means identifier type. The possible values are :   <br>- IMONumber
        for maritime transport<br>- CallSign for maritime transport'
    Measure:
      type: object
      properties:
        value:
          type: number
          description: Measure value.
          format: double
          nullable: true
        unit:
          type: string
          description: Value which comes from the international system of units.
          nullable: true
      additionalProperties: false
      description: 'This object concerns the following fields :     <br>- GrossWeight
        (the default unit is KGM)<br>- Tare (the default unit is KGM)<br>- NetWeight
        (the default unit is KGM)<br>- Volume (the default unit is DMQ)'
    Measures:
      type: object
      properties:
        quantity:
          type: integer
          description: Number of packages.
          format: int32
          nullable: true
        weight:
          "$ref": "#/components/schemas/Weight"
        volume:
          "$ref": "#/components/schemas/Measure"
        remainingQuantity:
          type: integer
          description: Number of packages remaining at current location.  <br>This
            field is used in the context of partial reports.<br>Applicable for breakbulk
            only.
          format: int32
          nullable: true
        availableQuantity:
          type: integer
          description: Number of packages available at current location.  <br>This
            field is used in the context of partial reports.<br>Applicable for breakbulk
            only.
          format: int32
          nullable: true
        reportedQuantity:
          type: integer
          description: Number of package reported reported at current location.  <br>This
            field is used in the context of partial reports.<br>Applicable for breakbulk
            only.
          format: int32
          nullable: true
        remainingWeight:
          "$ref": "#/components/schemas/Measure"
      additionalProperties: false
      description: Handling unit measures.
    PackagingCode:
      type: object
      properties:
        code:
          type: string
          description: Code of packaging
          nullable: true
        description:
          type: string
          description: Description of packaging
          nullable: true
      additionalProperties: false
      description: 'Packaging codes which are based on : <br> ADR standards for road
        mode <br> RID standards for rail mode <br>IMDG/IMO standards for maritime
        mode <br>ADN standards for inland water mode <br>IATA/ICAO standards for air
        mode'
    ProcessingIndicator:
      enum:
      - Unknown
      - Transit
      - Transhipment
      - Import
      - Export
      type: string
      description: 'List of possible processing indicator :   <br>- Unknown (undefined
        flag - default value)<br>- Import<br>- Export<br>- Transhipment<br>- Transit'
    Reference:
      type: object
      properties:
        type:
          "$ref": "#/components/schemas/ReferenceType"
        value:
          type: string
          description: Value of reference.
          nullable: true
      additionalProperties: false
      description: References linked to the handling unit  <br> e.g. for process export,
        the equipment can be identified by the sequence number.
    ReferenceType:
      enum:
      - Rank
      - SequenceNumber
      type: string
      description: 'Type of references which identified the handling unit. The possible
        values are :   <br>- Rank and SequenceNumber for export procedure'
    Shipment:
      type: object
      properties:
        processingIndicator:
          "$ref": "#/components/schemas/ProcessingIndicator"
        documentReference:
          type: string
          description: Reference of document that links to a shipment.  <br>e.g. the
            reference should be a bill of lading number
          nullable: true
        documentId:
          type: string
          description: S)ONE ID of document.  <br>This unique identifier is composed
            of a prefix (3 characters) and a number (10 digits).>
          nullable: true
        documentType:
          "$ref": "#/components/schemas/DocumentType"
        documentDate:
          type: string
          description: Date of document.  <br>ISO 8601 Extended Format
          format: date-time
          nullable: true
        originLocation:
          "$ref": "#/components/schemas/Unlocode"
        destinationLocation:
          "$ref": "#/components/schemas/Unlocode"
        merchantHaulage:
          type: boolean
          description: Indicator specifying that the freight forwarder may modify
            the shipment.
          nullable: true
      additionalProperties: false
      description: Shipment item.
    SizeType:
      type: object
      properties:
        code:
          type: string
          description: A 4 digit Alpha Numeric Code uniquely describing the container.
          nullable: true
        description:
          type: string
          description: Description of the Container Type.
          nullable: true
      additionalProperties: false
      description: Size type information.
    Temperatures:
      type: object
      properties:
        setPoint:
          type: number
          description: Set point temperature.  <br>The default unit is C.
          format: double
          nullable: true
        rangeMin:
          type: number
          description: Min temperature.  <br>The default unit is C.
          format: double
          nullable: true
        rangeMax:
          type: number
          description: Max temperature.  <br>The default unit is C.
          format: double
          nullable: true
      additionalProperties: false
      description: Temperature information.
    Transport:
      type: object
      properties:
        meansName:
          type: string
          description: Transport means name.
          nullable: true
        voyageId:
          type: string
          description: S)ONE ID of the voyage.  <br>This unique identifier is composed
            of a prefix (3 characters) and a number (10 digits).
          nullable: true
        mode:
          "$ref": "#/components/schemas/TransportMode"
        meansNationality:
          "$ref": "#/components/schemas/Country"
        voyageDates:
          "$ref": "#/components/schemas/TransportDate"
        schedulePlace:
          "$ref": "#/components/schemas/Unlocode"
        transportMeansType:
          "$ref": "#/components/schemas/TransportMeansType"
        meansId:
          type: array
          items:
            "$ref": "#/components/schemas/TransportMeansIdentifier"
          description: Transport means identifier.
          nullable: true
        arrivalScheduleReference:
          type: string
          description: Arrival reference.
          nullable: true
        departureScheduleReference:
          type: string
          description: Departure reference.
          nullable: true
      additionalProperties: false
      description: Transport information.
    TransportDate:
      type: object
      properties:
        eta:
          type: string
          description: Estimated Time of Arrival is the time when a ship, vehicle,
            aircraft, cargo, emergency service or person is expected to arrive at
            its destination.  <br>ISO 8601 Extended Format
          format: date-time
          nullable: true
        etd:
          type: string
          description: Estimated Time of Departure is the time when a ship, vehicle,
            aircraft, cargo, emergency service or person is expected to depart from
            its point of origin.  <br>ISO 8601 Extended Format
          format: date-time
          nullable: true
        ata:
          type: string
          description: Actual Time of Arrival is the time that a vessel or any other
            mode of transportation is determined to arrive at its destination.  <br>ISO
            8601 Extended Format
          format: date-time
          nullable: true
        atd:
          type: string
          description: Actual Time of Departure is the time that a vessel or any other
            mode of transportation is determined to depart from its point of origin.  <br>ISO
            8601 Extended Format
          format: date-time
          nullable: true
      additionalProperties: false
      description: Transport dates
    TransportMeansIdentifier:
      type: object
      properties:
        type:
          "$ref": "#/components/schemas/MeansIdType"
        name:
          type: string
          description: Name of means id
          nullable: true
      additionalProperties: false
      description: The mean identifier for the transport,  <br> e.g. when the mode
        of transport is a vessel, the transport mean identifier would be the vessel
        IMO number.
    TransportMeansType:
      type: object
      properties:
        code:
          type: string
          description: Code of means type.
          nullable: true
        name:
          type: string
          description: Name of the means type.
          nullable: true
          example: vehicle carrier
      additionalProperties: false
      description: Transport means type
    TransportMode:
      type: object
      properties:
        code:
          type: number
          description: Transport mode code.
          format: double
          nullable: true
        name:
          type: string
          description: Transport mode name.
          nullable: true
      additionalProperties: false
      description: TransportMode
    Unlocode:
      type: object
      properties:
        code:
          type: string
          description: UN/LOCODE have length of 5 - combination of Country code (length
            of 2) and Location code (length of 3)
          nullable: true
        name:
          type: string
          description: Name of location.
          nullable: true
      additionalProperties: false
      description: UN/LOCODE information is based on recommendation 16 UN/LOCODE.
    Way:
      enum:
      - In
      - Out
      - Undefined
      type: string
      description: Way of the movement on the location
    Weight:
      type: object
      properties:
        tare:
          "$ref": "#/components/schemas/Measure"
        grossWeight:
          "$ref": "#/components/schemas/Measure"
        netWeight:
          "$ref": "#/components/schemas/Measure"
      additionalProperties: false
      description: 'Weight (the default unit is KGM) :   <br>- GrossWeight<br>- Tare
        : applicable for container only<br>- NetWeight'
  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-tracing-libelle-in-mass/v1