--- 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 ``` 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-referential-unitary/v1