{ "openapi": "3.0.1", "info": { "title": "API Referential Unitary", "description": "API specifications for API Referential Unitary interface issued by SOGET", "contact": { "name": "SOGET", "url": "https://www.soget.fr/", "email": "hello@soget.fr" }, "license": { "name": "Copyright © SOGET", "url": "https://www.soget.fr/" }, "version": "1.4" }, "tags": [ { "name": "Actors", "description": "List of actor codes referenced in the S)ONE application." }, { "name": "ContainerTypes", "description": "Code list from the ISO 6346 standard specifying the type of shipping containers, used in international trade and electronic shipping messages." }, { "name": "Countries", "description": "Code list from the ISO 3166 standard, defining codes for the names of countries on 2 or 3 digits alpha-codes." }, { "name": "DangerousCodes", "description": "Code list of dangerous goods types and classes, used in international trade and electronic shipping messages." }, { "name": "DocumentTypes", "description": "Code list from Un/EDIFACT[1001] specifying the documents names used in international trade and electronic shipping messages." }, { "name": "EventTypes", "description": "List of event types referenced in the S)ONE application." }, { "name": "Locations", "description": "List of location codes referenced in the S)ONE application." }, { "name": "LocationTypes", "description": "Code list from Un/EDIFACT[3227] specifying the location function code used in international trade and electronic shipping messages." }, { "name": "PackagingCodes", "description": "Code list from UNECE/rec[21] specifying various packaging type names used in international trade and electronic shipping messages." }, { "name": "TransportMeansTypes", "description": "List of transport means types referenced in the S)ONE application." }, { "name": "TransportModes", "description": "Code list from UNECE/rec[19] specifying various transport modes used in international trade and electronic shipping messages." }, { "name": "Unlocodes", "description": "Code list provided by UNECE for trade and transport locations." } ], "paths": { "/actors/{code}": { "get": { "tags": [ "Actors" ], "summary": "Get actor information.", "description": "Sample request:\r\n\r\n`GET /actors/CCGM`", "parameters": [ { "name": "code", "in": "path", "description": "Actor code", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Actor" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpBusinessError" } } } } } } }, "/container-types/{code}": { "get": { "tags": [ "ContainerTypes" ], "summary": "Get container type information.", "description": "Sample request:\r\n \r\n`GET /container-types/45G1`", "parameters": [ { "name": "code", "in": "path", "description": "Container type code", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContainerType" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpBusinessError" } } } } } } }, "/countries/{code}": { "get": { "tags": [ "Countries" ], "summary": "Get country information.", "description": "Sample request:\r\n \r\n`GET /countries/FRA`", "parameters": [ { "name": "code", "in": "path", "description": "Country code (three letter code)", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Country" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpBusinessError" } } } } } } }, "/dangerous-codes/{type}/{code}": { "get": { "tags": [ "DangerousCodes" ], "summary": "Get dangerous code information.", "description": "Sample request:\r\n \r\n`GET /dangerous-codes/IMDG/1.1`\r\n \r\nor\r\n \r\n`GET /dangerous-codes/imdg/1.1`\r\n \r\nThe possible types of dangerous code are :\r\n\r\n* `IMDG` : International Maritime Dangerous Goods codes.\r\n* `UNDG` : United Nations Dangerous Goods codes.", "parameters": [ { "name": "type", "in": "path", "description": "Type of dangerous code", "required": true, "style": "simple", "explode": false, "schema": { "$ref": "#/components/schemas/DangerousCodeType" } }, { "name": "code", "in": "path", "description": "Dangerous code", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DangerousCode" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpBusinessError" } } } } } } }, "/document-types/{code}": { "get": { "tags": [ "DocumentTypes" ], "summary": "Get document type information.", "description": "Sample request:\r\n \r\n`GET /document-types/705`", "parameters": [ { "name": "code", "in": "path", "description": "Document type code", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentType" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpBusinessError" } } } } } } }, "/event-types/{code}": { "get": { "tags": [ "EventTypes" ], "summary": "Event type information.", "description": "Sample request:\r\n \r\n`GET /event-types/DIR`", "parameters": [ { "name": "code", "in": "path", "description": "Event type code", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventType" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpBusinessError" } } } } } } }, "/locations/{code}": { "get": { "tags": [ "Locations" ], "summary": "Get location information.", "description": "Sample request:\r\n \r\n`GET /locations/FRLEH`", "parameters": [ { "name": "code", "in": "path", "description": "Location code", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Location" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpBusinessError" } } } } } } }, "/location-types/{code}": { "get": { "tags": [ "LocationTypes" ], "summary": "Get location type information.", "description": "Sample request:\r\n \r\n`GET /location-types/248`", "parameters": [ { "name": "code", "in": "path", "description": "Location type code", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationType" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpBusinessError" } } } } } } }, "/packaging-codes/{code}": { "get": { "tags": [ "PackagingCodes" ], "summary": "Get packaging code information.", "description": "Sample request:\r\n \r\n`GET /packaging-codes/PK`", "parameters": [ { "name": "code", "in": "path", "description": "Packaging code", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackagingCode" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpBusinessError" } } } } } } }, "/transport-means-types/{code}": { "get": { "tags": [ "TransportMeansTypes" ], "summary": "Get transport mean type information.", "description": "Sample request:\r\n \r\n`GET /transport-means-types/1 50 1`", "parameters": [ { "name": "code", "in": "path", "description": "Transport mean type code", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransportMeansType" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpBusinessError" } } } } } } }, "/transport-modes/{code}": { "get": { "tags": [ "TransportModes" ], "summary": "Get transport mode information.", "description": "Sample request:\r\n \r\n`GET /transport-modes/1`", "parameters": [ { "name": "code", "in": "path", "description": "Transport mode code", "required": true, "style": "simple", "explode": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransportMode" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpBusinessError" } } } } } } }, "/unlocodes/{code}": { "get": { "tags": [ "Unlocodes" ], "summary": "Get UN/LOCODE information.", "description": "Sample request:\r\n \r\n`GET /unlocodes/UGMUK`", "parameters": [ { "name": "code", "in": "path", "description": "UN/LOCODE code", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unlocode" } } } }, "400": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpBusinessError" } } } } } } } }, "components": { "schemas": { "Actor": { "type": "object", "properties": { "code": { "maxLength": 32, "minLength": 0, "type": "string", "description": "Code of actor", "nullable": true, "example": "CCGM" }, "name": { "maxLength": 256, "minLength": 0, "type": "string", "description": "Name of actor", "nullable": true, "example": "CMA CGM" }, "type": { "maxLength": 3, "minLength": 0, "type": "string", "description": "Type of actor", "nullable": true, "example": "FB" }, "location": { "maxLength": 5, "minLength": 0, "type": "string", "description": "Location code", "nullable": true, "example": "FR" }, "organization": { "maxLength": 256, "minLength": 0, "type": "string", "description": "Organization of actor", "nullable": true, "example": "CMA CGM" } }, "additionalProperties": false, "description": "Actors referenced in the S)ONE application." }, "ContainerType": { "type": "object", "properties": { "code": { "maxLength": 4, "minLength": 0, "type": "string", "description": "A 4 digit Alpha Numeric Code uniquely describing the container", "nullable": true, "example": "45G1" }, "description": { "maxLength": 256, "minLength": 0, "type": "string", "description": "Description of the Container Type", "nullable": true, "example": "GP/AERATION PASSIVE SUPERIEURE" }, "length": { "type": "number", "description": "External length in feet of the container\r\n
This field is useless.", "format": "double", "example": 40, "deprecated": true }, "height": { "type": "number", "description": "External height of container in feet\r\n
This field is useless.", "format": "double", "example": 9.5, "deprecated": true }, "group": { "maxLength": 4, "minLength": 0, "type": "string", "description": "4 Digit describing the group the codes belong to, more regularly used when sending electronic shipping messages\r\n
This field is useless.", "nullable": true, "example": "45GP", "deprecated": true } }, "additionalProperties": false, "description": "The type of container is based on ISO 6346 standard." }, "Country": { "type": "object", "properties": { "name": { "maxLength": 256, "minLength": 0, "type": "string", "description": "Name of country", "nullable": true, "example": "France" }, "alphaCode2": { "maxLength": 2, "minLength": 0, "type": "string", "description": "Two letter code of country", "nullable": true, "example": "FR" }, "alphaCode3": { "maxLength": 3, "minLength": 0, "type": "string", "description": "Three letter code of country", "nullable": true, "example": "FRA" }, "identifier": { "type": "integer", "description": "Digital code of country", "format": "int32", "example": 250 } }, "additionalProperties": false, "description": "Countries which are based on ISO 3166 standard." }, "DangerousCode": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/DangerousCodeType" }, "code": { "maxLength": 11, "minLength": 0, "type": "string", "description": "Dangerous Code", "nullable": true, "example": "1.1" }, "description": { "maxLength": 256, "minLength": 0, "type": "string", "description": "Description of Dangerous Code", "nullable": true, "example": "Substances and articles which have a mass explosion hazard" } }, "additionalProperties": false, "description": "Dangerous Code which is based on Dangerous Goods List of UNECE" }, "DangerousCodeType": { "type": "string", "description": "", "enum": [ "IMDG", "UNDG" ] }, "DocumentType": { "type": "object", "properties": { "code": { "type": "integer", "description": "Code of the type of document", "format": "int32", "example": 705 }, "name": { "maxLength": 512, "minLength": 0, "type": "string", "description": "Name of the type of document", "nullable": true, "example": "Bill of lading" }, "description": { "maxLength": 2048, "minLength": 0, "type": "string", "description": "Description of the type of document", "nullable": true, "example": "Negotiable document/message which evidences a contract of carriage by sea and the taking over or loading of goods by carrier, and by which carrier undertakes to deliver goods against surrender of the document A provision in the document that goods are to be delivered to the order of a named person, or to order, or to bearer, constitutes such an undertaking" } }, "additionalProperties": false, "description": "Type of document which is based on UN/Edifact 1001." }, "EventType": { "type": "object", "properties": { "code": { "maxLength": 32, "minLength": 0, "type": "string", "description": "Code of the type of event", "nullable": true, "example": "DIR" }, "name": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Name of the type of event", "nullable": true, "example": "Discharged" } }, "additionalProperties": false, "description": "Type of events defined in the S)ONE application." }, "HttpBusinessError": { "type": "object", "properties": { "status": { "type": "string", "description": "Error status", "nullable": true, "example": "400" }, "timestamp": { "type": "string", "description": "Error date", "format": "date-time", "example": "2022-10-18T14:53:52.239Z" }, "code": { "type": "string", "description": "Error code\r\n
- R101 : The container size type is unfound.
- R102 : The country code is unfound.
- R103 : The document type is unfound.
- R104 : The location code is unfound.
- R105 : The location type is unfound.
- R106 : The packaging code is unfound.
- R107 : The transport mode is unfound.
- R108 : The transport mean type is unfound.
- R109 : The event type is unfound.
- R110 : The UN/LOCODE is unfound.
- R111 : The actor is unfound.
- R112 : The dangerous code is unfound.", "nullable": true, "example": "R001" }, "message": { "type": "string", "description": "Error message", "nullable": true, "example": "Information not found." } }, "additionalProperties": false, "description": "Business error management" }, "Location": { "type": "object", "properties": { "code": { "maxLength": 20, "minLength": 0, "type": "string", "description": "Code of the location", "nullable": true, "example": "FRLEH" }, "name": { "maxLength": 256, "minLength": 0, "type": "string", "description": "Name of the location", "nullable": true, "example": "Le Havre" }, "type": { "type": "integer", "description": "Type of location", "format": "int32", "example": 248 }, "country": { "maxLength": 3, "minLength": 0, "type": "string", "description": "Three letter code of country", "nullable": true, "example": "FRA" }, "parent": { "maxLength": 20, "minLength": 0, "type": "string", "description": "Code of the parent location\r\n
eg. Parent of MTDF (Terminal de France) is FRLEH (Le Havre) ", "nullable": true, "example": "FRLEH" } }, "additionalProperties": false, "description": "Locations represented ports, airports, warehouse, berth, ... referenced in the S)ONE application." }, "LocationType": { "type": "object", "properties": { "code": { "type": "integer", "description": "Code of the type of location", "format": "int32", "example": 248 }, "name": { "maxLength": 256, "minLength": 0, "type": "string", "description": "Name of the type of location", "nullable": true, "example": "Place of discharge and loading" }, "description": { "maxLength": 2048, "minLength": 0, "type": "string", "description": "Description of the type of location", "nullable": true, "example": "Place at which a means of transport is performing both discharge and loading operations, e.g. seaport, airport, freight terminal, rail station." } }, "additionalProperties": false, "description": "Type of location which is based on UN/Edifact 3227" }, "PackagingCode": { "type": "object", "properties": { "code": { "maxLength": 2, "minLength": 0, "type": "string", "description": "Code of packaging", "nullable": true, "example": "PK" }, "description": { "maxLength": 100, "minLength": 0, "type": "string", "description": "Name of packaging", "nullable": true, "example": "Package" } }, "additionalProperties": false, "description": "Packaging codes which are based on :\r\n
ADR standards for road mode
RID standards for rail mode
IMDG/IMO standards for maritime mode
ADN standards for inland water mode
IATA/ICAO standards for air mode" }, "TransportMeansType": { "type": "object", "properties": { "mCode": { "maxLength": 8, "minLength": 0, "type": "string", "description": "MCode is composed of the transport mode and a code value excepted for aircraft type whose Mcode is represented by IATA Code.\r\n
Mode : Mode of transport code as defined in Recommendation 19
Value : 3 character alphanumeric code value comprising characters 0 to 9 and upper case A to Z. For example, in maritime transport the code value \"50\" represents \"General cargo vessel\", whilst \"501\" is a subordinate code entry that represents \"Grain vessel\".", "nullable": true, "example": "1 50 1" }, "name": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Code value name.", "nullable": true, "example": "Grain vessel" }, "description": { "maxLength": 1024, "minLength": 0, "type": "string", "description": "Code value description.", "nullable": true, "example": "Vessel designed to carry grain." } }, "additionalProperties": false, "description": "Transport means types which are based on Un/Edifact Recommendation 28 and EMSA.\r\n
The identification of the type of means of transport is frequently required in information exchange in trade and transport. The means of transport such as aircraft, road vehicles, railway engines, barges, and deep-sea vessels, are often identified by a registration number. Such registration numbers invariably do not contain any element that would indicate the type the means of transport to which the number relates. Therefore a separate method is required to identify the specific type of means of transport." }, "TransportMode": { "type": "object", "properties": { "code": { "type": "integer", "description": "Transport mode code", "format": "int32", "example": 1 }, "name": { "maxLength": 128, "minLength": 0, "type": "string", "description": "Transport mode name.", "nullable": true, "example": "Maritime transport" }, "description": { "maxLength": 2048, "minLength": 0, "type": "string", "description": "Transport mode description.", "nullable": true, "example": "Transport of goods and/or persons is by sea" } }, "additionalProperties": false, "description": "Transport mode which is based on Unece 19 recommendations." }, "Unlocode": { "type": "object", "properties": { "code": { "maxLength": 5, "minLength": 0, "type": "string", "description": "UN/LOCODE have length of 5 - combination of Country code (length of 2) and Location code (length of 3)", "nullable": true, "example": "UGMUK" }, "country": { "maxLength": 2, "minLength": 0, "type": "string", "description": "Two letters code of country", "nullable": true, "example": "UG" }, "name": { "maxLength": 256, "minLength": 0, "type": "string", "description": "Description about location", "nullable": true, "example": "Mukono" }, "subdivision": { "maxLength": 3, "minLength": 0, "type": "string", "description": "1-3 character alphabetic and/or numeric code for the administrative division \r\nof the country concerned(state, province, department, etc.)", "nullable": true, "example": "108" }, "coordinates": { "maxLength": 12, "minLength": 0, "type": "string", "description": "Geographical coordinates (latitude/longitude)\r\n \r\nFormat: ddmmN dddmmW, ddmmS dddmmE, etc.,\r\n\r\nWhere the two last digits refer to minutes \r\nand the two or three first digits indicate the degrees.", "nullable": true, "example": "0021N 03245E" } }, "additionalProperties": false, "description": "UN/LOCODE information is based on \r\nrecommendation 16 UN/LOCODE." } }, "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-referential-unitary/v1" } ] }