---
openapi: 3.0.1
info:
  title: API Tracing Libelle
  description: API specifications for API Tracing Libelle interface issued by SOGET.
    The output of these services contains the meaning of the reference 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: v1
paths:
  "/handling-units":
    get:
      tags:
      - HandlingUnits
      summary: "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.\r\nAn handling unit corresponds to a container or a good."
      description: "Sample request :\r\n\r\n    GET /handling-units?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/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:
          maxLength: 32
          type: string
          description: Code of actor.
          example: CCGM
        name:
          maxLength: 256
          type: string
          description: Name of actor.
          example: CMA CGM
      description: Actor referenced in the S)ONE application
    Actors:
      type: object
      properties:
        freightAgent:
          "$ref": "#/components/schemas/Actor"
        freightForwarder:
          "$ref": "#/components/schemas/Actor"
    Country:
      type: object
      properties:
        name:
          maxLength: 256
          type: string
          description: Name of country.
          example: France
        alphaCode3:
          maxLength: 3
          minLength: 3
          type: string
          description: Three letter code of country.
          example: FRA
      description: Country information base on ISO 3166 standard.
    CustomsFlag:
      type: string
      description: 'List of possible customs flag information :   <br>- Unknown (undefined
        flag - default value)<br>- Import<br>- Export<br>- Transhipment<br>- Transit'
      enum:
      - Unknown
      - Import
      - Export
      - Transhipment
      - Transit
    DangerousCode:
      type: object
      properties:
        code:
          maxLength: 11
          type: string
          description: Dangerous code
          example: '1.1'
        description:
          maxLength: 256
          type: string
          description: Description of dangerous code
          example: Substances and articles which have a mass explosion hazard
      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: int32
          example: 705
        name:
          maxLength: 512
          type: string
          description: Name of the type of document
          example: Bill of lading
      description: Actor referenced in the S)ONE application
    EmptyReturn:
      type: object
      properties:
        dueDate:
          type: string
          description: "Due date\r\n<br>ISO 8601 Extended Format"
          format: date-time
          nullable: true
          example: '2022-11-19T22:00:00.000Z'
        finishDateEarliest:
          type: string
          description: "Finish date earliest\r\n<br>ISO 8601 Extended Format"
          format: date-time
          nullable: true
          example: '2022-11-20T22:00:00.000Z'
        finishDateLatest:
          type: string
          description: "Finish date latest\r\n<br>ISO 8601 Extended Format"
          format: date-time
          nullable: true
          example: '2022-11-21T22:00:00.000Z'
      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
        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:
          maxLength: 32
          type: string
          description: Code of event.
          example: DIR
        name:
          maxLength: 128
          type: string
          description: Name of event.
          example: Discharged
      description: Type of events defined in the S)ONE application.
    FreightFamily:
      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.'
      enum:
      - Container
      - BreakBulk
      - SolidBulk
      - LiquidBulk
      - MobileUnits
    HandlingUnit:
      type: object
      properties:
        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
          example: AAAU1234566
        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
          example: CNI0000000001
        freightFamily:
          "$ref": "#/components/schemas/FreightFamily"
        sizeType:
          "$ref": "#/components/schemas/SizeType"
        packagingCode:
          "$ref": "#/components/schemas/PackagingCode"
        measures:
          "$ref": "#/components/schemas/Measures"
        indicators:
          "$ref": "#/components/schemas/Indicators"
        references:
          type: array
          description: "Linked references. This reference should be :\r\n<br>a sequence
            number for export process,<br>a rank reference for export process."
          items:
            "$ref": "#/components/schemas/Reference"
        customsFlag:
          "$ref": "#/components/schemas/CustomsFlag"
        huLocation:
          "$ref": "#/components/schemas/HuLocation"
        actors:
          "$ref": "#/components/schemas/Actors"
        temperatures:
          "$ref": "#/components/schemas/Temperatures"
        shipments:
          type: array
          description: "Shipments information.\r\n<br>This corresponds to the documentary
            information related to the handling unit, such as booking or bill of lading
            information."
          nullable: true
          items:
            "$ref": "#/components/schemas/Shipment"
        transport:
          "$ref": "#/components/schemas/Transport"
        events:
          type: array
          description: Events information.
          nullable: true
          items:
            "$ref": "#/components/schemas/EventInformation"
        hazardousItems:
          type: array
          description: Hazardous information.
          nullable: true
          items:
            "$ref": "#/components/schemas/HazardousItem"
        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
          example: 3
        returned:
          type: integer
          description: Amount of objects returned by the paginated query.
          format: int32
          example: 1
        first:
          type: integer
          description: Index of the first returned object.
          format: int32
        items:
          type: array
          description: Items returned by the query.
          nullable: true
          items:
            "$ref": "#/components/schemas/HandlingUnit"
      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
          example: true
      additionalProperties: false
      description: Hazardous item.
    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.
    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:
          maxLength: 20
          type: string
          description: Code of location.
          example: MTDF
        name:
          maxLength: 256
          type: string
          description: Name of location.
          example: Terminal de France
      description: Locations represented ports, airports, warehouse, berth, ... referenced
        in the S)ONE application.
    MeansIdType:
      type: string
      description: "Means identifier type. The possible values are : \r\n<br>- IMONumber
        for maritime transport<br>- CallSign for maritime transport"
      enum:
      - IMONumber
      - CallSign
      - IATA
      - ICAO
    Measure:
      type: object
      properties:
        value:
          type: number
          description: Measure value.
          format: double
          nullable: true
          example: 13030
        unit:
          maxLength: 5
          minLength: 0
          type: string
          description: Value which comes from the international system of units.
          nullable: true
          example: KGM
      additionalProperties: false
      description: "This object concerns the following fields :   \r\n<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
          example: 10
        weight:
          "$ref": "#/components/schemas/Weight"
        volume:
          "$ref": "#/components/schemas/Measure"
        remainingQuantity:
          type: integer
          description: "Number of packages remaining at current location.\r\n<br>This
            field is used in the context of partial reports.<br>Applicable for breakbulk
            only."
          format: int32
          nullable: true
          example: 4
        availableQuantity:
          type: integer
          description: "Number of packages available at current location.\r\n<br>This
            field is used in the context of partial reports.<br>Applicable for breakbulk
            only."
          format: int32
          nullable: true
          example: 3
        reportedQuantity:
          type: integer
          description: "Number of package reported reported at current location.\r\n<br>This
            field is used in the context of partial reports.<br>Applicable for breakbulk
            only."
          format: int32
          nullable: true
          example: 6
        remainingWeight:
          "$ref": "#/components/schemas/Measure"
      additionalProperties: false
      description: Handling unit measures.
    PackagingCode:
      type: object
      properties:
        code:
          maxLength: 2
          minLength: 2
          type: string
          description: Code of packaging
          example: PK
        description:
          maxLength: 100
          type: string
          description: Description of packaging
          example: Package
      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:
      type: string
      description: "List of possible processing indicator : \r\n<br>- Unknown (undefined
        flag - default value)<br>- Import<br>- Export<br>- Transhipment<br>- Transit"
      enum:
      - Unknown
      - Transit
      - Transhipment
      - Import
      - Export
    Reference:
      type: object
      properties:
        type:
          "$ref": "#/components/schemas/ReferenceType"
        value:
          type: string
          description: Value of reference.
          nullable: true
          example: 20NL050BC243E2C8A0
      additionalProperties: false
      description: "References linked to the handling unit\r\n<br> e.g. for process
        export, the equipment can be identified by the sequence number."
    ReferenceType:
      type: string
      description: "Type of references which identified the handling unit. The possible
        values are : \r\n<br>- Rank and SequenceNumber for export procedure"
      enum:
      - Rank
      - SequenceNumber
    Shipment:
      type: object
      properties:
        documentReference:
          maxLength: 32
          minLength: 0
          type: string
          description: "Reference of document that links to a shipment.\r\n<br>e.g.
            the reference should be a bill of lading number"
          nullable: true
          example: HLCUEUR2002APIK9
        documentId:
          maxLength: 13
          minLength: 0
          type: string
          description: "S)ONE ID of document.\r\n<br>This unique identifier is composed
            of a prefix (3 characters) and a number (10 digits).>"
          nullable: true
          example: DAI0000387547
        documentType:
          "$ref": "#/components/schemas/DocumentType"
        documentDate:
          type: string
          description: "Date of document.\r\n<br>ISO 8601 Extended Format"
          format: date-time
          nullable: true
          example: '2020-05-07T12:38:54.000Z'
        originLocation:
          "$ref": "#/components/schemas/Unlocode"
        destinationLocation:
          "$ref": "#/components/schemas/Unlocode"
        processingIndicator:
          "$ref": "#/components/schemas/ProcessingIndicator"
        merchantHaulage:
          type: boolean
          description: Indicator specifying that the freight forwarder may modify
            the shipment.
          example: true
      description: Shipment item.
    SizeType:
      type: object
      properties:
        code:
          maxLength: 4
          minLength: 4
          type: string
          description: A 4 digit Alpha Numeric Code uniquely describing the container.
          example: 45G1
        description:
          maxLength: 256
          type: string
          description: Description of the Container Type.
          example: GP/AERATION PASSIVE SUPERIEURE
      description: Size type information.
    Temperatures:
      type: object
      properties:
        setPoint:
          type: number
          description: "Set point temperature.\r\n<br>The default unit is C."
          format: double
          nullable: true
          example: -1
        rangeMin:
          type: number
          description: "Min temperature.\r\n<br>The default unit is C."
          format: double
          nullable: true
          example: -5
        rangeMax:
          type: number
          description: "Max temperature.\r\n<br>The default unit is C."
          format: double
          nullable: true
          example: 2
      additionalProperties: false
      description: Temperature information.
    Transport:
      type: object
      properties:
        meansName:
          type: string
          description: Transport means name.
          nullable: true
          example: MSC GRAND
        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
          example: VOS0019102839
        mode:
          "$ref": "#/components/schemas/TransportMode"
        meansNationality:
          "$ref": "#/components/schemas/Country"
        voyageDates:
          "$ref": "#/components/schemas/TransportDate"
        schedulePlace:
          "$ref": "#/components/schemas/Unlocode"
        meansType:
          "$ref": "#/components/schemas/TransportMeansType"
        meansId:
          type: array
          description: Transport means identifier.
          nullable: true
          items:
            "$ref": "#/components/schemas/TransportMeansIdentifier"
        arrivalScheduleReference:
          maxLength: 384
          minLength: 0
          type: string
          description: Arrival reference.
          nullable: true
          example: BA649R
        departureScheduleReference:
          maxLength: 384
          minLength: 0
          type: string
          description: Departure reference.
          nullable: true
          example: BA649A
      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:
          maxLength: 10
          minLength: 0
          type: string
          description: Name of means id
          nullable: true
          example: '9360142'
      additionalProperties: false
      description: "The mean identifier for the transport,\r\n<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.
          example: 1 MVE
        name:
          type: string
          description: Name of the means type.
          example: vehicle carrier
    TransportMode:
      type: object
      properties:
        code:
          type: number
          description: Transport mode code.
          format: int32
          example: 1
        name:
          maxLength: 128
          type: string
          description: Transport mode name.
          example: Maritime transport
    Unlocode:
      type: object
      properties:
        code:
          maxLength: 5
          type: string
          description: UN/LOCODE have length of 5 - combination of Country code (length
            of 2) and Location code (length of 3)
          example: FRLEH
        name:
          maxLength: 256
          type: string
          description: Name of location.
          example: Le Havre
      description: UN/LOCODE information is based on recommendation 16 UN/LOCODE.
    Way:
      type: string
      description: Way of the movement on the location
      enum:
      - In
      - Out
      - Undefined
    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) : \r\n<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/v1