openapi: 3.0.3
info:
  title: Telefónica Device Roaming Status 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
paths:
  /device-roaming/retrieve:
    post:
      operationId: getDeviceRoamingStatus
      summary: Get Device Roaming Status
      description: >-
        Returns the current roaming status of a device. Indicates whether
        the device is roaming and, if available, the country code of the
        network the device is currently connected to.
      tags:
        - Device Roaming
      security:
        - openIdConnect:
            - device-roaming-status:read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - device
              properties:
                device:
                  $ref: '#/components/schemas/Device'
      responses:
        '200':
          description: Device roaming status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoamingStatusResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
        '422':
          description: Unable to determine roaming status.
components:
  securitySchemes:
    openIdConnect:
      type: openIdConnect
      openIdConnectUrl: https://opengateway.telefonica.com/.well-known/openid-configuration
  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
    RoamingStatusResponse:
      type: object
      properties:
        roaming:
          type: boolean
          description: True if the device is currently roaming.
        countryCode:
          type: integer
          description: MCC (Mobile Country Code) of the network the device is connected to.
        countryName:
          type: array
          description: Name of the country in multiple languages.
          items:
            type: string
        lastStatusTime:
          type: string
          format: date-time
          description: Timestamp when the roaming status was last updated.
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
        code:
          type: string
        message:
          type: string