openapi: 3.0.1
info:
  title: APMT Track & Trace - Empty Container Returns
  description: Details if and when an Import container returns/arrives Empty at a terminal
  contact:
    name: APMT Terminals API Management Team
    url: https://developer.apmterminals.com/support/technical-support
    email: api.support@apmterminals.com
  license:
    name: APM Terminals BV
    url: https://developer.apmterminals.com/terms-and-conditions
  version: 1.0.0

servers:
  - url: 'https://api-sandbox.apmterminals.com'
    description: Sandbox Environment (Sandbox)
  - url: 'https://api.apmterminals.com'
    description : Production Environment

paths:
  /empty-container-returns:
    get:
      description: Returns details of if and when an Import container returns/arrives Empty at a terminal
      parameters:
      - $ref : '#/components/parameters/assetId'
      - $ref : '#/components/parameters/facilityCode'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type : object
                properties :
                  containerId :
                    type : string
                    description : The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number.
                    example: 'CARX4812090'
                  shippingLine:
                    type : string
                    description : The name of the shipper or container operator.
                    example: 'Maersk Line'
                  containerIsoCode:
                    description: ISO code of the container.
                    type: string
                    example: '42G1'
                  sizeTypeHeight:
                    description: Size-Type-Height of the container.
                    type: string
                    example: '40/GP/96'
                  isContainerReturned:
                    description: a flag to indicate if the container is returned or not
                    type: string
                    example : 'true'
                  gateInDateTimeLocal:
                    description: Date and local time with UTC offset, that's been set to be the gate in time.
                    type: string
                    format: date-time
                    example: '2019-11-02T15:45:37.627-07:00'
              example: {
        "containerId": "MSKU6669540",
        "shippingLine": "MAE",
        "containerIsoCode": "42G1",
        "sizeTypeHeight": "40/GP/86",
        "isContainerReturned": "true",
        "gateInDateTimeLocal": "2016-11-02T10:35:41-08:00"
    }

        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Exception'
              example:
                Payload:
                  code: "400"
                  message: "Bad Request"
                  debugMessage: "Invalid content or request details"

        '401':
          description: The user is not authenticated in the system
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Exception'
              example :
                1 :
                  Payload:
                    code: "401"
                    message: "Unauthorized"
                    debugMessage: "Failed to Authenticate, invalid access token"
                2:
                  Payload:
                    code: "401"
                    message: "Unauthorized"
                    debugMessage: "Access Token Expired, please renew"
        '403':
          description: The user does not have permissions to access this endpoint, Inadequate credits for the api call or Rate Plan not selected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Exception'
              example :
                Payload:
                  code: "400"
                  message: "Bad Request"
                  debugMessage: "Inadequate credits for the api call or Rate Plan not selected"
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Exception'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Exception'
              example :
                Payload:
                  code: "405"
                  message: "Method Not Allowed"
                  debugMessage: "Method Not Allowed"
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Exception'
              example :
                Payload:
                  code: "429"
                  message: "Too Many Requests"
                  debugMessage: "Sudden usage spike, please try after sometime"
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Exception'
              example :
                Payload:
                  code: "500"
                  message: "InternalServerError"
                  debugMessage: "Unexpected server error"
        '502':
          description: BadGateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Exception'
              example :
                Payload:
                  code: "502"
                  message: "BadGateway"
                  debugMessage: "The remote server returned an error: Bad Gateway"
        '503':
          description: ServiceUnavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Exception'
              example :
                Payload:
                  code: "503"
                  message: "ServiceUnavailable"
                  debugMessage: "Target Service Unavailable"

components:
  parameters:
    facilityCode:
      name: facilityCode
      in: query
      description: The Terminal UN Location Code to search for (USLAX for Los Angeles etc). Only accepts a single Terminal Code. Possible values are USLAX (Los Angeles, US), USMOB (Mobile, US), USNWK (Port Elizabeth, US), SEGOT (Gothenburg, Sweden), ITVDL (Vado, Italy),
      NGAPP (Apapa, Nigeria),BHKBS (Bahrain), USMIA (Miami, US), ARBUE (Buenos Aires, Argentina), INNSA (Mumbai, India), INPAV (Pipavav, India), JOAQB (Aqaba, Jordan), DKAAR (Aarhus, Denmark) and GTPRQ (Puerto Quetzal,Guatemala).
      required: true
      style: form
      explode: true
      schema:
        type: string
      example: SEGOT
    assetId:
      name : assetId
      in: query
      description: Either single or multiple Container IDs seperated by commas (e.g. MRKU7137914,UACU817507).
      required: true
      style: form
      explode: true
      schema:
        type: string
      example: MRKU7137914

  schemas:
    Exception:
      type: object
      properties:
        code:
          type: string
          description: Standard http code.
        message:
          type: string
          description: Standard http message with respect to http code.
        debugMessage:
          type: string
          description: Reason for the failure of message.

  securitySchemes:
    oauth2:
      type: oauth2
      description: APMT IAM OAuth 2.0 with client credentials only.
      flows:
        clientCredentials:
          tokenUrl: https://api.apmterminals.com/oauth/client_credential/accesstoken?grant_type=client_credentials
          scopes:
            client_write: Write data