MLS Safe

Έκδοση 3

Ο σκοπός της εφαρμογής MLS Safe είναι η ασφαλής διαχείριση συσκευών MLS και το κλείδωμά τους σε περίπτωση μη τήρησης του συμφωνητικού πληρωμών από την πλευρά του παρόχου από τον οποίο αγοράζονται. Η εφαρμογή παρέχει ένα πλήθος ενεργειών για τη διαχείριση αυτών των συσκευών.

Το συγκεκριμένο έγγραφο θα περιγράψει τη δομή των δεδομένων τα οποία διαχειρίζεται η εφαρμογή, καθώς επίσης και το API interface που προσφέρει μέσω του MLS Apps API.

Δομή Εφαρμογής

Η εφαρμογή χωρίζεται σε 2 βασικά τμήματα: τις συσκευές οι οποίες είναι εγγεγραμμένες στην εφαρμογή και οι ενέργειες που μπορούν να γίνουν στις συσκευές ανάλογα με την κατάστασή τους και τις εντολές του παρόχου.

Πάροχος, πακέτα και συσκευές

Ως πάροχος θεωρείται η κάθε εταιρία τηλεπικοινωνίας η οποία παρέχει στους χρήστες συσκευές MLS με την προϋπόθεση τήρησης του συμφωνητικού τιμολόγησης ώστε να έχουν το δικαίωμα χρήσης της συσκευής.

Ο κάθε πάροχος μπορεί να προσθέσει πλήθος συσκευών (τηλέφωνα, tablets κλπ.) για διαχείριση. Οι συσκευές μπορούν να χωριστούν σε πακέτα, τα batches, τα οποία μπορούν να διαχειριστούν ξεχωριστά ως προς το κλείδωμα. Ένας πάροχος μπορεί να δημιουργήσει μηδέν ή περισσότερα πακέτα κάθε ένα από τα οποία μπορούν να έχουν μηδέν ή περισσότερες συσκευές.

Ως συσκευή θεωρείται κάθε τηλέφωνο, tablet ή άλλη συσκευή η οποία αγοράζεται από κάποιον χρήστη με δέσμευση συμβολαίου παρόχου και έχει φορτωμένη την εφαρμογή MLS Safe.

Δεδομένα, κατάσταση και ενέργειες

Η κάθε συσκευή αναγνωρίζεται από το μοναδικό για αυτή κωδικό αριθμό IMEI και περιέχει πληροφορίες για την τρέχουσα κατάστασή της.

Κάθε συσκευή αρχικοποιείται από το σύστημα και είναι ελεύθερη για διαχείριση από τον πάροχο στον οποίο έχει ανατεθεί. Κάθε συσκευή μπορεί να βρίσκεται σε 4 διαφορετικές καταστάσεις και η μετάβαση σε αυτές δεν προϋποθέτει κάποια συγκεκριμένη σειρά:

  • Ξεκλείδωτη συσκευή - Unlocked, αυτή είναι η αρχική κατάσταση όλων των συσκευών μετά την πρώτη φορά που θα επικοινωνήσουν με την υπηρεσία.
  • Προειδοποιημένη συσκευή - Warned, η συσκευή έχει ενημερωθεί για εκκρεμότητες σε βάρος της πληρωμής του λογαριασμού.
  • Κλειδωμένη συσκευή - Locked, η συσκευή δεν έχει συμμορφωθεί με τους όρους του παρόχου και βρίσκεται σε κατάσταση κλειδώματος (μόνιμη εμφάνιση οθόνης κλειδώματος και αποτροπή ενεργειών χρήστη).
  • Μόνιμα κλειδωμένη συσκευή - Final Locked/Cancelled, η συσκευή ήταν κλειδωμένη για κάποιο χρονικό διάστημα και πλέον έχει κλειδωθεί μόνιμα και χαρακτηρίζεται ως ακυρωμένη από τον πάροχο.

Ενέργειες

Η μετάβαση μιας συσκευής από μια κατάσταση σε μια άλλη πραγματοποιείται με τη χρήση ενεργειών μέσω της εφαρμογής και των υπηρεσιών που προσφέρει. Η διαδικασία δημιουργίας ενέργειας και μετάβασης σε μια κατάσταση είναι η εξής:

  1. Δημιουργία ενέργειας από την πλευρά του διαχειριστή, σημειώνεται ως [Status Request]. Υπάρχει μια ενέργεια για κάθε κατάσταση που αναφέρθηκε παραπάνω.
  2. Στην επόμενη επικοινωνία της συσκευής με την υπηρεσία θα σημειωθεί η ενέργεια ότι παραδόθηκε και η συσκευή θα μεταβεί στην κατάσταση αυτή.

Υπάρχει υπηρεσία η οποία επιστρέφει το πλήθος των διαθέσιμων ενεργειών. Αναφέρεται στην ενότητα API Interface / Ενέργειες Συσκευής.

Κάθε πακέτο περιλαμβάνει επιπλέον πληροφορίες σχετικά με αυτόματες ενέργειες που μπορούν να ενεργοποιηθούν στις συσκευές. Έτσι, κάθε πακέτο έχει 2 ρυθμίσεις, εάν θα γίνεται το αυτόματο κλείδωμα μετά από τη δημιουργία ενέργειας προειδοποίησης και μετά από πόσες μέρες θα γίνεται. Περισσότερες πληροφορίες παρακάτω στην ενότητα API Interface / Διαχείριση πακέτων.

API Interface

Προτού προχωρήσουμε παρακάτω σχετικά με την πλήρη ανάλυση των υπηρεσιών της εφαρμογής, το συγκεκριμένο API ακολουθεί αυστηρά το MLS Apps API με την απαίτηση συνδεδεμένων χρηστών για όλες τις υπηρεσίες. Μαζί με όλες τις παραμέτρους που θα ακολουθήσουν θα πρέπει να περιλαμβάνονται και όλες οι παράμετροι ώστε να τηρούνται τα πρωτόκολλα, σε οποιαδήποτε μορφή κλήσης (request method).

Διαχείριση παρόχου

Πληροφορίες παρόχου

Ο κάθε πάροχος έχει ρυθμίσεις σχετικά με τα μηνύματα εμφάνισης των χρηστών ανάλογα με την κατάστασή τους.

[GET Request]: https://mlsapps.gr/subs/api/safe/v3/provider/info.php

Parameters:
There are no parameters for this request. The provider is selected automatically from the user id.

Response Template:
"body":{
	"response":{
		"type":"json",
		"context":{
			"id":"{provider_id}",
			"name":"{provider_name}",
			"warning_message":"{Provider's warning message}",
			"lock_message":"{Provider's lock message}",
			"final_lock_message":"{Provider's final lock message}"
		}
	}
}

Αλλαγή ρυθμίσεων παρόχου

[POST/PUT Request]: https://mlsapps.gr/subs/api/safe/v3/provider/update.php

Parameters:
[warning_message] = The provider's warning message
[lock_message] = The provider's lock message
[final_lock_message] = The provider's final lock message

Successful response:
"body":{
	"response":{
		"type":"json",
		"context":{
			"status":1,
			"description":"OK"
		}
	}
}

Error response:
"body":{
	"response":{
		"type":"json",
		"context":{
			"status":0,
			"error":"An error occured. Error in updating provider information."
		}
	}
}

Διαχείριση πακέτων / batches

Προβολή όλων των πακέτων του παρόχου

[GET Request]: https://mlsapps.gr/subs/api/safe/v3/batch/list.php

Parameters:
There are no parameters for this request. The provider is selected automatically from the user id.

Response Template:
"body":{
	"response":{
		"type":"json",
		"context":{
			0:{
				"id":"{batch_0_id}",
				"name":"{batch_0_name}",
				"provider_id":"{provider_id}",
				"auto_lock":"0",	1 for enabled, 0 for disabled [Default]
				"lock_days":"0",	Number of days for auto lock after warning
				"time_created":"1430736831",  Unix timestamp
			},
			1:{
				"id":"{batch_1_id}",
				"name":"{batch_1_name}",
				"provider_id":"{provider_id}",
				"auto_lock":"0",	1 for enabled, 0 for disabled [Default]
				"lock_days":"0",	Number of days for auto lock after warning
				"time_created":"1430736733",  Unix timestamp
			},
			...
		}
	}
}

Πληροφορίες ενός πακέτου

Οι πληροφορίες των πακέτων μπορούν να αποθηκεύονται σε cache της εφαρμογής και να αποφεύγεται η συνεχής χρήση αυτών των υπηρεσιών. Ωστόσο η ανανέωση της cache θα πρέπει να γίνεται μετά από ενημέρωση κάποιου πακέτου.

[GET Request]: https://mlsapps.gr/subs/api/safe/v3/batch/info.php

Parameters:
[bid]: Batch id to get the information for

Response Template:
"body":{
	"response":{
		"type":"json",
		"context":{
			"id":"{batch_0_id}",
			"name":"{batch_0_name}",
			"provider_id":"{provider_id}",
			"auto_lock":"0",	1 for enabled, 0 for disabled [Default]
			"lock_days":"0",	Number of days for auto lock after warning
			"time_created":"1430736831",  Unix timestamp
		}
	}
}

Δημιουργία πακέτου

[POST Request]: https://mlsapps.gr/subs/api/safe/v3/batch/create.php

Parameters:
[name]: The batch name to be created

Successful creation:
"body":{
	"response":{
		"type":"json",
		"context":{
			"status":"1",
			"description":"OK"
		}
	}
}

Error in creation:
"body":{
	"response":{
		"type":"json",
		"context":{
			"status":"0",
			"error":"An error occured. The batch name is not valid or there is a batch with the same name."
		}
	}
}

Ενημέρωση πληροφοριών πακέτου

[POST/PUT Request]: https://mlsapps.gr/subs/api/safe/v3/batch/update.php

Parameters:
[bid]: The batch id to update
[name]: The new batch name.
(optional) [auto_lock]: Activate or deactivate the auto lock, 1 for activate, 0 for deactivate
(optional) [lock_days]: Number of days to lock after the warning

Successful update:
"body":{
	"response":{
		"type":"json",
		"context":{
			"status":"1",
			"description":"OK"
		}
	}
}

Error in update:
"body":{
	"response":{
		"type":"json",
		"context":{
			"status":"0",
			"error":"An error occured. The batch name is not valid or there is a batch with the same name."
		}
	}
}

Διαγραφή πακέτου

[POST Request]: https://mlsapps.gr/subs/api/safe/v3/batch/remove.php

Parameters:
[bid]: The batch id to remove

Successful removal:
"body":{
	"response":{
		"type":"json",
		"context":{
			"status":"1",
			"description":"OK"
		}
	}
}

Error in remove:
"body":{
	"response":{
		"type":"json",
		"context":{
			"status":"0",
			"error":"An error occured while removing batch. Please try again later."
		}
	}
}

Διαχείριση συσκευών

Δημιουργία συσκευής

[POST Request]: https://mlsapps.gr/subs/api/safe/v3/device/create.php

Parameters:
[imei]: The device unique imei
[bid]: The provider's batch id for the device.

Successful creation:
"body":{
	"response":{
		"type":"json",
		"context":{
			"status":"1",
			"description":"OK"
		}
	}
}

Error in create:
"body":{
	"response":{
		"type":"json",
		"context":{
			"status":"0",
			"error":"An error occured. The device IMEI is not valid or there is a device with the same IMEI."
		}
	}
}

Πληροφορίες συσκευής

[GET Request]: https://mlsapps.gr/subs/api/safe/v3/device/info.php

Parameters (any of them or all of them):
[id]: The device id
[imei]: The device unique imei

Device information:
"body":{
	"response":{
		"type":"json",
		"context":{
			"id":"{device_id}",
			"imei":"{device_imei}".
			"sdid":"{client_unique_id}",	Ignore this value
			"status_id":"1",
			"last_action_id":null,
			"batch_id":"{batch_id}",
			"password_md5":null,
			"last_contact":"1430913169",
			"client_version":null,
			"time_created":"1430913169",
			"provider":"{provider_name}",
			"warning_message":"{provider_warning_message}",
			"lock_message":"{provider_lock_message}",
			"final_lock_message":"{provider_final_lock_message}",
			"batch":"{batch_name}",
			"provider_id":"{batch_provider_id}",
			"status":"{device_status_description}",
			"lastAction":"{device_last_action_title}"
		}
	}
}

Διαγραφή συσκευής

[POST Request]: https://mlsapps.gr/subs/api/safe/v3/device/remove.php

Parameters (any of them or all of them):
[id]: The device id
[imei]: The device unique imei

Successful removal:
"body":{
	"response":{
		"type":"json",
		"context":{
			"status":"1",
			"description":"OK"
		}
	}
}

Error in remove:
"body":{
	"response":{
		"type":"json",
		"context":{
			"status":"0",
			"error":"An error occured while removing device. Please try again later."
		}
	}
}

Αναζήτηση συσκευων

Η αναζήτηση συσκευών γίνεται ως προς το IMEI.

[GET Request]: https://mlsapps.gr/subs/api/safe/v3/device/search.php

Parameters (any of them or all of them):
[q]: The content to search
(optional) [count]: Maximum number of results
(optional) [page]: The page number of results
(optional) [status]: The device status id
(optional) [action]: The device last action id

Search results:
"body":{
	"response":{
		"type":"json",
		"context":{
			0:{
				"id":"{device_id}",
				"imei":"{device_imei}".
				"sdid":"{client_unique_id}",	Ignore this value
				"status_id":"1",
				"last_action_id":null,
				"batch_id":"{batch_id}",
				"password_md5":null,
				"last_contact":"1430913169",
				"client_version":null,
				"time_created":"1430913169",
				"status":"{device_status_description}",
				"provider":"{provider_name}"
			},
			...
		}
	}
}

Ενημέρωση πληροφοριών συσκευής

Η αλλαγή του IMEI υπάρχει για την περίπτωση που χρειαστεί μια συσκευή να αντικατασταθεί με καινούριο hardware. Το ενναλακτικό αυτής της ενέργειας είναι η διαγραφή και η δημιουργία νέας συσκευής αλλά θα διαγραφεί και το συνοδευόμενο ιστορικό ενεργειών.

[POST Request]: https://mlsapps.gr/subs/api/safe/v3/device/update.php

Parameters:
[did]: The device id
(optional) [bid]: Change the device's batch id
(optional) [imei]: Change the device's imei

Successful update:
"body":{
	"response":{
		"type":"json",
		"context":{
			"status":"1",
			"description":"OK"
		}
	}
}

Error in update:
"body":{
	"response":{
		"type":"json",
		"context":{
			"status":"0",
			"error":"{Custom error description}"
		}
	}
}

Διαχείριση ενεργειών

Λίστα διαθέσιμων ενεργειών

[GET Request]: https://mlsapps.gr/subs/api/safe/v3/actions/list.php

Parameters:
There are no parameters for this request.

Response template:
"body":{
	"response":{
		"type":"json",
		"context":{
			0:{
				"id":"{action_0_id}",
				"name":"{action_0_name}",
				"status":"{The corresponding status id}"
			},
			1:{
				"id":"{action_1_id}",
				"name":"{action_1_name}",
				"status":"{The corresponding status id}"
			},
			...
		}
	}
}

Προσθήκη ενέργειας σε συσκευή

[POST Request]: https://mlsapps.gr/subs/api/safe/v3/device/actions/create.php

Parameters:
[did]: The device id
[aid]: The action id

Successful creation:
"body":{
	"response":{
		"type":"json",
		"context":{
			"status":"1",
			"description":"OK"
		}
	}
}

Error in create:
"body":{
	"response":{
		"type":"json",
		"context":{
			"status":"0",
			"error":"An error occured while creating the device action."
		}
	}
}

Ιστορικό ενεργειών συσκευής

[GET Request]: https://mlsapps.gr/subs/api/safe/v3/device/actions/history.php

Parameters:
[did]: The device id

Response template:
"body":{
	"response":{
		"type":"json",
		"context":{
			0:{
				"id":"{history_0_id}",
				"device_id":"{device_id}",
				"action_id":"{action_id}",
				"time_created":"1430741780",
				"time_delivered":null,
				"extra_info":null,
				"action":"{Action title}",
				"status_id":"{The status id of the device when this action is delivered}"
			},
			1:{
				"id":"{history_1_id}",
				"device_id":"{device_id}",
				"action_id":"{action_id}",
				"time_created":"1430741680",
				"time_delivered":"1430741750",
				"extra_info":null,
				"action":"{Action title}",
				"status_id":"{The status id of the device when this action is delivered}"
			},
			...
		}
	}
}
MLS Apps™ © 2018Κέντρο ΒοήθειαςΕλληνικά