openapi: 3.1.0
info:
  title: ThingPark AS to LRC Tunnel API for Cellular IoT
  description: >
    REST interface implemented by ThingPark for AS to LRC communication. This
    interface applies to Cellular IoT devices.
  version: '8.1'
servers:
  - url: 'https://community.thingpark.io/thingpark/lrc/rest'
    description: Community
  - url: 'https://thingparkenterprise.eu.actility.com/thingpark/lrc/rest'
    description: Europe
  - url: 'https://thingparkenterprise.us.actility.com/thingpark/lrc/rest'
    description: United-States
  - url: 'https://thingparkenterprise.au.actility.com/thingpark/lrc/rest'
    description: Australia
  - url: 'https://{hostname}/thingpark/lrc/rest'
    description: Self-hosted TPE
    variables:
      hostname:
        default: enterprise.actility.local
        description: Hostname of the self-hosted TPE deployment
paths:
  /downlink:
    post:
      deprecated: true
      tags:
        - downlink-v1
      summary: Send a message mode downlink packet to a Cellular IoT device
      description: |
        This endpoint must no longer be used: the endpoint `POST /v2/downlink` must be used in replacement.

        ---

        Send a message mode downlink packet to a Cellular IoT device
      x-rateLimit:
        category: DL_IMPACT
      parameters:
        - $ref: '#/components/parameters/DevEUI'
        - $ref: '#/components/parameters/MType'
        - $ref: '#/components/parameters/Payload'
        - $ref: '#/components/parameters/RAN'
        - $ref: '#/components/parameters/AS_ID'
        - $ref: '#/components/parameters/Time'
        - $ref: '#/components/parameters/CorrelationID'
        - $ref: '#/components/parameters/Token'
      responses:
        '200':
          $ref: '#/components/responses/SuccessV1'
        '350':
          $ref: '#/components/responses/ErrorOtherV1'
        '404':
          $ref: '#/components/responses/ErrorNoBaseStationV1'
  /v2/downlink:
    post:
      tags:
        - downlink-v2
      summary: Send a message mode downlink packet to a Cellular IoT device
      description: Send a message mode downlink packet to a Cellular IoT device
      x-rateLimit:
        category: DL_IMPACT
      parameters:
        - $ref: '#/components/parameters/DevEUI'
        - $ref: '#/components/parameters/MType'
        - $ref: '#/components/parameters/Payload'
        - $ref: '#/components/parameters/RAN'
        - $ref: '#/components/parameters/AS_ID'
        - $ref: '#/components/parameters/Time'
        - $ref: '#/components/parameters/CorrelationID'
        - $ref: '#/components/parameters/Token'
      responses:
        '202':
          description: The downlink request is accepted
        '409':
          $ref: '#/components/responses/ErrorV2'
components:
  schemas:
    Error:
      type: object
      oneOf:
        - $ref: '#/components/schemas/ErrorDefault'
        - $ref: '#/components/schemas/ErrorInvalidPayloadSize'
      example:
        code: 100
        message: Invalid DevEUI
    ErrorDefault:
      title: Default error
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          allOf:
            - $ref: '#/components/schemas/ErrorCode'
            - type: integer
              enum: [ 100, 105, 106, 107, 108, 109, 110, 111, 114 ]
        message:
          $ref: '#/components/schemas/ErrorMessage'
    ErrorInvalidPayloadSize:
      type: object
      title: Invalid payload size error
      required:
        - code
        - message
      properties:
        code:
          type: integer
          allOf:
            - $ref: '#/components/schemas/ErrorCode'
            - type: integer
              enum: [ 113 ]
        message:
          $ref: '#/components/schemas/ErrorMessage'
        maxSize:
          type: integer
          format: int32
          description: When set this means that the max payload size was reached. When not
            set this means that the payload size is invalid (must be a multiple
            of 2).
    ErrorCode:
      type: integer
      format: int32
      description: Error code
    ErrorMessage:
      type: string
      description: Error message
  responses:
    SuccessV1:
      description: The downlink request is accepted
      content:
        text/html:
          schema:
            type: string
            example: <html><body>Request queued by LRC</body></html>
    ErrorOtherV1:
      description: |
        The downlink request is rejected.

        The HTML document in response body contains the error message:

        <html><table>
          <thead><tr><th><strong>Message</strong></th><th><strong>Description</strong></th></tr></thead>
          <tbody>
            <tr><td>Invalid DevEUI</td><td>The provided IMEI does not match an existing Device.</td></tr>
            <tr><td>Security Check. AS_ID is mandatory</td><td>Speaking to this device needs AS_ID. The Application Server authorization has been activated for this device and the application must be identified.</td></tr>
            <tr><td>Security Check. missing timestamp/token</td><td>Time and Token query parameters are mandatory when the application server authentication is activated.</td></tr>
            <tr><td>Security Check. bad AS_ID</td><td>AS_ID is not declared in the database or is not authorized for the targeted device</td></tr>
            <tr><td>Security Check. Server Decrypt Error</td><td>Missing or badly formatted security token.</td></tr>
            <tr><td>Security Check. malformed ISO8601 time</td><td>An ISO 8601 date/time must be used (YYYY-MM-DDThh:mm:ss.s+|-hh:mm) representing a local time with a time zone offset in hours and minutes.</td></tr>
            <tr><td>Security Check. Invalid downlink frame timestamp</td><td>The time deviation between the frame generation by the application server and the reception by the LRC exceeds the MAX deviation configured in the AS profile.</td></tr>
            <tr><td>Security Check. bad token</td><td>Token was not accepted by the LRC.</td></tr>
            <tr><td>Payload too big or invalid size</td><td>The payload size is greater than 5000 characters or is not a multiple of 2.</td></tr>
            <tr><td>Downlink transmission disabled</td><td>The request for transmission of the downlink packet was rejected by the LRC due to the absence of the downlinkTransmission feature flag in the Connectivity plan associated to the device.</td></tr>
          </tbody>
        <br/></html>
      content:
        text/html:
          schema:
            type: string
            example: <html><body>Invalid DevEUI</body></html>
    ErrorNoBaseStationV1:
      description: The request for transmission of the downlink packet was rejected by
        the LRC because no base station near to the device is connected.
      content:
        text/html:
          schema:
            type: string
            example: <html><body>No Base Station Available</body></html>
    ErrorV2:
      description: |
        The downlink request is rejected.

        The JSON document in response body contains the error code, the error message and optionally additional information:

        <html><table>
          <thead><tr><th><strong>Code</strong></th><th><strong>Message</strong></th></tr></thead>
          <tbody>
            <tr><td>100</td><td>Invalid DevEUI</td></tr>
            <tr><td>105</td><td>Security Check: AS_ID is mandatory</td></tr>
            <tr><td>106</td><td>Security Check: Missing timestamp</td></tr>
            <tr><td>107</td><td>Security Check: Bad AS_ID</td></tr>
            <tr><td>108</td><td>Security Check: Server Decrypt Error</td></tr>
            <tr><td>109</td><td>Security Check: Malformed ISO 8601 time</td></tr>
            <tr><td>110</td><td>Security Check: Invalid downlink frame timestamp</td></tr>
            <tr><td>111</td><td>Security Check: Bad token</td></tr>
            <tr><td>113</td><td>Payload too big or invalid size</td></tr>
            <tr><td>114</td><td>Downlink transmission disabled</td></tr>
          </tbody>
        <br/></html>
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    DevEUI:
      name: DevEUI
      in: query
      description: Targeted Device EUI in hexadecimal format (representing 8 octets)
      required: true
      schema:
        type: string
        pattern: ^[0-9a-f]{16}$
        example: 'f03d290000000000'
    MType:
      name: MType
      in: query
      description: |
        Type of the packet:
        - 0 = IPv4 packet
      schema:
        type: integer
        format: int32
        minimum: 0
        maximum: 0
        example: 0
    Payload:
      name: Payload
      in: query
      description: Hexa dump of the IPv4 packet (applicable when MType=0). This
        includes IP Header and TCP/UDP Headers.
      required: true
      schema:
        type: string
        pattern: ^([0-9A-F][0-9A-F]){1,250}$
        example: '45C0004C5DAC40003F11BF670A0B000A97507C68007B007B003846F4E3030AE900000A1100011DB297507C68DB78EE2162C0F74E00000000000000000000000000000000DB78F79E5E881B12'
    RAN:
      name: RAN
      in: query
      description: |
        Radio Access Network Type:
        - CELLULAR = Cellular Access Network (only this value is supported)
      required: true
      schema:
        type: string
        enum: [ CELLULAR ]
        example: CELLULAR
    AS_ID:
      name: AS_ID
      in: query
      description: |
        Application Server ID, as provisioned in the AS Profile. AS_ID is mandatory if the Application server authentication has been activated in the AS Profile. In this case, the LRC will check that the Application Server is authorized to send downlink command to the device.
      schema:
        type: string
        pattern: ^[0-9A-Za-z\-._]+$
        example: app1.sample.com
    Time:
      name: Time
      in: query
      description: |
        ISO 8601 time of the request. Time is mandatory when the Application server authentication has been activated in the AS Profile. In this case the LRC will verify the time deviation between the generation and the reception of the request. The deviation must be lower than Max Time Deviation defined in the AS Profile.

        Note: In the URL of the HTTP request, use %2B ASCII code for the + character and the %3A ASCII code for the : character.
      schema:
        type: string
        format: date-time
        example: '2016-01-11T14:28:00.333+02:00'
    Token:
      name: Token
      in: query
      description: |
        Security token to sign the downlink frame. Token is mandatory when the Application server authentication has been activated in the AS Profile.
        For more information about token computation, see <a href="../#token-computation-details">Token Computation Details</a>.
      schema:
        type: string
        pattern: ^[0-9a-f]{64}$
        example: 'ea8f31d2299cbece8e180a3012766c4df15fe3cf2e142d9fdf4035b5894ec886'
    CorrelationID:
      name: CorrelationID
      in: query
      description: |
        64 bits ID used to correlate the downlink frame with the associated downlink frame sent report.

        When this parameter is provided, it is sent back in the associated downlink frame sent report.
      schema:
        type: string
        pattern: ^[0-9A-F]{16}$
        example: '4434704901C7450B'
tags:
  - name: downlink-v1
    description: Downlink API v1
  - name: downlink-v2
    description: Downlink API v2
