---
openapi: 3.0.1
info:
  title: API Tracing Code
  description: API specifications for API Tracing Code interface issued by SOGET
  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=CGMU2436601&spi=CNI0000063978&limit=5&offset=0&desc=true"
      parameters:
      - name: reference
        in: query
        description: Handling unit reference with which to filter.
        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.
        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:
    Actors:
      type: object
      properties:
        freightAgent:
          type: string
          description: Freight Agent.
          nullable: true
          example: CSGT
        freightForwarder:
          type: string
          description: Freight Forwarder.
          nullable: true
          example: '2308522'
      additionalProperties: false
      description: Actors information.
    CustomsFlag:
      enum:
      - Unknown
      - Import
      - Export
      - Transhipment
      - Transit
      type: string
      description: "List of possible customs flag information : \r\n<br>- Unknown
        (undefined flag - default value)<br>- Import<br>- Export<br>- Transhipment<br>-
        Transit"
    EmptyReturn:
      type: object
      properties:
        dueDate:
          type: string
          description: "Due date\r\n<br>ISO 8601 Extended Format"
          format: date-time
          example: '2022-11-19T22:00:00+00:00'
        finishDateEarliest:
          type: string
          description: "Finish date earliest\r\n<br>ISO 8601 Extended Format"
          format: date-time
          example: '2022-11-20T22:00:00+00:00'
        finishDateLatest:
          type: string
          description: "Finish date latest\r\n<br>ISO 8601 Extended Format"
          format: date-time
          example: '2022-11-21T22:00:00+00:00'
      additionalProperties: false
      description: Empty return  information.
    EventInformation:
      type: object
      properties:
        eventType:
          type: string
          description: Type of event.
          nullable: true
          example: GIR
        eventDate:
          type: string
          description: "Event date.\r\n<br>ISO 8601 Extended Format"
          format: date-time
          example: '2019-11-12T07:41:00+08:30'
        eventPlace:
          type: string
          description: Place of event
          nullable: true
          example: FRLEH
        eventLocation:
          type: string
          description: Location of event
          nullable: true
          example: MTNOTMS
        eventWay:
          "$ref": "#/components/schemas/Way"
        eventTransportMode:
          type: integer
          description: "Transport mode of event\r\n<br>Unece Recommendation 19"
          format: int32
          example: 1
      additionalProperties: false
      description: An event corresponds to a movement or an authorization on the handling
        unit, occured on a location.
    FreightFamily:
      enum:
      - Container
      - BreakBulk
      - SolidBulk
      - LiquidBulk
      - MobileUnits
      type: string
      description: "The freight family handled by this service is only Container and
        Breakbulk.\r\n<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:
        reference:
          maxLength: 17
          minLength: 0
          type: string
          description: "Handling unit reference.\r\n<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: CGMU2436601
        pswId:
          maxLength: 13
          minLength: 0
          type: string
          description: "S)ONE ID of the handling unit.\r\n<br>This unique identifier
            is composed of a prefix(3 characters) and a number(10 digits)."
          nullable: true
          example: CNI0000063978
        freightFamily:
          "$ref": "#/components/schemas/FreightFamily"
        sizeType:
          type: string
          description: "Size type of container.\r\n<br>Applicable for containers only."
          nullable: true
          example: 22G1
        packagingCode:
          type: string
          description: "Packaging code of breakbulk.\r\n<br>Applicable for breakbulk
            only."
          nullable: true
          example: PK
        measures:
          "$ref": "#/components/schemas/Measures"
        indicators:
          "$ref": "#/components/schemas/Indicators"
        references:
          type: array
          items:
            "$ref": "#/components/schemas/References"
          description: "Linked references. This reference should be :\r\n<br>a sequence
            number for export process,<br>a rank reference for export process."
          nullable: true
        customsFlag:
          "$ref": "#/components/schemas/CustomsFlag"
        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.\r\n<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\r\n<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
          example: 0
        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.\r\n<br>Object result types : <br>-
        HandlingUnitItemsResponseModel :  List of returned handling units"
    HazardousItem:
      type: object
      properties:
        imoClass:
          type: string
          description: Dangerous class (IMO)
          nullable: true
          example: '1.1'
        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.8381389Z'
        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:
          type: string
          description: Current place of the handling unit.
          nullable: true
          example: FRLEH
        location:
          type: string
          description: Current location of the handling unit.
          nullable: true
          example: MTDF
      additionalProperties: false
      description: Current location information
    Indicators:
      type: object
      properties:
        hazardous:
          type: boolean
          description: Hazardous indicator.
          example: true
        empty:
          type: boolean
          description: "Indicator to denote whether the equipment is empty or laden.
            \r\n<br>Applicable for the container only."
          example: false
        reefer:
          type: boolean
          description: Reefer indicator.
          example: true
        pollutant:
          type: boolean
          description: Pollutant indicator.
          example: false
        fumigation:
          type: boolean
          description: Fumigation indicator.
          example: false
        quarantine:
          type: boolean
          description: Quarantine indicator.
          example: false
      additionalProperties: false
      description: Handling unit indicators.
    MeansIdType:
      enum:
      - IMONumber
      - CallSign
      - IATA
      - ICAO
      type: string
      description: "Means identifier type. The possible values are : \r\n<br>- IMONumber
        for maritime transport<br>- CallSign for maritime transport"
    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.
    ProcessingIndicator:
      enum:
      - Unknown
      - Transit
      - Transhipment
      - Import
      - Export
      type: string
      description: "List of possible processing indicator : \r\n<br>- Unknown (undefined
        flag - default value)<br>- Import<br>- Export<br>- Transhipment<br>- Transit"
    ReferenceType:
      enum:
      - Rank
      - SequenceNumber
      type: string
      description: "Type of references which identified the handling unit. The possible
        values are : \r\n<br>- Rank and SequenceNumber for export procedure"
    References:
      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."
    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:
          type: integer
          description: Type of document (1001 norm Un/Edifact).
          format: int32
          nullable: true
          example: 705
        documentDate:
          type: string
          description: "Date of document.\r\n<br>ISO 8601 Extended Format"
          format: date-time
          nullable: true
          example: '2020-05-07T14:38:54+02:00'
        originLocation:
          maxLength: 20
          minLength: 0
          type: string
          description: Place of origin of the shipment.
          nullable: true
          example: FRTLS
        destinationLocation:
          maxLength: 20
          minLength: 0
          type: string
          description: Place of destination of the shipment.
          nullable: true
          example: FRNTE
        processingIndicator:
          "$ref": "#/components/schemas/ProcessingIndicator"
        merchantHaulage:
          type: boolean
          description: Indicator specifying that the freight forwarder may modify
            the shipment.
          example: true
      additionalProperties: false
      description: Shipment item.
    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:
          maxLength: 384
          minLength: 0
          type: string
          description: Transport means name.
          nullable: true
          example: MSC EYRA
        voyageId:
          maxLength: 13
          minLength: 0
          type: string
          description: "S)ONE ID of the voyage.\r\n<br>This unique identifier is composed
            of a prefix (3 characters) and a number (10 digits)."
          nullable: true
          example: VOS0000034525
        mode:
          type: integer
          description: "Transport mode.\r\n<br>Unece Recommendation 19"
          format: int32
          example: 1
        meansNationality:
          type: string
          description: "Transport means nationality.\r\n<br>ISO 3166 alpha 3"
          nullable: true
          example: GBR
        voyageDates:
          "$ref": "#/components/schemas/TransportDate"
        schedulePlace:
          maxLength: 5
          minLength: 0
          type: string
          description: Schedule place.
          nullable: true
          example: FRLEH
        voyageAgentId:
          maxLength: 13
          minLength: 0
          type: string
          description: Voyage agent internal identifier composed of a prefix (3 characters)
            and a number (10 digits).
          nullable: true
          example: VAG0000034525
        voyageAgentReference:
          type: string
          description: Reference of the voyage agent.
          nullable: true
          example: OWL-RDM-2305
        meansType:
          type: string
          description: Transport means type.
          nullable: true
          example: MVE
        meansId:
          type: array
          items:
            "$ref": "#/components/schemas/TransportMeansIdentifier"
          description: Transport means identifier.
          nullable: true
        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.\r\n<br>ISO 8601 Extended Format"
          format: date-time
          nullable: true
          example: '2020-05-19T22:00:00+00:00'
        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.\r\n<br>ISO 8601 Extended Format"
          format: date-time
          nullable: true
          example: '2020-05-20T23:00:00+00:00'
        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.\r\n<br>ISO
            8601 Extended Format"
          format: date-time
          nullable: true
          example: '2020-05-19T22:43:17+00:00'
        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.\r\n<br>ISO 8601 Extended Format"
          format: date-time
          nullable: true
          example: '2020-05-20T23:00:17+00:00'
      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."
    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) : \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-code/v1