openapi: 3.0.3
info:
  title: Telefónica Status Device Roaming QoD Sessions API
  description: The Device Roaming Status API verifies the roaming status of a SIM-based device using carrier network data, without relying on GPS or risking identity information exposure. Enables fraud detection, content geo-restriction, and compliance workflows. Based on CAMARA open standards. Available in Spain and Brazil.
  version: 0.5.0
  contact:
    url: https://opengateway.telefonica.com/en/apis/device-roaming-status
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://opengateway.telefonica.com/v1
  description: Telefónica Open Gateway - Production
- url: https://sandbox.opengateway.telefonica.com/v1
  description: Telefónica Open Gateway - Sandbox
tags:
- name: QoD Sessions
paths:
  /qod/sessions:
    post:
      operationId: createQodSession
      summary: Create QoD Session
      description: Creates a Quality on Demand session, assigning a specific QoS profile to a device for the specified duration. The network guarantees the requested quality parameters for the session duration.
      tags:
      - QoD Sessions
      security:
      - openIdConnect:
        - qod:sessions:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
      responses:
        '201':
          description: QoD session created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionInfo'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
        '409':
          description: Session already exists for this device.
    get:
      operationId: listQodSessions
      summary: List QoD Sessions
      description: Retrieve all active QoD sessions.
      tags:
      - QoD Sessions
      security:
      - openIdConnect:
        - qod:sessions:read
      responses:
        '200':
          description: List of active QoD sessions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SessionInfo'
        '401':
          description: Unauthorized.
  /qod/sessions/{sessionId}:
    get:
      operationId: getQodSession
      summary: Get QoD Session
      description: Retrieve information about a specific QoD session.
      tags:
      - QoD Sessions
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      security:
      - openIdConnect:
        - qod:sessions:read
      responses:
        '200':
          description: QoD session details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionInfo'
        '404':
          description: Session not found.
    delete:
      operationId: deleteQodSession
      summary: Delete QoD Session
      description: Terminate and delete an active QoD session.
      tags:
      - QoD Sessions
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      security:
      - openIdConnect:
        - qod:sessions:write
      responses:
        '204':
          description: Session deleted successfully.
        '404':
          description: Session not found.
components:
  schemas:
    Device:
      type: object
      properties:
        phoneNumber:
          type: string
          pattern: ^\+[1-9][0-9]{4,14}$
        networkAccessIdentifier:
          type: string
        ipv4Address:
          type: object
          properties:
            publicAddress:
              type: string
            publicPort:
              type: integer
        ipv6Address:
          type: string
    SessionInfo:
      type: object
      properties:
        sessionId:
          type: string
          format: uuid
          description: Unique session identifier.
        device:
          $ref: '#/components/schemas/Device'
        qosProfile:
          type: string
          description: Assigned QoS profile.
        qosStatus:
          type: string
          description: Current QoS session status.
          enum:
          - REQUESTED
          - AVAILABLE
          - UNAVAILABLE
        startedAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        duration:
          type: integer
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
        code:
          type: string
        message:
          type: string
    CreateSessionRequest:
      type: object
      required:
      - device
      - qosProfile
      - duration
      properties:
        device:
          $ref: '#/components/schemas/Device'
        applicationServer:
          $ref: '#/components/schemas/ApplicationServer'
        qosProfile:
          type: string
          description: QoS profile name defining connectivity quality parameters.
          enum:
          - QOS_E
          - QOS_S
          - QOS_M
          - QOS_L
        duration:
          type: integer
          description: Session duration in seconds. Maximum 86400 (24 hours).
          minimum: 1
          maximum: 86400
        notificationUrl:
          type: string
          format: uri
          description: Webhook URL for session status change notifications.
        notificationAuthToken:
          type: string
          description: Authentication token for webhook notifications.
    ApplicationServer:
      type: object
      properties:
        ipv4Address:
          type: string
        ipv6Address:
          type: string
  securitySchemes:
    openIdConnect:
      type: openIdConnect
      openIdConnectUrl: https://opengateway.telefonica.com/.well-known/openid-configuration