SORACOM Developers

Documents

SORACOM API Sandbox User Guide

Here, we provide necessary information for use of SORACOM API Sandbox.

Outline

SORACOM API Sandbox (hereinafter “Sandbox”) is a platform that enables you to learn how to use SORACOM API and try out an API. Since APIs operating on Sandbox will not affect the actual Air SIM, it enables you to try processing that is difficult to call on an API (termination, etc.).

Please read through the SORACOM API User Guide in advance.

To use Sandbox, you must have an account in the production environment.

Precautions

Please be aware of the precautions below upon using Sandbox.

  1. Sandbox may conduct some operations that differ from the production environment. For instance, an event handler can be set up, but the event handler may not activate even if it meets conditions under the present circumstances.

  2. Information saved on Sandbox is not guaranteed to persist. The database may be cleaned at SORACOM’s convenience. Accordingly, be sure to conduct tests after you construct an environment after creating an operator (sign up) whenever you conduct CI (continuous integration) using SORACOM API Sandbox. Please feel free to use the Sandbox API, as it is available for you to use.

  3. Sandbox is a service offered on a best offer basis. We may conduct maintenance for version upgrades without prior notice. As always, the Support will handle inquiries regarding Sandbox. However, the Support will prioritize handling inquiries regarding production environments.

Use SORACOM API Sandbox

Here, we will explain the procedure to use the Sandbox environment as follows.

  1. Prepare SAM user in the production environment (just once)
  2. Create operator in the Sandbox environment
  3. Create and register false SIM in the Sandbox environment

1. Prepare SAM User in the Production Environment

Information, including user account (operator) and SIM (subscriber), will not be shared with the production environment in the Sandbox environment.

However, be sure to create a SAM user and generate certification key in advance in the production environment since it is required to confirm that you have an account in the production environment.

It is not necessary to grant authorization to this SAM user. Also, it is not necessary to be able to log in to a console in the production environment with this SAM user. In order to prevent unintended operation, we recommend creating a special account that is not granted with authorization or that is not able to log in to a console.

Please refer to Manage Operation Authorization using SORACOM Access Management for how to create a SAM user and how to generate a certification key.

Also, be sure to create a SAM user in the production environment once at the beginning as preparation for using the Sandbox environment. Once you create the SAM user and authorization key, you can repeatedly use them after that.

2. Create an Operator in the Sandbox Environment

After you create the SAM user and generate the authorization key in the production environment, move on to work in the Sandbox environment. The following are required preparations every time you use the Sandbox environment.

2-1. Create operators in the Sandbox environment

First, it is necessary to create a dedicated operator for Sandbox.

However, since there is no console screen for the Sandbox environment, you need to create an operator using the API. Previously, I ordered the normal sign up API, but as the procedure was complicated, I prepared a new API which makes it easy to sign up. Please create an operator by calling / v1 / sandbox / init API as follows.

curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{ "email": "email@example.com", "password": "superStrongP@ssw0rd", "authKeyId": "< Authentication key ID of SAM user in production environment >", "authKey": "< Authentication key secret of SAM user in production environment >" }' \
     https://api-sandbox.soracom.io/v1/sandbox/init

# Response:
# 201 Created
# {
#   "operatorId": "OPXXXXXXXXXX",
#   "apiKey": "< Random character string>",
#   "token": "< Random character string>"
# }

Please use a different mail address each time. If you are using Gmail, you can add your favorite string with a + sign behind the user name, such as username+@gmail.com, so it’s a good idea to use those functions.

In addition, API Key and API Token are returned as API return values. Please use this API token for subsequent API calls. (API key does not change)

Since fictitious payment information (test credit card number) has been registered at this point, it is possible to call any API after that.

3. Register False Payment Information

In order to call the API, the SIM to be operated by the API is required. Let’s register the SIM in the Sandbox environment. IMSI and passcode are required to register SIM. In the Sandbox environment, instead of registering actual SIM information, create a fictitious SIM and register it.

First of all, create a fictitious SIM with the following API for Sandbox only.

curl -X POST https://api-sandbox.soracom.io/v1/sandbox/subscribers/create

# Response:
# 200 OK
# {
#   "imsi": "生成された SIM の IMSI",
#   "msisdn": "生成された SIM の MSISDN",
#   "registrationSecret": "生成された SIM を登録するときに必要なパスコード",
#      :
# }

Register the imaginary SIM created here in the account with the normal API as follows.

curl -X POST \
     -H 'Content-Type: application/json' \
     -H 'X-Soracom-API-Key: <verify API Key>' \
     -H 'X-Soracom-Token: <verify signup token>' \
     -d '{ "cvc": "123", "expireMonth": 12, "expireYear": 20, "name": "SORAO TAMAGAWA", "number": "4242424242424242" }' \
     https://api-sandbox.soracom.io/v1/payment_methods/webpay

# Response:
# 200 OK
# {
#   "imsi": "IMSI of the generated SIM",
#   "msisdn": "MSISDN of the generated SIM",
#      :
# }

Repeat create -> register for the number of required SIMs.

If you can prepare so far, you can call various APIs for SIM.

As an example, let’s take a list of SIMs just registered.

curl -X GET \
     -H 'Content-Type: application/json' \
     -H 'X-Soracom-API-Key: < apiKey obtained by /v1/sandbox/init >' \
     -H 'X-Soracom-Token: < token btained by /v1/sandbox/init> ' \
     https://api-sandbox.soracom.io/v1/subscribers

# Response:
# 200 OK
# [
#   {
#     "imsi": "00101xxxxxxxxxx",
#     "msisdn": "99xxxxxxxxxx",
#     "ipAddress": "10.xxx.xxx.xxx",
#     "operatorId": "OP00xxxxxxxx",
#     "apn": "soracom-sandbox.io",
#     "type": "s1.standard",
#      :
#   }
# ]

What do you think. In addition to this, you can also call other APIs such as Group and Event Handler, as well as SIM.

Please try out various things by all means.

Sandbox API Reference

Below are APIs dedicated to the Sandbox environment. Please refer to SORACOM API Reference for common production environments with normal APIs.

Getting Started

SORACOM Air for Cellular

SORACOM Air for Sigfox

SORACOM Beam

SORACOM Canal/Direct/Door

SORACOM Endorse

SORACOM Funnel

SORACOM Gate

SORACOM Harvest

SORACOM Inventory

SORACOM Junction

SORACOM Krypton

SORACOM Lagoon

Service Detail

Developer Tools

pagetop