---
openapi: 3.0.1
info:
  title: API Customs
  description: API specifications for API Customs interface issued by SOGET. The output
    is the customs 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: 1.0.0
paths:
  "/customs":
    get:
      tags:
      - Customs
      summary: Filter handling units' customs information relating to the merchandise
        by reference or by S)ONE ID.
      description: "Sample request\r\n\r\n    GET /customs?reference=AAAU1234566&spi=CNI1234567890&limit=5&offset=0&desc=true"
      parameters:
      - name: reference
        in: query
        description: Handling unit reference with which to filter.
        schema:
          type: string
          default: ''
      - name: spi
        in: query
        description: Handling unit ID with which to filter. ID corresponds to the
          single passage identification in S)ONE.
        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.
        schema:
          type: boolean
          default: false
      - name: limit
        in: query
        description: Number of results to be returned. Max value is 10.
        schema:
          type: integer
          format: int32
          default: 5
      - name: offset
        in: query
        description: Index of the first returned result.
        schema:
          type: integer
          format: int32
          default: 0
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CustomsInformationItemsResponseModel"
        '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:
    CustomsInformationsItem:
      type: object
      properties:
        commodityCode:
          type: string
          description: Commodity code
          nullable: true
        commodityCodeType:
          type: string
          description: Nomenclature
          nullable: true
        mrn:
          type: string
          description: MRN information
          nullable: true
        mrnItem:
          type: integer
          description: MRN article
          format: int32
          nullable: true
        document:
          type: string
          description: Customs document
          nullable: true
        status:
          type: string
          description: Customs status
          nullable: true
      additionalProperties: false
      description: Customs information item.
    CustomsInformation:
      type: object
      properties:
        reference:
          type: string
          description: Reference
          nullable: true
        spi:
          type: string
          description: Spi
          nullable: true
        customsInformationsItems:
          type: array
          items:
            "$ref": "#/components/schemas/CustomsInformationsItem"
          description: Customs information
          nullable: true
      additionalProperties: false
      description: Customs information
    CustomsInformationItemsResponseModel:
      type: object
      properties:
        total:
          type: integer
          description: Total amount of objects matching given parameters.
          format: int32
          example: 3
        returned:
          type: integer
          description: Amount of objects returned by the paginated query.
          format: int32
          example: 1
        first:
          type: integer
          description: Index of the first returned object.
          format: int32
          example: 0
        items:
          type: array
          items:
            "$ref": "#/components/schemas/CustomsInformation"
          description: Items returned by the query.
          nullable: true
      additionalProperties: false
      description: An object containing the list of found customs information.
    HttpBusinessError:
      type: object
      properties:
        status:
          type: string
          description: Http error status.
          nullable: true
          example: NotFound
        timestamp:
          type: string
          description: "Error date.\r\n<br>ISO 8601 Extended Format"
          format: date-time
          example: '2022-11-17T15:40:39.8381389Z'
        code:
          type: string
          description: "Business error code.\r\n<br>The possible values are :<br>-
            R001 : No handling unit was found<br>- R002 : The handling unit is null<br>-
            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.
  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-customs/v1