{ "openapi": "3.0.1", "info": { "title": "API Equipment", "description": "API specifications for API Equipment interface issued by SOGET. The output is the equipment information relating to the handling unit.", "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": { "/equipments": { "get": { "operationId": "filter-equipment", "tags": [ "Equipment" ], "summary": "Filter the equipment information by reference or by S)ONE ID. ", "description": "Sample request :\r\n\r\n GET /equipments?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/EquipmentItemsResponseModel" } } } }, "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": { "EquipmentItemsResponseModel": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total amount of objects matching given parameters.", "example": 3 }, "returned": { "type": "integer", "description": "Amount of objects returned by the paginated query.", "example": 1 }, "first": { "type": "integer", "description": "Index of the first returned object.", "example": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Equipment" }, "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
Object result types :
- EquipmentItemsResponseModel : List of returned equipments" }, "Dimensions": { "type": "object", "properties": { "length": { "$ref": "#/components/schemas/Measure" }, "width": { "$ref": "#/components/schemas/Measure" }, "height": { "$ref": "#/components/schemas/Measure" } } }, "Equipment": { "type": "object", "properties": { "spi": { "type": "string", "description": "Equipment spi" }, "reference": { "type": "string", "description": "Equipment reference" }, "seals": { "type": "array", "description": "List of seals.", "items": { "$ref": "#/components/schemas/Seal" } }, "measures": { "$ref": "#/components/schemas/Measures" }, "dimensions": { "$ref": "#/components/schemas/Dimensions" }, "supplier": { "type": "string" } } }, "Seal": { "type": "object", "properties": { "number": { "type": "string" }, "origin": { "type": "string" } } }, "HttpBusinessError": { "type": "object", "properties": { "status": { "type": "string", "description": "Http error status.", "nullable": true, "example": "NotFound" }, "timestamp": { "type": "string", "description": "Error date.\r\n
ISO 8601 Extended Format", "format": "date-time", "example": "2022-11-17T15:40:39.838Z" }, "code": { "type": "string", "description": "Business error code.\r\n
The possible values are :
- R001 : No handling unit was found
- R002 : The handling unit is null
- 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." }, "Measure": { "type": "object", "properties": { "value": { "type": "number", "description": "Measure value.", "format": "decimal" }, "unit": { "maxLength": 5, "minLength": 0, "type": "string", "description": "Value which comes from the international system of units." } }, "description": "This object concerns the following fields : \r\n
- Length (the default unit is MTR)
- Width (the default unit is MTR)
- Height (the default unit is MTR)
- Volume (the default unit is DMQ)" }, "Measures": { "type": "object", "properties": { "volume": { "$ref": "#/components/schemas/Measure" } } } }, "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```" } ], "security": [ { "bearer_token": [], "api_key": [] } ], "servers": [ { "url": "https://soget-api-integration.azure-api.net/api-equipment/v1" } ] }