Include readiness Checklist and User Stories proposal for SIM Swap

documentation/API_documentation/API-Readiness-Checklist_SIM-Swap-1.0.0.md

@@ -0,0 +1,27 @@
+# API Readiness Checklist
+
+Checklist for SIM Swap 1.0.0 in FALL24
+
+| Nr | API release assets  | alpha | release-candidate |  initial<br>public | stable<br> public | Status | Comments |
+|----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:|
+|  1 | API definition                               |   M   |         M         |    M    |    M   |      | link |
+|  2 | Design guidelines from Commonalities applied |   O   |         M         |    M    |    M   |      |      |
+|  3 | Guidelines from ICM applied                  |   O   |         M         |    M    |    M   |      |      |
+|  4 | API versioning convention applied            |   M   |         M         |    M    |    M   |      |      |
+|  5 | API documentation                            |   M   |         M         |    M    |    M   |      | link |
+|  6 | User stories                                 |   O   |         O         |    O    |    M   |      | link |
+|  7 | Basic API test cases & documentation         |   O   |         M         |    M    |    M   |      | link |
+|  8 | Enhanced API test cases & documentation      |   O   |         O         |    O    |    M   |      | link |
+|  9 | Test result statement                        |   O   |         O         |    O    |    M   |      | link |
+| 10 | API release numbering convention applied     |   M   |         M         |    M    |    M   |      |      |
+| 11 | Change log updated                           |   M   |         M         |    M    |    M   |      | link |
+| 12 | Previous public release was certified        |   O   |         O         |    O    |    M   |      |      |
+
+To fill the checklist:
+- in the line above the table, replace the api-name, api-version and the rx.y by their actual values for the current API version and release.
+- in the Status column, put "Y" (yes) if the release asset is available or fulfilled in the current release, a "N" (no) or a "tbd". Example use of "tbd" is in case an alpha or release-candidate API version does not yet provide all mandatory assets for the release.
+- in the Comments column, provide the link to the asset once available, and any other relevant comments.
+
+Note: the checklists of a public API version and of its preceding release-candidate API version can be the same.
+
+The documentation for the content of the checklist is here: [API Readiness Checklist](https://wiki.camaraproject.org/x/HQBFAQ)

documentation/API_documentation/SIM-Swap_check_User_Story.md

@@ -0,0 +1,11 @@
+# SIM Swap Check API User Story
+
+
+| **Item** | **Details** |
+| ---- | ------- |
+| ***Summary*** | As an enterprise application developer, I want to check if a SIM swap has occurred within a specified period for a user's mobile number so that I can enhance security measures against account takeover fraud.  |
+| ***Roles, Actors and Scope*** | **Roles:** Customer:User, Customer:BusinessManager, Customer:Administrator<br> **Actors:** Application service providers, hyperscalers, application developers, end users, Communication service Provider (CSP). <br> **Scope:**  <br> - Checks if a SIM Swap has occurred within a specified period for a given phone number. |
+| ***Pre-conditions*** |The preconditions are listed below:<br><ol><li>The Customer:BusinessManager and Customer:Administrator have been onboarded to the CSP's API platform.</li><li>The Customer:BusinessManager has successfully subscribed to the SIM Swap API product from the product catalog.</li><li>The Customer:Administrator has onboarded the Customer:User to the platform.</li><li>The Customer:User performs an authorization request to CSP</li><li>The Customer:User has the access token allowing the access of the API and SIM Swap information of the target phoneNumber, if applies|
+| ***Activities/Steps*** | **Starts when:** The customer application makes a POST request to the /check endpoint via the SIM Swap API, providing the phone number and the desired period to check for SIM swaps.<br>**Ends when:** The CSP's SIM Swap server responds indicating whether a SIM swap has been performed within the specified period. |
+| ***Post-conditions*** | The customer application could continue offering its service to the end user with the confirmation of the validity of the SIM based on the SIM Swap information.  |
+| ***Exceptions*** | Several exceptions might occur during the SIM Swap API operations<br>- Unauthorized: Not valid credentials (e.g., use of already expired access token).<br>- Invalid input: Not valid input data to invoke operation (e.g., improperly formatted phone number).|

documentation/API_documentation/SIM-Swap_retrieve_User_Story.md

@@ -0,0 +1,11 @@
+# SIM Swap Retrieve API User Story
+
+
+| **Item** | **Details** |
+| ---- | ------- |
+| ***Summary*** | As an enterprise application developer, I want to verify the last SIM Swap date for a user's mobile number so that I can enhance security measures against account takeover fraud.  |
+| ***Roles, Actors and Scope*** | **Roles:** Customer:User, Customer:BusinessManager, Customer:Administrator<br> **Actors:** Application service providers, hyperscalers, application developers, end users, Communication service Provider (CSP). <br> **Scope:**  <br> - Retrieves the timestamp of the last SIM Swap event for a given phone number. |
+| ***Pre-conditions*** |The preconditions are listed below:<br><ol><li>The Customer:BusinessManager and Customer:Administrator have been onboarded to the CSP's API platform.</li><li>The Customer:BusinessManager has successfully subscribed to the SIM Swap API product from the product catalog.</li><li>The Customer:Administrator has onboarded the Customer:User to the platform.</li><li>The Customer:User performs an authorization request to CSP</li><li>The Customer:User has the access token allowing the access of the API and SIM Swap information of the target phoneNumber, if applies"|
+| ***Activities/Steps*** | **Starts when:** The customer application makes a POST request to the /retrieve-date endpoint via the SIM Swap API, including the phone number provided by the user in the application.<br>**Ends when:** The CSP's SIM Swap server responds with the timestamp of the last SIM swap event, or the SIM activation date if no swap has occurred. |
+| ***Post-conditions*** | The customer application could continue offering its service to the end user with the confirmation of the validity of the SIM based on the SIM Swap information.  |
+| ***Exceptions*** | Several exceptions might occur during the SIM Swap API operations<br>- Unauthorized: Not valid credentials (e.g., use of already expired access token).<br>- Invalid input: Not valid input data to invoke operation (e.g., improperly formatted phone number).<br>- Not able to provide: Legal restrictions or data retention policies preventing the retrieval of the requested information.|