.wpb_animate_when_almost_visible { opacity: 1; }

Device Roaming Status - CAMARA Sandbox - Orange lab 0.1 Beta

This API provides the customer with the ability to query device roaming Status

Use this API Contact us

Getting started



Disclaimer (sandboxed version)

This CAMARA Sandbox - Device Roaming Status - Orange lab API is a sandboxed version of the production-grade CAMARA - Device Roaming Status API.

It is running in our lab, against a small list of lab-specific mobile devices (see list of phone number available for test below).

This API could be suspended or upgraded any time without any notice.

Introduction

The CAMARA Device Roaming Status API provides a standardized mechanism for getting mobile equipment Roaming status.

Subscribe to the API

You get the Authorization header credentials when you register your application on the Orange Developer Console.

API Authentication

Note: In production environment the Device Roaming Status API will require a 3-Legged OAuth 2.0 flow but as this implementation is provided on Orange Lab, the API works with a 2-Legged OAuth (OAuth 2 with client credentials).

HTTPS requests to the REST API are protected with 2-Legged OAuth. To learn more about how Orange Developer handles authentication, please refer to our documentation.

In short, you will use your Orange Developer Authorization header as authorization_header for the Basic authentication with Orange Developer.

curl -X POST \
-H "Authorization: {{ authorization_header }}" \
-d "grant_type=client_credentials" \
https://api.orange.com/oauth/v3/token

In response, you will get an access_token.

{
       "token_type": "Bearer",
       "access_token": "66AeYJF8eJQ...2SjkFg9LB1LePC",
       "expires_in": "3600"
}

Go up

API Description

Summary of resources

This API has one resource retrieve. In the response, the roaming status is provided but also information of the last status time and country of presence in case of roaming situation.

Summary of methods and URL

Use case of operationURL method
I want to get roaming information of a device from a MSISDN number, an external identifier or an IP (+port)POST "https://api.orange.com/camara/orange-lab/device-roaming-status/v0/retrieve"

Go up

Summary of request body parameters

NameDescriptionTypeMandatory
deviceAn object with four fields, each of them make possible to pass device identifier in different format: externalId , msisdn, ipv4Addr and ipv6AddrSee below information on deviceNo

Following table provide details about device:

NameTypeDescription
externalIdstringExternal Identifier format of the GPSI. Not managed in our implementation
phoneNumberstringSubscriber number in E.164 format (starting with country code). Must be prefixed with '+'
Ipv4AddrstringIPv4 address may be specified in form <address/mask>. If address we expect an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule. If address/mask - an IP number as above with a mask width of the form 1.2.3.4/24. Not managed in our implementation
Ipv6AddrstringIPv6 address, following IETF 5952 format, may be specified in form <address/mask>. If address, the /128 subnet is optional for single address (2001:db8:85a3:8d3:1319:8a2e:370:7344 or 2001:db8:85a3:8d3:1319:8a2e:370:7344/128). If address/mask, an IP v6 number with a mask (2001:db8:85a3:8d3::0/64 or 2001:db8:85a3:8d3::/64 ). Not managed in our implementation

Lab implementation specific:

Only requests using phoneNumber are operational. Following phone number must be used (other will not work):

msisdn
33699901031
33699901032
33699901033
33699901034
33699901035
33699901036
33699901037
33699901038
33699901039
33699901040
33699901064

Example of body query

{
"device": {
    "phoneNumber": "33699901032"
   }
}

Go up

Request mobile equipment status (from phone number)

Request
curl -X POST "https://api.orange.com/camara/orange-lab/device-roaming-status/v0/status"
-H "Authorization: Bearer {your access token}"
-H "Cache-Control: no-cache"  
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d  '{
"device": {
    "phoneNumber": "+33699901032"
  }
}
Response
200 OK
Content-Type: application/json
{
  "lastStatusTime": "2024-07-22T12:23:21.112125501Z",
  "roaming": false,
  "countryName": []
}

Go up

Fields description

In the response following attributes are provided:

NameTypeDescriptionMandatory
lastStatusTimestring(datetime)Last time that the associated device roaming status was updatedNo
roamingbooleanRoaming status. True, if it is roamingYes
countryCodestringThe Mobile country code (MCC) as an geographic region identifier for the country and the dependent areas.No
countryNamestringThe ISO 3166 ALPHA-2 country-codes of mapped to mobile country code(MCC). If there is mapping of one MCC to multiple countries, then we have list of countries. If there is no mapping of MCC to any country, then an empty array [] shall be returned.No

Note: As this is a lab implementation our devices are not supposed to move in roaming.

Go up

Most frequent errors

If invalid input are provided in particular for the ueId a 400 error is triggered.

HTTP/1.1 400 Invalid input
Content-Type: application/json
{
  "code": "INVALID_ARGUMENT",
  "status": 400,
  "message": "Invalid input"
}

if a non-managed msisdn is provided a 500 error is triggered.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
{
  "status": 500,
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Internal Server Error, status code 500"
}

There are some cases where your client application will no longer gain access to API resources, and get an error back.

Please check the following points:

  • Here, you attempt to use an expired or revoked access_token and you get an invalid token error. You will have to request a new access_token. As an example:
HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "code": "UNAUTHENTICATED",
  "status": 401,
  "message": "Authorization failed: ..."
}
  • Here, you removed your subscription to the API so that the capability to generate an access_token is not allowed anymore. As an example:
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
  "code": "PERMISSION_DENIED",
  "status": 403,
  "message": "Operation not allowed: ..."
}

Looking for support ?

Facing technical issue when using this API ? please contact us

Go up

History of document

Version of the documentmodification datedescription of modifications
1.019/08/2024initialization by Orange CAMARA APIs team

Go up