{ "openapi": "3.0.1", "info": { "title": "API Tracking Code", "description": "API specifications for the tracking of a handling unit, 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-handling-unit": { "post": { "tags": [ "Trackings" ], "summary": "Create tracking for a specific handling unit.", "description": "Sample request:\r\n\r\n POST /track-handling-unit", "requestBody": { "description": "Information of new tracking.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingSinglePost" }, "example": { "spi": "CNI0000000001", "reference": "CGMU0000001", "way": "Import", "place": "MTDF", "agentCode": "CCGM", "url": "https://my-webhook-endpoints.com", "externalReference": "EXT-REF-001" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "string" } } } }, "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." }, "TrackingSinglePost": { "required": [ "reference", "url" ], "type": "object", "properties": { "spi": { "maxLength": 13, "minLength": 13, "type": "string", "description": "Handling unit SPI.", "nullable": true }, "reference": { "maxLength": 11, "minLength": 11, "type": "string", "description": "Reference of a handling unit" }, "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." }, "externalReference": { "maxLength": 50, "type": "string", "description": "External reference to facilitate the identification and processing of webhook notifications.", "nullable": true } }, "additionalProperties": false, "description": "Tracking model for POST method" } }, "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\n\n```\ncurl -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\"\n```\n\n## Request an API\n````\ncurl \\\n -X GET https://soget-api-integration.azure-api.net \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"\n -H \"Ocp-Apim-Subscription-Key: $API_KEY\"\n```" }, { "title": "Webhook", "content": "# Receiving Webhook Notifications\n\nAfter 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:\n\n```json\n{\n \"HandlingUnit\": {\n \"Events\": [\n {\n \"AlertDate\": \"2025-08-15T23:32:00+00:00\",\n \"AlertType\": \"Creation\",\n \"Direction\": \"Import\",\n \"Location\": \"MTDF\",\n \"State\": \"Active\",\n \"Type\": \"DIR\"\n }\n ],\n \"FreightFamily\": \"Container\",\n \"Reference\": \"REF_HU\",\n \"Spi\": \"SPI_HU\",\n \"ExternalReference\": \"EXT_REF\",\n }\n}" } ], "security": [ { "bearer_token": [], "api_key": [] } ], "servers": [ { "url": "https://soget-api-integration.azure-api.net/api-tracking-code/v1" } ] }