RestFul API 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.
Please note that all provisioning request (i.e. Connect/Disconnect Service, Change Service Name or Add/Remove Bar) will create a CCC ticket for each SIM card. The CCC ticket handles your request (i.e. activations) and sends them to the network. If you activate only one or a few SIM cards the processing of these tickets takes a few minutes, but if you activate larger amounts of SIM cards it can also take hours until all SIM cards and the according tickets are handled. If you send another API request for a SIM card which has already a pending ticket, you will receive the error message „Service Locked. Another ticket is processing. / error code:101“. In this case you should wait until the already pending ticket is successfully handled.
You can check the status of your open tickets in the upper right corner of your CCC Portal. You will find notifications or here as well, if you click on the bell icon:

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
|
Endpoint for the API request: https://ctde.nina.zygo.net/api/v1/xxx
(substitute xxx by the individual Method, see below)
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
POST /v1/changeServiceName
{
"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.
status_code return parameters:
„A“ (Active): The SIM is linked to a Service and the Service has been activated.
„B“ (Barred / Suspended): The Service has had a „Suspend“ bar applied to the SIM at the network.
„S“ (Switched Off): The Service has been disconnected in the billing system but has not yet had a final invoice
„C“ (Closed): The Service has been disconnected in the billing system and has had a final invoice
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.
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 |
9. Send SMS
Send an SMS is an API request, exclusive to your Conekkt KE SIM cards
Parameters
Params | Type | Required |
text | string |
true
|
Example „Send SMS“ Request
POST /v1/sendSMS
{
"user": {
"username": "MarioG",
"password": "Stuttgart"
},
"service":{
"sim": "89490200001122333682"
},
"text": "test"
}
Example „Send SMS“ Response (Success)
{
"ok": true,
"id": "1067566",
"dateSubmitted": "2021-01-08T10:45:05+00:00",
"content": "test",
"deliveryReport": [
{
"iccid": "8944477100000052905",
"deliveryStatus": "PENDING"
}
]
}
Example „Send SMS“ Response (Error)
{
"ok": false,
"errorCode": "200",
"errorMessage": "'text' missing."
}
War das hilfreich? / Was this helpful?