Einrichtung

API for raising and querying tickets in the Crout Control Center (CCC).

Getting Started

You’ll need an account set up in the CCC portal before you will be able to use these APIs.

Request Structure

Parameters

Each API Method will have its own parameters. Unless stated otherwise each request should also contain two elements:

{
"user": {
"username": "...",
"password": "..."
},
"service": {
"code": "...",
"cli": "...",
"sim": "..."
}
}
 
Params Type Required
user object true
user.username string true
user.password string true
service object true
service.code string At least one code or cli or sim
service.cli string At least one code or cli or sim
service.sim string At least one code or cli or sim

Method

The individual HTTP methods will be individually described in the following.

Description of individual HTTP methods:

1. Get Contracts

List the Contracts belonging to a Customer.

The „Get Contracts“ method is used to retrieve the Contract Codes used for a specific Customer Code.  The retrieved CODE value(s) returned from „Get Contracts“ is needed as the „contractCode“ attribute for the „Connect Service“ method.

NOTE: Usually there is only one contract existing for one customer.

Example “Get Contracts” Request

POST /v1/getContracts
{
"user": {
"username": "MarioG",
"password": "Stuttgart"
},
"customer": "1000000"
}

description of the parameters:

customer: The customer attribute should be populated with your Customer Account Number.  This is displayed next to your account in the Crout Control Centre (CCC) portal. 

Example “Get Contracts” Response (Success)

{
"ok": true,
"contracts": [
{
"CODE": "1000274",
"NAME": "MarioG18",
"ACTIVE_SERVICES": 217
},
{
"CODE": "1900274",
"NAME": "MarioG19",
"ACTIVE_SERVICES": 11
}
]
}

Example “Get Contracts” Response (Error)

{
"ok": false,
"errorCode": "209",
"errorMessage": "'customer' missing."
}

2. Connect Service

Raise a ticket to connect a new service.

NOTE: You have first to retrieve the „contractCode“ value using the „Get Contracts“ method before you can call the „Connect Service“ method. 

Parameters:

These are in addition to the standard parameters.

NOTE: The service block is not required here

Params Type Required
sim string true
name string true
contractCode string true
tariffCode string true
APNCodes string false

Example “Connect Service” Request

POST /v1/connectService
{
"user": {
"username": "MarioG",
"password": "Stuttgart"
},
"sim": "8910390000015161789",
"contractCode": "200035680",
"tariffCode": "TEASEU1000MB",
"APNCodes": "AS_APN_CROUT",
"name": "IMK Test"
}

description of the parameters:

sim: ICCID (SIM Number) that is to be activated

name: SIM Name (Service Username) for the SIM that is to be activated

contractCode: CODE value returned for the applicable customer account using the „Get Contracts“ method

tariffCode: The unique code for the product on which you wish to activate the SIM.  You can obtain a list of applicable values from the „Tariffs“ section of the „Selfcareable Products“ screen in the CCC portal.

APNCodes: The unique code for the APN(s) you wish to activate along with the SIM.  You can obtain a list of applicable values from the „APNs“ section of the „Selfcareable Products“ screen in the CCC portal.

Example “Connect Service” Response (Success)

{
"ok": true,
"ticket": {
"id": "1226",
"status": "Processing"
}
}

Example “Connect Service” Response (Error)

{
"ok": false,
"errorCode": "208",
"errorMessage": "'sim' missing."
}

3. Disconnect Service

Raise a ticket to disconnect an active service.

Parameters:

These are in addition to the standard parameters.

Params Type Required
newSIM string true

Example “Disconnect Service” Request

POST /v1/disconnectService
{
"user": {
"username": "MarioG",
"password": "Stuttgart"
},
"service":{
"cli": "07718123456"
}
}

description of the parameters:

cli: MSISDN of service that is to be deactivated.  You can pass „code“ (Service Code) or sim (ICCID) instead if you prefer, as detailed in „Request Structure“ section.

Example “Disconnect Service” Response (Success)

{
"ok": true,
"ticket": {
"id": "1227",
"status": "Processing"
}
}

Example “Disconnect Service” Response (Error)

{
"ok": false,
"errorCode": "302",
"errorMessage": "Service is not Active."
}

4. Change Service Name

Raise a ticket to change the name on an active service.

Parameters:

These are in addition to the standard parameters.

Params Type Required
newName string true

Example “Change Service Name” Request

{
"user": {
"username": "MarioG",
"password": "Stuttgart"
},
"service":{
"cli": "07836123456"
},
"newName": "IMK Testing 2"
}

description of the parameters:

newName: The new Service Username for the SIM.  Max 50 characters in length.

cli: MSISDN of service that you wish to change the Service Username for.  You can pass „code“ (Service Code) or sim (ICCID) instead if you prefer, as detailed in „Request Structure“ section.

Example “Change Service Name” Response (Success)

{
"ok": true,
"ticket": {
"id": "1228",
"status": "Processing"
}
}

Example “Change Service Name” Response (Error)

{
"ok": false,
"errorCode": "205",
"errorMessage": "'newName' missing."
}

5. Add Bar

Raise a ticket to add a bar to a service.

NOTE: The „AS_SUS_MSISDN“ bar suspends the SIM at the network meaning that the full service will be blocked.

Parameters:

These are in addition to the standard parameters.

Params Type Required
barCode string true

Example “Add Bar” Request

POST /v1/addBar
{
"user": {
"username": "MarioG",
"password": "Stuttgart"
},
"service":{
"cli": "07831123456"
},
"barCode": "AS_SUS_MSISDN"
}

description of the parameters:

barCode: Bar code of „suspension“ bar to be added at the network.  Possible values: „AS_SUS_MSISDN“ (Suspend SIM).

cli: MSISDN of service that you wish to suspend at the network.  You can pass „code“ (Service Code) or sim (ICCID) instead if you prefer, as detailed in „Request Structure“ section.

Example “Add Bar” Response (Success)

{
"ok": true,
"ticket": {
"id": "1224",
"status": "Processing"
}
}

Example “Add Bar” Response (Error)

{
"code": "102",
"message": "You do not have permission to update this Bar (BF_002)",
"ok": false
}

6. Remove Bar

Raise a ticket to remove a bar from a service.

NOTE: Removing the „AS_SUS_MSISDN“ bar results in the resumption of full service at the network for the SIM.

Parameters:

These are in addition to the standard parameters.

Params Type Required
barCode string true

Example “Remove Bar” Request

POST /v1/removeBar
{
"user": {
"username": "MarioG",
"password": "Stuttgart"
},
"service":{
"cli": "07831123456"
},
"barCode": "AS_SUS_MSISDN"

description of the parameters:

barCode: Bar code of „suspension“ bar to be lifted at the network.  Possible values: „AS_SUS_MSISDN“ (Suspend SIM).

cli: MSISDN of service that you wish to resume full network services.  You can pass „code“ (Service Code) or sim (ICCID) instead if you prefer, as detailed in „Request Structure“ section.

Example “Remove Bar” Response (Success)

{
"ok": true,
"ticket": {
"id": "1225",
"status": "Processing"
}
}

Example “Remove Bar” Response (Error)

{
"ok": false,
"errorCode": "200",
"errorMessage": "'barCode' missing."
}

7. Query Service

Query the status of a service. This will return the status at the network where available.

Example “Query Service” Request

POST /v1/queryService
{
"user": {
"username": "MarioG",
"password": "Stuttgart"
},
"service":{
"cli": "07979123456"
}
}

description of the parameters:

cli: MSISDN of service that you wish to query at network.  You can pass „code“ (Service Code) or sim (ICCID) instead if you prefer, as detailed in „Request Structure“ section.

Example “Query Service” Response (Success)

{
"ok": true,
"service": {
"nina": {
"code": "5012345",
"name": "Marion Gomez",
"status_code": "A",
"cli": "07979123456",
"sim": "8944110011462295831",
"network": "AS",
"contract": "2001288",
"customer": "1023896"
}
}
}

Example “Query Service” Response (Error)

{
"ok": false,
"errorCode": "104",
"errorMessage": "'service' missing."
}

8. Change SIM (not supported yet)

Authentication

You can use your existing login credentials for the Zygo portal to access the API.

As detailed in the the Request Structure section you should pass your username/password in the user item on the request.

You can use your existing login credentials for the Zygo portal to access the API.

As detailed in the the Request Structure section you should pass your username/password in the user item on the request.

Response Structure

The response for each API Method will be detailed in the documentation for each individual API Method.

Generally there are two types of response:

Ticket Raised

Requesting something to happen on the system will generally result in a ticket being raised. This ticket will then be processed.

Details Returned

Requesting information from the system will result in that information, when it is available, being returned.

Error Response

When the request is not successful you will receive details of the error.

{
ok: false,
errorCode: '...',
errorMessage: '...'
}

Errors

Code Message
000 Zygo portal undergoing maintenance.
001 Internal Error.
100 Authentication failed.
101 Service Locked. Another ticket is processing.
102 You do not have permission to update this Bar
103 You do not have permission to update this Bolt On
104 service missing.
105 You do not have premission to access this service.
200 barCode missing.
201 ticketType missing.
202 message missing.
203 file missing.
204 boltonCode missing.
205 newName missing.
206 contractCode missing.
207 templateCode missing.
208 newSIM missing.
208 sim missing.
209 customer missing.
300 sim invalid.
301 ticketType invalid.
302 Service is not Active.
400 Could not find Service.
401 Could not find Ticket
402 SIM not available to Customer
403 Could not find Contract
404 Could not find Template
405 Could not find APN