---
openapi: 3.0.1
info:
  title: API Tracking Code In Mass
  description: API specifications for the tracking of handling units, published by
    SOGET
  contact:
    name: SOGET S.A.
    url: https://www.soget.fr/
    email: info@soget.fr
  license:
    name: Copyright © SOGET
    url: https://www.soget.fr/
  version: v1
paths:
  "/track-document":
    post:
      tags:
      - Trackings
      summary: Create a tracking for handling units with same document reference.
      description: "Sample request:\r\n\r\n    POST /track-document"
      requestBody:
        description: Information of new tracking.
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/TrackingBatchPost"
            example:
              documentReference: '3714238101'
              way: Import
              place: MTDF
              agentCode: CCGM
              url: https://my-webhook-endpoints.com
      responses:
        '201':
          description: "Created.<br></br>\r\nAPI will return the functional ID of
            Tracking."
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/TrackingBatchResponseModel"
              example:
                trackingId: TRK0000000001
                trackedHandlingUnits:
                - spi: CNI0000000001
                  reference: CGMU0000001
                - spi: CNI0000000002
                  reference: CGMU0000002
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/HttpBusinessError"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/HttpBusinessError"
components:
  schemas:
    CustomsIndicators:
      enum:
      - Unknown
      - Import
      - Export
      - Transit
      - Transhipment
      - DomesticIn
      - DomesticOut
      - DomesticTranshipment
      type: string
      description: Customs indicators
    HttpBusinessError:
      type: object
      properties:
        status:
          type: string
          description: Error status.
          nullable: true
        timestamp:
          type: string
          description: Error timestamp.
          format: date-time
        code:
          type: string
          description: Error code.
          nullable: true
        message:
          type: string
          description: Error message.
          nullable: true
        subErrors:
          type: array
          items:
            "$ref": "#/components/schemas/HttpBusinessSubError"
          description: Error details.
          nullable: true
      additionalProperties: false
      description: Functional error handling.
    HttpBusinessSubError:
      type: object
      properties:
        section:
          type: string
          description: Error object.
          nullable: true
        field:
          type: string
          description: Error attribute.
          nullable: true
        rejectedValue:
          type: string
          description: Rejection code.
          nullable: true
        message:
          type: string
          description: Error message.
          nullable: true
      additionalProperties: false
      description: Error message details.
    TrackingBatchPost:
      required:
      - documentReference
      type: object
      properties:
        way:
          "$ref": "#/components/schemas/CustomsIndicators"
        place:
          maxLength: 20
          type: string
          description: Event location.
          nullable: true
        agentCode:
          maxLength: 64
          type: string
          description: Agent code.
          nullable: true
        url:
          minLength: 1
          pattern: "^(https?:\\/\\/)?([\\da-z\\.-]+)\\.([a-z\\.]{2,6})([\\/\\w \\.-]*)*\\/?$"
          type: string
          description: Webhook URL endpoint to receive tracking events' notifications.
        documentReference:
          minLength: 1
          type: string
          description: Reference of the announcement document
      additionalProperties: false
      description: Tracking model for POST API /track-document
    TrackedHandlingUnit:
      type: object
      properties:
        spi:
          type: string
          description: Handling unit SPI
          nullable: true
        reference:
          type: string
          description: Handling unit reference
          nullable: true
      additionalProperties: false
      description: Tracked handling unit minimal information
    TrackingBatchResponseModel:
      type: object
      properties:
        trackingId:
          type: string
          description: Functional ID of the tracking
          nullable: true
        trackedHandlingUnits:
          type: array
          items:
            "$ref": "#/components/schemas/TrackedHandlingUnit"
          description: List tracked handling unit
          nullable: true
      additionalProperties: false
      description: Response model for API POST /trackings/track-document
  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"
    ```
- title: Webhook
  content: |-
    # Receiving Webhook Notifications

    After you register a webhook URL using Tracking API, we will send HTTP POST requests to that endpoint whenever events occur on a handling unit. The payload of each request contains relevant information about the event in JSON format:

    ```json
    {
      "HandlingUnit": {
        "Events": [
          {
            "AlertDate": "2025-08-15T23:32:00+00:00",
            "AlertType": "Creation",
            "Direction": "Import",
            "Location": "MTDF",
            "State": "Active",
            "Type": "DIR"
          }
        ],
        "FreightFamily": "Container",
        "Reference": "REF_HU",
        "Spi": "SPI_HU",
        "ExternalReference": "EXT_REF",
      }
    }
security:
- bearer_token: []
  api_key: []
servers:
- url: https://soget-api-integration.azure-api.net/api-tracking-code-in-mass/v1