Filter handling units by reference or by S)ONE ID and get a list of handling units : general information, information on shipments, transports and events. An handling unit corresponds to a container or a good.

GET /handling-units

Sample request :

GET /handling-units?reference=AAAU1234566&spi=CNI1234567890&limit=5&offset=0&desc=true

Query parameters

  • reference string

    Handling unit reference with which to filter.

    Default value is empty.

  • spi string

    Handling unit ID with which to filter. ID corresponds to the single passage identificator in S)ONE.

    Default value is empty.

  • desc boolean

    Boolean that indicates the sort order. If it is set to true, results will be sorted by descending order.

    Default value is false.

  • limit integer(int32)

    Number of results to be returned. Max value is 10.

    Maximum value is 10. Default value is 5.

  • offset integer(int32)

    Index of the first returned result.

    Default value is 0.

Responses

  • 200 application/json

    Success

    Hide response attributes Show response attributes object
    • total integer(int32)

      Total amount of objects matching given parameters.

    • returned integer(int32)

      Amount of objects returned by the paginated query.

    • first integer(int32)

      Index of the first returned object.

    • items array[object] | null

      Handling unit information
      An handling unit corresponds to a container or a good.

      Handling unit information
      An handling unit corresponds to a container or a good.

      Hide items attributes Show items attributes object
      • reference string | null

        Handling unit reference.
        e.g. if the handling unit is an an equipment, this reference should follow the BIC ISO Container Identification Number where possible.

      • pswId string | null

        Internal identifier of the handling unit.
        This unique identifier is composed of a prefix(3 characters) and a number(10 digits).

      • freightFamily string

        The freight family handled by this service is only Container and Breakbulk.
        - 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.
        - 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.

        Values are Container, BreakBulk, SolidBulk, LiquidBulk, or MobileUnits.

      • sizeType object

        Size type information.

        Hide sizeType attributes Show sizeType attributes object
        • code string

          A 4 digit Alpha Numeric Code uniquely describing the container.

          Minimum length is 4, maximum length is 4.

        • description string

          Description of the Container Type.

          Maximum length is 256.

      • packagingCode object

        Packaging codes which are based on :
        ADR standards for road mode
        RID standards for rail mode
        IMDG/IMO standards for maritime mode
        ADN standards for inland water mode
        IATA/ICAO standards for air mode

        Hide packagingCode attributes Show packagingCode attributes object
        • code string

          Code of packaging

          Minimum length is 2, maximum length is 2.

        • description string

          Description of packaging

          Maximum length is 100.

      • measures object

        Handling unit measures.

        Hide measures attributes Show measures attributes object
        • quantity integer(int32) | null

          Number of packages.

        • weight object

          Weight (the default unit is KGM) :
          - GrossWeight
          - Tare : applicable for container only
          - NetWeight

          Hide weight attributes Show weight attributes object
          • tare object

            This object concerns the following fields :

            - GrossWeight (the default unit is KGM)
            - Tare (the default unit is KGM)
            - NetWeight (the default unit is KGM)
            - Volume (the default unit is DMQ)

            Hide tare attributes Show tare attributes object
            • value number(double) | null

              Measure value.

            • unit string | null

              Value which comes from the international system of units.

              Minimum length is 0, maximum length is 5.

            • Additional properties are NOT allowed
          • grossWeight object

            This object concerns the following fields :

            - GrossWeight (the default unit is KGM)
            - Tare (the default unit is KGM)
            - NetWeight (the default unit is KGM)
            - Volume (the default unit is DMQ)

            Hide grossWeight attributes Show grossWeight attributes object
            • value number(double) | null

              Measure value.

            • unit string | null

              Value which comes from the international system of units.

              Minimum length is 0, maximum length is 5.

            • Additional properties are NOT allowed
          • netWeight object

            This object concerns the following fields :

            - GrossWeight (the default unit is KGM)
            - Tare (the default unit is KGM)
            - NetWeight (the default unit is KGM)
            - Volume (the default unit is DMQ)

            Hide netWeight attributes Show netWeight attributes object
            • value number(double) | null

              Measure value.

            • unit string | null

              Value which comes from the international system of units.

              Minimum length is 0, maximum length is 5.

            • Additional properties are NOT allowed
          • Additional properties are NOT allowed
        • volume object

          This object concerns the following fields :

          - GrossWeight (the default unit is KGM)
          - Tare (the default unit is KGM)
          - NetWeight (the default unit is KGM)
          - Volume (the default unit is DMQ)

          Hide volume attributes Show volume attributes object
          • value number(double) | null

            Measure value.

          • unit string | null

            Value which comes from the international system of units.

            Minimum length is 0, maximum length is 5.

          • Additional properties are NOT allowed
        • remainingQuantity integer(int32) | null

          Number of packages remaining at current location.
          This field is used in the context of partial reports.
          Applicable for breakbulk only.

        • availableQuantity integer(int32) | null

          Number of packages available at current location.
          This field is used in the context of partial reports.
          Applicable for breakbulk only.

        • reportedQuantity integer(int32) | null

          Number of package reported reported at current location.
          This field is used in the context of partial reports.
          Applicable for breakbulk only.

        • remainingWeight object

          This object concerns the following fields :

          - GrossWeight (the default unit is KGM)
          - Tare (the default unit is KGM)
          - NetWeight (the default unit is KGM)
          - Volume (the default unit is DMQ)

          Hide remainingWeight attributes Show remainingWeight attributes object
          • value number(double) | null

            Measure value.

          • unit string | null

            Value which comes from the international system of units.

            Minimum length is 0, maximum length is 5.

          • Additional properties are NOT allowed
        • Additional properties are NOT allowed
      • indicators object

        Handling unit indicators.

        Hide indicators attributes Show indicators attributes object
        • hazardous boolean

          Hazardous indicator.

        • empty boolean

          Indicator to denote whether the equipment is empty or laden.
          Applicable for the container only.

        • reefer boolean

          Reefer indicator.

        • pollutant boolean

          Pollutant indicator.

        • fumigation boolean

          Fumigation indicator.

        • quarantine boolean

          Quarantine indicator.

        • outOfGauge boolean

          Out of Gauge indicator.

        • Additional properties are NOT allowed
      • references array[object]

        References linked to the handling unit
        e.g. for process export, the equipment can be identified by the sequence number.

        References linked to the handling unit
        e.g. for process export, the equipment can be identified by the sequence number.

        Hide references attributes Show references attributes object
        • type string

          Type of references which identified the handling unit. The possible values are :
          - Rank and SequenceNumber for export procedure

          Values are Rank or SequenceNumber.

        • value string | null

          Value of reference.

        • Additional properties are NOT allowed
      • customsFlag string

        List of possible customs flag information :
        - Unknown (undefined flag - default value)
        - Import
        - Export
        - Transhipment
        - Transit

        Values are Unknown, Import, Export, Transhipment, or Transit.

      • huLocation object

        Current location information

        Hide huLocation attributes Show huLocation attributes object
        • place object

          Locations represented ports, airports, warehouse, berth, ... referenced in the S)ONE application.

          Hide place attributes Show place attributes object
          • code string

            Code of location.

            Maximum length is 20.

          • name string

            Name of location.

            Maximum length is 256.

        • location object

          Locations represented ports, airports, warehouse, berth, ... referenced in the S)ONE application.

          Hide location attributes Show location attributes object
          • code string

            Code of location.

            Maximum length is 20.

          • name string

            Name of location.

            Maximum length is 256.

        • Additional properties are NOT allowed
      • actors object
        Hide actors attributes Show actors attributes object
        • freightAgent object

          Actor referenced in the S)ONE application

          Hide freightAgent attributes Show freightAgent attributes object
          • code string

            Code of actor.

            Maximum length is 32.

          • name string

            Name of actor.

            Maximum length is 256.

        • freightForwarder object

          Actor referenced in the S)ONE application

          Hide freightForwarder attributes Show freightForwarder attributes object
          • code string

            Code of actor.

            Maximum length is 32.

          • name string

            Name of actor.

            Maximum length is 256.

      • temperatures object

        Temperature information.

        Hide temperatures attributes Show temperatures attributes object
        • setPoint number(double) | null

          Set point temperature.
          The default unit is C.

        • rangeMin number(double) | null

          Min temperature.
          The default unit is C.

        • rangeMax number(double) | null

          Max temperature.
          The default unit is C.

        • Additional properties are NOT allowed
      • shipments array[object] | null

        Shipment item.

        Shipment item.

        Hide shipments attributes Show shipments attributes object
        • documentReference string | null

          Reference of document that links to a shipment.
          e.g. the reference should be a bill of lading number

          Minimum length is 0, maximum length is 32.

        • documentId string | null

          S)ONE ID of document.
          This unique identifier is composed of a prefix (3 characters) and a number (10 digits).>

          Minimum length is 0, maximum length is 13.

        • documentType object

          Actor referenced in the S)ONE application

          Hide documentType attributes Show documentType attributes object
          • code number(int32)

            Code of the type of document.

          • name string

            Name of the type of document

            Maximum length is 512.

        • documentDate string(date-time) | null

          Date of document.
          ISO 8601 Extended Format

        • originLocation object

          UN/LOCODE information is based on recommendation 16 UN/LOCODE.

          Hide originLocation attributes Show originLocation attributes object
          • code string

            UN/LOCODE have length of 5 - combination of Country code (length of 2) and Location code (length of 3)

            Maximum length is 5.

          • name string

            Name of location.

            Maximum length is 256.

        • destinationLocation object

          UN/LOCODE information is based on recommendation 16 UN/LOCODE.

          Hide destinationLocation attributes Show destinationLocation attributes object
          • code string

            UN/LOCODE have length of 5 - combination of Country code (length of 2) and Location code (length of 3)

            Maximum length is 5.

          • name string

            Name of location.

            Maximum length is 256.

        • processingIndicator string

          List of possible processing indicator :
          - Unknown (undefined flag - default value)
          - Import
          - Export
          - Transhipment
          - Transit

          Values are Unknown, Transit, Transhipment, Import, or Export.

        • merchantHaulage boolean

          Indicator specifying that the freight forwarder may modify the shipment.

      • transport object

        Transport information.

        Hide transport attributes Show transport attributes object
        • meansName string | null

          Transport means name.

        • voyageId string | null

          S)ONE ID of the voyage.
          This unique identifier is composed of a prefix (3 characters) and a number (10 digits).

        • mode object
          Hide mode attributes Show mode attributes object
          • code number(int32)

            Transport mode code.

          • name string

            Transport mode name.

            Maximum length is 128.

        • meansNationality object

          Country information base on ISO 3166 standard.

          Hide meansNationality attributes Show meansNationality attributes object
          • name string

            Name of country.

            Maximum length is 256.

          • alphaCode3 string

            Three letter code of country.

            Minimum length is 3, maximum length is 3.

        • voyageDates object

          Transport dates

          Hide voyageDates attributes Show voyageDates attributes object
          • eta string(date-time) | null

            Estimated Time of Arrival is the time when a ship, vehicle, aircraft, cargo, emergency service or person is expected to arrive at its destination.
            ISO 8601 Extended Format

          • etd string(date-time) | null

            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.
            ISO 8601 Extended Format

          • ata string(date-time) | null

            Actual Time of Arrival is the time that a vessel or any other mode of transportation is determined to arrive at its destination.
            ISO 8601 Extended Format

          • atd string(date-time) | null

            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.
            ISO 8601 Extended Format

          • Additional properties are NOT allowed
        • schedulePlace object

          UN/LOCODE information is based on recommendation 16 UN/LOCODE.

          Hide schedulePlace attributes Show schedulePlace attributes object
          • code string

            UN/LOCODE have length of 5 - combination of Country code (length of 2) and Location code (length of 3)

            Maximum length is 5.

          • name string

            Name of location.

            Maximum length is 256.

        • meansType object
          Hide meansType attributes Show meansType attributes object
          • code string

            Code of means type.

          • name string

            Name of the means type.

        • meansId array[object] | null

          The mean identifier for the transport,
          e.g. when the mode of transport is a vessel, the transport mean identifier would be the vessel IMO number.

          The mean identifier for the transport,
          e.g. when the mode of transport is a vessel, the transport mean identifier would be the vessel IMO number.

          Hide meansId attributes Show meansId attributes object
          • type string

            Means identifier type. The possible values are :
            - IMONumber for maritime transport
            - CallSign for maritime transport

            Values are IMONumber, CallSign, IATA, or ICAO.

          • name string | null

            Name of means id

            Minimum length is 0, maximum length is 10.

          • Additional properties are NOT allowed
        • arrivalScheduleReference string | null

          Arrival reference.

          Minimum length is 0, maximum length is 384.

        • departureScheduleReference string | null

          Departure reference.

          Minimum length is 0, maximum length is 384.

        • Additional properties are NOT allowed
      • events array[object] | null

        An event corresponds to a movement or an authorization on the handling unit, occured on a location.

        An event corresponds to a movement or an authorization on the handling unit, occured on a location.

        Hide events attributes Show events attributes object
        • eventWay string

          Way of the movement on the location

          Values are In, Out, or Undefined.

        • eventType object

          Type of events defined in the S)ONE application.

          Hide eventType attributes Show eventType attributes object
          • code string

            Code of event.

            Maximum length is 32.

          • name string

            Name of event.

            Maximum length is 128.

        • eventDate string(date-time)

          Event date.
          ISO 8601 Extended Format

        • eventPlace object

          Locations represented ports, airports, warehouse, berth, ... referenced in the S)ONE application.

          Hide eventPlace attributes Show eventPlace attributes object
          • code string

            Code of location.

            Maximum length is 20.

          • name string

            Name of location.

            Maximum length is 256.

        • eventLocation object

          Locations represented ports, airports, warehouse, berth, ... referenced in the S)ONE application.

          Hide eventLocation attributes Show eventLocation attributes object
          • code string

            Code of location.

            Maximum length is 20.

          • name string

            Name of location.

            Maximum length is 256.

        • eventTransportMode object
          Hide eventTransportMode attributes Show eventTransportMode attributes object
          • code number(int32)

            Transport mode code.

          • name string

            Transport mode name.

            Maximum length is 128.

        • Additional properties are NOT allowed
      • hazardousItems array[object] | null

        Hazardous item.

        Hazardous item.

        Hide hazardousItems attributes Show hazardousItems attributes object
        • imoClass object

          Dangerous Code which is based on Dangerous Goods List of UNECE

          Hide imoClass attributes Show imoClass attributes object
          • code string

            Dangerous code

            Maximum length is 11.

          • description string

            Description of dangerous code

            Maximum length is 256.

        • limitedQuantity boolean | null

          Limited quantity

        • Additional properties are NOT allowed
      • emptyReturn object

        Empty return information.

        Hide emptyReturn attributes Show emptyReturn attributes object
        • dueDate string(date-time) | null

          Due date
          ISO 8601 Extended Format

        • finishDateEarliest string(date-time) | null

          Finish date earliest
          ISO 8601 Extended Format

        • finishDateLatest string(date-time) | null

          Finish date latest
          ISO 8601 Extended Format

        • Additional properties are NOT allowed
      • Additional properties are NOT allowed
    • Additional properties are NOT allowed
  • 400 application/json

    Bad Request

    Hide response attributes Show response attributes object
    • status string | null

      Http error status.

    • timestamp string(date-time)

      Error date.
      ISO 8601 Extended Format

    • code string | null

      Business error code.
      The possible values are :
      - R001 : No handling unit was found
      - R002 : The handling unit is null
      - R003 : The handling unit is not correctly formated

    • message string | null

      Error message.

    • Additional properties are NOT allowed
  • 404 application/json

    Not Found

    Hide response attributes Show response attributes object
    • status string | null

      Http error status.

    • timestamp string(date-time)

      Error date.
      ISO 8601 Extended Format

    • code string | null

      Business error code.
      The possible values are :
      - R001 : No handling unit was found
      - R002 : The handling unit is null
      - R003 : The handling unit is not correctly formated

    • message string | null

      Error message.

    • Additional properties are NOT allowed
GET /handling-units
curl \
 -X GET https://soget-api-integration.azure-api.net/api-tracing-libelle/v1/handling-units \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Ocp-Apim-Subscription-Key: $API_KEY"
Response examples (200)
{
  "total": 3,
  "returned": 1,
  "first": 42,
  "items": [
    {
      "reference": "AAAU1234566",
      "pswId": "CNI0000000001",
      "freightFamily": "Container",
      "sizeType": {
        "code": "45G1",
        "description": "GP/AERATION PASSIVE SUPERIEURE"
      },
      "packagingCode": {
        "code": "PK",
        "description": "Package"
      },
      "measures": {
        "quantity": 10,
        "weight": {
          "tare": {
            "value": 13030,
            "unit": "KGM"
          },
          "grossWeight": {
            "value": 13030,
            "unit": "KGM"
          },
          "netWeight": {
            "value": 13030,
            "unit": "KGM"
          }
        },
        "volume": {
          "value": 13030,
          "unit": "KGM"
        },
        "remainingQuantity": 4,
        "availableQuantity": 3,
        "reportedQuantity": 6,
        "remainingWeight": {
          "value": 13030,
          "unit": "KGM"
        }
      },
      "indicators": {
        "hazardous": true,
        "empty": true,
        "reefer": true,
        "pollutant": true,
        "fumigation": true,
        "quarantine": true,
        "outOfGauge": true
      },
      "references": [
        {
          "type": "Rank",
          "value": "20NL050BC243E2C8A0"
        }
      ],
      "customsFlag": "Unknown",
      "huLocation": {
        "place": {
          "code": "MTDF",
          "name": "Terminal de France"
        },
        "location": {
          "code": "MTDF",
          "name": "Terminal de France"
        }
      },
      "actors": {
        "freightAgent": {
          "code": "CCGM",
          "name": "CMA CGM"
        },
        "freightForwarder": {
          "code": "CCGM",
          "name": "CMA CGM"
        }
      },
      "temperatures": {
        "setPoint": -1,
        "rangeMin": -5,
        "rangeMax": 2
      },
      "shipments": [
        {
          "documentReference": "HLCUEUR2002APIK9",
          "documentId": "DAI0000387547",
          "documentType": {
            "code": 705,
            "name": "Bill of lading"
          },
          "documentDate": "2020-05-07T12:38:54.000Z",
          "originLocation": {
            "code": "FRLEH",
            "name": "Le Havre"
          },
          "destinationLocation": {
            "code": "FRLEH",
            "name": "Le Havre"
          },
          "processingIndicator": "Unknown",
          "merchantHaulage": true
        }
      ],
      "transport": {
        "meansName": "MSC GRAND",
        "voyageId": "VOS0019102839",
        "mode": {
          "code": 1,
          "name": "Maritime transport"
        },
        "meansNationality": {
          "name": "France",
          "alphaCode3": "FRA"
        },
        "voyageDates": {
          "eta": "2024-05-04T09:42:00+00:00",
          "etd": "2024-05-04T09:42:00+00:00",
          "ata": "2024-05-04T09:42:00+00:00",
          "atd": "2024-05-04T09:42:00+00:00"
        },
        "schedulePlace": {
          "code": "FRLEH",
          "name": "Le Havre"
        },
        "meansType": {
          "code": "1 MVE",
          "name": "vehicle carrier"
        },
        "meansId": [
          {
            "type": "IMONumber",
            "name": "9360142"
          }
        ],
        "arrivalScheduleReference": "BA649R",
        "departureScheduleReference": "BA649A"
      },
      "events": [
        {
          "eventWay": "In",
          "eventType": {
            "code": "DIR",
            "name": "Discharged"
          },
          "eventDate": "2024-05-04T09:42:00+00:00",
          "eventPlace": {
            "code": "MTDF",
            "name": "Terminal de France"
          },
          "eventLocation": {
            "code": "MTDF",
            "name": "Terminal de France"
          },
          "eventTransportMode": {
            "code": 1,
            "name": "Maritime transport"
          }
        }
      ],
      "hazardousItems": [
        {
          "imoClass": {
            "code": "1.1",
            "description": "Substances and articles which have a mass explosion hazard"
          },
          "limitedQuantity": true
        }
      ],
      "emptyReturn": {
        "dueDate": "2022-11-19T22:00:00.000Z",
        "finishDateEarliest": "2022-11-20T22:00:00.000Z",
        "finishDateLatest": "2022-11-21T22:00:00.000Z"
      }
    }
  ]
}
Response examples (400)
{
  "status": "NotFound",
  "timestamp": "2022-11-17T15:40:39.838Z",
  "code": "R001",
  "message": "No handling unit was found"
}
Response examples (404)
{
  "status": "NotFound",
  "timestamp": "2022-11-17T15:40:39.838Z",
  "code": "R001",
  "message": "No handling unit was found"
}