openapi: 3.1.0
info:
  title: ThingPark LRC to AS Tunnel API for Cellular IoT
  description: >
    REST interface implemented by ThingPark for LRC to AS communication. This interface applies to Cellular IoT devices.
  version: '8.1'
paths:
  /:
    post:
      tags:
        - reports
      summary: Send a report for a Cellular IoT device
      description: |
        Report a message mode uplink packet, a session event or a microflow
        event for a Cellular IoT device.
      parameters:
        - $ref: '#/components/parameters/AS_ID'
        - $ref: '#/components/parameters/LrnDevEui'
        - $ref: '#/components/parameters/LrnInfos'
        - $ref: '#/components/parameters/Time'
        - $ref: '#/components/parameters/Token'
      requestBody:
        $ref: '#/components/requestBodies/Report'
      responses:
        '200':
          description: Operation success
        default:
          description: Operation failed
components:
  schemas:
    ReportJson:
      type: object
      oneOf:
        - $ref: '#/components/schemas/UplinkFrameReportJson'
        - $ref: '#/components/schemas/DownlinkFrameSentReportJson'
    ReportXml:
      type: object
      oneOf:
        - $ref: '#/components/schemas/UplinkFrameReportXml'
        - $ref: '#/components/schemas/DownlinkFrameSentReportXml'
    UplinkFrameReportJson:
      title: Uplink frame report
      type: object
      required:
        - DevEUI_uplink
      properties:
        DevEUI_uplink:
          type: object
          allOf:
            - $ref: '#/components/schemas/UplinkFrameReport'
            - type: object
              properties:
                CustomerData:
                  $ref: '#/components/schemas/CustomerDataJson'
    UplinkFrameReportXml:
      title: Uplink frame report
      type: object
      allOf:
        - $ref: '#/components/schemas/UplinkFrameReport'
        - type: object
          properties:
            CustomerData:
              $ref: '#/components/schemas/CustomerDataXml'
    UplinkFrameReport:
      type: object
      required:
        - CustomerID
        - DevAddr
        - DevEUI
        - IMSI
        - Late
        - Lrcid
        - MTC
        - MType
        - Time
      properties:
        APN:
          $ref: '#/components/schemas/APN'
        Cause:
          type: integer
          description: Session deletion cause (only applicable when MType=2)
          format: int32
          example: 10
        CELLID:
          $ref: '#/components/schemas/CELLID'
        CELLTAC:
          $ref: '#/components/schemas/CELLTAC'
        CMCCMNC:
          $ref: '#/components/schemas/CMCCMNC'
        CustomerID:
          $ref: '#/components/schemas/CustomerID'
        DevAddr:
          $ref: '#/components/schemas/DevAddr'
        DevEUI:
          $ref: '#/components/schemas/DevEUI'
        EBI:
          $ref: '#/components/schemas/EBI'
        IMEI:
          $ref: '#/components/schemas/IMEI'
        IMSI:
          $ref: '#/components/schemas/IMSI'
        Late:
          type: integer
          description: Indicates that this is a late reporting of an uplink frame.
          format: int32
          minimum: 0
          maximum: 1
          example: 0
        Lrcid:
          $ref: '#/components/schemas/Lrcid'
        MSISDN:
          $ref: '#/components/schemas/MSISDN'
        MTC:
          $ref: '#/components/schemas/MTC'
        MType:
          type: integer
          description: |
            Type of the message:
            - 0 = Message mode uplink IPv4 packet
            - 1 = Session creation
            - 2 = Session deletion
            - 3 = Session update
            - 4 = Microflow event aggregating uplink and downlink direct IP mode
              usage on a given period
          format: int32
          minimum: 0
          maximum: 4
          example: 0
        payload_hex:
          type: string
          description: Hexa dump of the IPv4 packet (applicable when MType=0). This includes IP Header and TCP/UDP Headers.
          pattern: ^([0-9a-f][0-9a-f]){1,250}$
          example: '45c0004c5dac40003f11bf670a0b000a97507c68007b007b003846f4e3030ae900000a1100011db297507c68db78ee2162c0f74e00000000000000000000000000000000db78f79e5e881b12'
        RAT:
          $ref: '#/components/schemas/RAT'
        SERVNET:
          $ref: '#/components/schemas/SERVNET'
        Time:
          type: string
          description: Timestamp of packet reception on the P-GW
          format: date-time
          example: '2020-07-09T16:06:38.49+02:00'
        UFBDL:
          type: string
          description: Microflow Bytes down in Bytes. Only applicable when MType=4.
          example: '45821'
        UFBUL:
          type: string
          description: Microflow Bytes up in Bytes. Only applicable when MType=4.
          example: '896587'
        UFDATE:
          type: string
          description: Microflow start timestamp. Only applicable when MType=4.
          format: date-time
          example: '2020-07-09T16:06:38.49+02:00'
        UFDUR:
          type: string
          description: Microflow duration in seconds. Only applicable when MType=4.
          example: '10'
        UplinkSize:
          type: integer
          description: Size of the IPv4 packet in Bytes. Only applicable when MType=0.
          format: int32
          example: 76
      xml:
        name: DevEUI_uplink
        namespace: 'http://uri.actility.com/lora'
    DownlinkFrameSentReportJson:
      title: Downlink frame sent report
      type: object
      required:
        - DevEUI_downlink_Sent
      properties:
        DevEUI_downlink_Sent:
          type: object
          allOf:
            - $ref: '#/components/schemas/DownlinkFrameSentReport'
            - type: object
              properties:
                CustomerData:
                  $ref: '#/components/schemas/CustomerDataJson'
    DownlinkFrameSentReportXml:
      title: Downlink frame sent report
      type: object
      allOf:
        - $ref: '#/components/schemas/DownlinkFrameSentReport'
        - type: object
          properties:
            CustomerData:
              $ref: '#/components/schemas/CustomerDataXml'
    DownlinkFrameSentReport:
      type: object
      required:
        - Cause
        - CustomerID
        - DevAddr
        - DevEUI
        - IMSI
        - Lrcid
        - MTC
        - MType
        - Time
      properties:
        APN:
          $ref: '#/components/schemas/APN'
        Cause:
          type: integer
          description: |
            Downlink transmission status:
            - 0 means that the downlink was delivered
            - other value means that the downlink could not be delivered
          format: int32
          example: 0
        CELLID:
          $ref: '#/components/schemas/CELLID'
        CELLTAC:
          $ref: '#/components/schemas/CELLTAC'
        CMCCMNC:
          $ref: '#/components/schemas/CMCCMNC'
        CorrelationID:
          type: string
          description: |
            ID used to correlate the downlink frame sent report with the unicast downlink frame previously submitted.

            Only reported when CorrelationID has been provided in downlink frame.
          pattern: ^[0-9A-F]{16}$
          example: '4434704901C7450B'
        CustomerID:
          $ref: '#/components/schemas/CustomerID'
        DevAddr:
          $ref: '#/components/schemas/DevAddr'
        DevEUI:
          $ref: '#/components/schemas/DevEUI'
        EBI:
          $ref: '#/components/schemas/EBI'
        IMEI:
          $ref: '#/components/schemas/IMEI'
        IMSI:
          $ref: '#/components/schemas/IMSI'
        Lrcid:
          $ref: '#/components/schemas/Lrcid'
        MSISDN:
          $ref: '#/components/schemas/MSISDN'
        MTC:
          $ref: '#/components/schemas/MTC'
        MType:
          type: integer
          description: |
            Type of the message:
            - 5 = Message mode downlink IPv4 packet
          format: int32
          minimum: 5
          maximum: 5
          example: 5
        RAT:
          $ref: '#/components/schemas/RAT'
        SERVNET:
          $ref: '#/components/schemas/SERVNET'
        Time:
          type: string
          description: Timestamp of packet reception on the LRC
          format: date-time
          example: '2020-01-27T10:00:46.336+01:00'
      xml:
        name: DevEUI_downlink_Sent
        namespace: 'http://uri.actility.com/lora'
    APN:
      type: string
      description: Access Point Name
      example: internet
    CELLID:
      type: string
      description: Cell ID
      example: '897988'
    CELLTAC:
      type: string
      description: Cell Tracking Area Number
      example: '123456'
    CMCCMNC:
      type: string
      description: Cell MCCMNC
      example: '20810'
    CustomerID:
      type: string
      description: Customer ID associated to the Device Manager account
      example: '100000507'
    DevAddr:
      type: string
      description: Device IP address
      example: '10.10.0.10'
    DevEUI:
      type: string
      description: Device EUI
      pattern: ^[0-9a-f]{16}$
      example: 'f03d290000000000'
    EBI:
      type: integer
      description: EPS Bearer ID
      format: int32
      example: 123456
    IMEI:
      type: string
      description: Device IMEI
      pattern: ^[0-9]{14}$
      example: '35456789012345'
    IMSI:
      type: string
      description: SIM card IMSI
      pattern: ^[0-9]{15}$
      example: '234500012232166'
    Lrcid:
      type: string
      description: ID of the LRC sending the report
      pattern: ^[0-9A-F]{8}$
      example: '00000065'
    MSISDN:
      type: string
      description: MSISDN number E.164
      example: '1234567890123456'
    MTC:
      type: string
      description: ID of the P-GW that processed the packet
      example: '00000001'
    RAT:
      type: string
      description: Radio Access Type
      example: 'EUTRAN'
    SERVNET:
      type: string
      description: Serving Network MCCMNC
      example: '20810'
    CustomerDataJson:
      type: object
      description: Customer data set by provisioning
      properties:
        loc:
          type: object
          description: Administrative device location
          required:
            - lat
            - lon
          properties:
            lat:
              type: string
              description: Device latitude
              example: '43.58081'
            lon:
              type: string
              description: Device longitude
              example: '1.4421667'
        alr:
          type: object
          description: Product metadata
          required:
            - pro
            - ver
          properties:
            pro:
              type: string
              description: Product name
              example: STL
            ver:
              type: string
              description: Product version
              example: '1'
        tags:
          type: array
          description: Tags associated with the device
          items:
            type: string
          example: [ tag1, tag2 ]
        doms:
          type: array
          items:
            type: object
            required:
              - n
              - g
            properties:
              n:
                type: string
                description: Domain name
              g:
                type: string
                description: Domain group name
          example:
            - n: France/Paris
              g: Site
            - n: Location
              g: Vertical
        name:
          type: string
          description: Device name
          example: My device name
    CustomerDataXml:
      type: string
      description: |
        Device properties set by provisioning:
        - "loc": administrative location (OPTIONAL)
          - "lat" (latitude) and "lon" (longitude) sub-attributes.
        - "alr": product metadata (OPTIONAL)
          - "pro" (product name) and "ver" (product version) sub-attributes.
        - "tags": array of tags associated with the device (OPTIONAL)
        - "doms": array of domains (OPTIONAL)
          - "n" (domain name) and "g" (domain group name) sub-attributes.
        - "name": device name (OPTIONAL)
      example: '{"loc":{"lat":"43.58081","lon":"1.4421667"},"alr":{"pro":"STL","ver":"1"},"tags":["tag1","tag2"],"doms":[{"n":"France/Paris","g":"Site"},{"n":"Location","g":"Vertical"}],"name":"My device name"}'
  parameters:
    AS_ID:
      name: AS_ID
      in: query
      description: Application Server ID (only reported when the authentication is activated). AS_ID is not reported when the Uplink/downlink authentication is not activated in the AS profile.
      schema:
        type: string
        pattern: ^[0-9A-Za-z\-._]+$
        example: app1.sample.com
    LrnDevEui:
      name: LrnDevEui
      in: query
      description: Device IMEI
      required: true
      schema:
        type: string
        pattern: ^[0-9]{14}$
        example: '35456789012345'
    LrnInfos:
      name: LrnInfos
      in: query
      description: Routing profile name used to route the packet
      required: true
      schema:
        type: string
        example: UPHTTP_LAB_LORA
    Time:
      name: Time
      in: query
      description: ISO 8601 timestamp associated to the generation of the HTTP request by the LRC (only reported when the authentication is activated). Time is not reported when the Uplink/downlink authentication is not activated in the AS profile.
      schema:
        type: string
        format: date-time
        example: '2020-01-11T14:28:00.333+02:00'
    Token:
      name: Token
      in: query
      description: Security token generated by the LRC (only reported when the authentication is activated). Token is not reported when the Uplink/downlink authentication is not activated in the AS profile.
      schema:
        type: string
        pattern: ^[0-9a-f]{64}$
        example: 'ea8f31d2299cbece8e180a3012766c4df15fe3cf2e142d9fdf4035b5894ec886'
  requestBodies:
    Report:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ReportJson'
          examples:
            DevEUI_uplink_MType0:
              summary: Message mode uplink IPv4 packet
              value:
                DevEUI_uplink:
                  Time: '2023-06-12T15:39:09.839+02:00'
                  DevEUI: 'f03d290000000000'
                  Lrcid: '0000000F'
                  MTC: '00000001'
                  Late: 0
                  CustomerID: '199982747'
                  CustomerData:
                    loc:
                      lat: '43.58081'
                      lon: '1.4421667'
                    alr:
                      pro: STL
                      ver: '1'
                    tags:
                      - tag1
                      - tag2
                    doms:
                      - n: France/Paris
                        g: Site
                      - n: Location
                        g: Vertical
                    name: My device name
                  DevAddr: '192.168.3.131'
                  MType: 0
                  EBI: 6
                  payload_hex: '45000022a7b8400040110ab8c0a80383c0a8038799271e61000edc5248454c4c4f0a'
                  UplinkSize: 34
                  IMSI: '234500012232166'
                  IMEI: '86182103901857'
                  APN: internet
                  RAT: EUTRAN
                  SERVNET: '20810'
                  CELLID: '35'
                  CMCCMNC: '20810'
                  CELLTAC: '123'
            DevEUI_uplink_MType1:
              summary: Session creation
              value:
                DevEUI_uplink:
                  Time: '2023-06-12T15:39:09.839+02:00'
                  DevEUI: 'f03d290000000000'
                  Lrcid: '0000000F'
                  MTC: '00000001'
                  Late: 0
                  CustomerID: '199982747'
                  CustomerData:
                    loc:
                      lat: '43.58081'
                      lon: '1.4421667'
                    alr:
                      pro: STL
                      ver: '1'
                    tags:
                      - tag1
                      - tag2
                    doms:
                      - n: France/Paris
                        g: Site
                      - n: Location
                        g: Vertical
                    name: My device name
                  DevAddr: '192.168.3.131'
                  MType: 1
                  EBI: 6
                  IMSI: '234500012232166'
                  IMEI: '86182103901857'
                  APN: internet
                  RAT: EUTRAN
                  SERVNET: '20810'
                  CELLID: '35'
                  CMCCMNC: '20810'
                  CELLTAC: '123'
            DevEUI_uplink_MType2:
              summary: Session deletion
              value:
                DevEUI_uplink:
                  Time: '2023-06-12T15:39:09.839+02:00'
                  DevEUI: 'f03d290000000000'
                  Lrcid: '0000000F'
                  MTC: '00000001'
                  Late: 0
                  CustomerID: '199982747'
                  CustomerData:
                    loc:
                      lat: '43.58081'
                      lon: '1.4421667'
                    alr:
                      pro: STL
                      ver: '1'
                    tags:
                      - tag1
                      - tag2
                    doms:
                      - n: France/Paris
                        g: Site
                      - n: Location
                        g: Vertical
                    name: My device name
                  DevAddr: '192.168.3.131'
                  MType: 2
                  Cause: 10
                  EBI: 6
                  IMSI: '234500012232166'
                  IMEI: '86182103901857'
                  APN: internet
                  RAT: EUTRAN
            DevEUI_uplink_MType3:
              summary: Session update
              value:
                DevEUI_uplink:
                  Time: '2023-06-12T15:39:09.839+02:00'
                  DevEUI: 'f03d290000000000'
                  Lrcid: '0000000F'
                  MTC: '00000001'
                  Late: 0
                  CustomerID: '199982747'
                  CustomerData:
                    loc:
                      lat: '43.58081'
                      lon: '1.4421667'
                    alr:
                      pro: STL
                      ver: '1'
                    tags:
                      - tag1
                      - tag2
                    doms:
                      - n: France/Paris
                        g: Site
                      - n: Location
                        g: Vertical
                    name: My device name
                  DevAddr: '192.168.3.131'
                  MType: 3
                  EBI: 6
                  IMSI: '234500012232166'
                  IMEI: '86182103901857'
                  APN: internet
                  RAT: EUTRAN
                  SERVNET: '20810'
                  CELLID: '35'
                  CMCCMNC: '20810'
                  CELLTAC: '123'
            DevEUI_uplink_MType4:
              summary: Microflow event
              value:
                DevEUI_uplink:
                  Time: '2023-06-12T15:39:09.839+02:00'
                  DevEUI: 'f03d290000000000'
                  Lrcid: '0000000F'
                  MTC: '00000001'
                  Late: 0
                  CustomerID: '199982747'
                  CustomerData:
                    loc:
                      lat: '43.58081'
                      lon: '1.4421667'
                    alr:
                      pro: STL
                      ver: '1'
                    tags:
                      - tag1
                      - tag2
                    doms:
                      - n: France/Paris
                        g: Site
                      - n: Location
                        g: Vertical
                    name: My device name
                  DevAddr: '192.168.3.131'
                  MType: 4
                  EBI: 6
                  IMSI: '234500012232166'
                  IMEI: '86182103901857'
                  APN: internet
                  RAT: EUTRAN
                  SERVNET: '20810'
                  CELLID: '35'
                  CMCCMNC: '20810'
                  CELLTAC: '123'
                  UFDATE: '2023-06-12T15:39:09.839+02:00'
                  UFBUL: '896587'
                  UFBDL: '45821'
                  UFDUR: '10'
            DevEUI_downlink_Sent:
              summary: Message mode downlink sent indication
              value:
                DevEUI_downlink_Sent:
                  Time: '2023-06-12T15:39:09.839+02:00'
                  DevEUI: 'f03d290000000000'
                  Lrcid: '0000000F'
                  MTC: '00000001'
                  CorrelationID: '4434704901C7450B'
                  CustomerID: '199982747'
                  CustomerData:
                    loc:
                      lat: '43.58081'
                      lon: '1.4421667'
                    alr:
                      pro: STL
                      ver: '1'
                    tags:
                      - tag1
                      - tag2
                    doms:
                      - n: France/Paris
                        g: Site
                      - n: Location
                        g: Vertical
                    name: My device name
                  DevAddr: '192.168.3.131'
                  MType: 5
                  Cause: 0
                  EBI: 6
                  IMSI: '234500012232166'
                  IMEI: '86182103901857'
                  APN: internet
                  RAT: EUTRAN
                  SERVNET: '20810'
                  CELLID: '35'
                  CMCCMNC: '20810'
                  CELLTAC: '123'
        application/xml:
          schema:
            $ref: '#/components/schemas/ReportXml'
          examples:
            DevEUI_uplink_MType0:
              summary: Message mode uplink IPv4 packet
              value:
                Time: '2023-06-12T15:39:09.839+02:00'
                DevEUI: 'f03d290000000000'
                Lrcid: '0000000F'
                MTC: '00000001'
                Late: 0
                CustomerID: '199982747'
                CustomerData: '{"loc":{"lat":"43.58081","lon":"1.4421667"},"alr":{"pro":"STL","ver":"1"},"tags":["tag1","tag2"],"doms":[{"n":"France/Paris","g":"Site"},{"n":"Location","g":"Vertical"}],"name":"My device name"}'
                DevAddr: '192.168.3.131'
                MType: 0
                EBI: 6
                payload_hex: '45000022a7b8400040110ab8c0a80383c0a8038799271e61000edc5248454c4c4f0a'
                UplinkSize: 34
                IMSI: '234500012232166'
                IMEI: '86182103901857'
                APN: internet
                RAT: EUTRAN
                SERVNET: '20810'
                CELLID: '35'
                CMCCMNC: '20810'
                CELLTAC: '123'
            DevEUI_uplink_MType1:
              summary: Session creation
              value:
                Time: '2023-06-12T15:39:09.839+02:00'
                DevEUI: 'f03d290000000000'
                Lrcid: '0000000F'
                MTC: '00000001'
                Late: 0
                CustomerID: '199982747'
                CustomerData: '{"loc":{"lat":"43.58081","lon":"1.4421667"},"alr":{"pro":"STL","ver":"1"},"tags":["tag1","tag2"],"doms":[{"n":"France/Paris","g":"Site"},{"n":"Location","g":"Vertical"}],"name":"My device name"}'
                DevAddr: '192.168.3.131'
                MType: 1
                EBI: 6
                IMSI: '234500012232166'
                IMEI: '86182103901857'
                APN: internet
                RAT: EUTRAN
                SERVNET: '20810'
                CELLID: '35'
                CMCCMNC: '20810'
                CELLTAC: '123'
            DevEUI_uplink_MType2:
              summary: Session deletion
              value:
                Time: '2023-06-12T15:39:09.839+02:00'
                DevEUI: 'f03d290000000000'
                Lrcid: '0000000F'
                MTC: '00000001'
                Late: 0
                CustomerID: '199982747'
                CustomerData: '{"loc":{"lat":"43.58081","lon":"1.4421667"},"alr":{"pro":"STL","ver":"1"},"tags":["tag1","tag2"],"doms":[{"n":"France/Paris","g":"Site"},{"n":"Location","g":"Vertical"}],"name":"My device name"}'
                DevAddr: '192.168.3.131'
                MType: 2
                Cause: 10
                EBI: 6
                IMSI: '234500012232166'
                IMEI: '86182103901857'
                APN: internet
                RAT: EUTRAN
            DevEUI_uplink_MType3:
              summary: Session update
              value:
                Time: '2023-06-12T15:39:09.839+02:00'
                DevEUI: 'f03d290000000000'
                Lrcid: '0000000F'
                MTC: '00000001'
                Late: 0
                CustomerID: '199982747'
                CustomerData: '{"loc":{"lat":"43.58081","lon":"1.4421667"},"alr":{"pro":"STL","ver":"1"},"tags":["tag1","tag2"],"doms":[{"n":"France/Paris","g":"Site"},{"n":"Location","g":"Vertical"}],"name":"My device name"}'
                DevAddr: '192.168.3.131'
                MType: 3
                EBI: 6
                IMSI: '234500012232166'
                IMEI: '86182103901857'
                APN: internet
                RAT: EUTRAN
                SERVNET: '20810'
                CELLID: '35'
                CMCCMNC: '20810'
                CELLTAC: '123'
            DevEUI_uplink_MType4:
              summary: Microflow event
              value:
                Time: '2023-06-12T15:39:09.839+02:00'
                DevEUI: 'f03d290000000000'
                Lrcid: '0000000F'
                MTC: '00000001'
                Late: 0
                CustomerID: '199982747'
                CustomerData: '{"loc":{"lat":"43.58081","lon":"1.4421667"},"alr":{"pro":"STL","ver":"1"},"tags":["tag1","tag2"],"doms":[{"n":"France/Paris","g":"Site"},{"n":"Location","g":"Vertical"}],"name":"My device name"}'
                DevAddr: '192.168.3.131'
                MType: 4
                EBI: 6
                IMSI: '234500012232166'
                IMEI: '86182103901857'
                APN: internet
                RAT: EUTRAN
                SERVNET: '20810'
                CELLID: '35'
                CMCCMNC: '20810'
                CELLTAC: '123'
                UFDATE: '2023-06-12T15:39:09.839+02:00'
                UFBUL: '896587'
                UFBDL: '45821'
                UFDUR: '10'
            DevEUI_downlink_Sent:
              summary: Message mode downlink sent indication
              value:
                Time: '2023-06-12T15:39:09.839+02:00'
                DevEUI: 'f03d290000000000'
                Lrcid: '0000000F'
                MTC: '00000001'
                CorrelationID: '4434704901C7450B'
                CustomerID: '199982747'
                CustomerData: '{"loc":{"lat":"43.58081","lon":"1.4421667"},"alr":{"pro":"STL","ver":"1"},"tags":["tag1","tag2"],"doms":[{"n":"France/Paris","g":"Site"},{"n":"Location","g":"Vertical"}],"name":"My device name"}'
                DevAddr: '192.168.3.131'
                MType: 5
                Cause: 0
                EBI: 6
                IMSI: '234500012232166'
                IMEI: '86182103901857'
                APN: internet
                RAT: EUTRAN
                SERVNET: '20810'
                CELLID: '35'
                CMCCMNC: '20810'
                CELLTAC: '123'
tags:
  - name: reports
    description: Device reports
