Apply suggestions from code review

422_NOT_SUPPORTED -> when the service is not supported for the provided phone number (e.g. a B2B phone number)
UNIDENTIFIABLE_PHONE_NUMBER -> when the phone number is not provided in the request body a cannot be deducted from the access token. The UNIDENTIFIABLE_DEVICE should be used only when the API uses the object device

Co-authored-by: Fernando Prado Cabrillo <[email protected]>

code/API_definitions/kyc-match.yaml

@@ -44,19 +44,20 @@ info:
 
     It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.
 
-    ## Identifying the phone number from the access token
-    This specification defines the "phoneNumber" field as optional in API requests because using a 3-legged access token the phone number can be uniquely identified by the token.
+    # Identifying a phone number from the access token
+    This specification defines the `phoneNumber` field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token, and the phone number can be uniquely identified by the token. This approach simplifies API usage for API consumers by relying on the information associated with the access token used to invoke the API.
     ## Handling of phone number information:
-    ### Optional phone number object for 3-legged tokens:
-    When using a 3-legged access token, the phone number associated with the access token must be considered as the phone number for the API request.
-    This means that the "phoneNumber" paramenter is not required in the request, and if it is included it must identify the same phone number.
+    ### Optional `phoneNumber` field for 3-legged tokens:
+    - When using a 3-legged access token, the phone number associated with the access token must be considered as the phone number for the API request. This means that the `phoneNumber` field is not required in the request, and if included it must identify the same phone number, therefore **it is recommended NOT to include it in these scenarios** to simplify the API usage and avoid additional validations.
     ### Validation mechanism:
     - The server will extract the phone number identification from the access token, if available.
-    - If the API request additionally includes a "phoneNumber" parameter when using a 3-legged access token, the API will validate that the phone number
-    identifier provided matches the one associated with the access token.
-    - If there is a mismatch, the API will respond with a 403 `INVALID_TOKEN_CONTEXT` error, indicating that the device information in the request does not match the token.
-    ### Error handling for unidentifiable devices:
-    - If the "phoneNumber" parameter is not included in the request and the phone number information cannot be derived from the 3-legged access token, the server will return a 422 `UNIDENTIFIABLE_DEVICE` error.
+    - If the API request additionally includes a `phoneNumber` field when using a 3-legged access token, the API will validate that the phone number provided matches the one associated with the access token.
+    - If there is a mismatch, the API will respond with a 403 - INVALID_TOKEN_CONTEXT error, indicating that the phone number information in the request does not match the token.
+    ### Error handling for unidentifiable phone number:
+    - If the `phoneNumber` field is not included in the request and the phone number information cannot be derived from the 3-legged access token, the server will return a 422 `UNIDENTIFIABLE_PHONE_NUMBER` error.
+    ### Restrictions for tokens without an associated authenticated phone number:
+    - For scenarios which do not have a phone number associated to the token during the authentication flow, e.g. 2-legged access tokens, the `phoneNumber` field MUST be provided in the API request. This ensures that the phone number is explicit and valid for each API call made with these tokens.
+
 
   termsOfService: http://swagger.io/terms/
   contact:
@@ -554,12 +555,19 @@ components:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
           examples:
-            NoPhoneNumber:
-              description: Phone number not available neither from "phoneNumber" or from the access token.
+            GENERIC_422_NOT_SUPPORTED:
+              description: Not Supported
+              value:
+                status: 422
+                code: NOT_SUPPORTED
+                message: Service not supported for this phoneNumber
+            UNIDENTIFIABLE_PHONE_NUMBER:
+              description: The phone number is not included in the request and the phone number information cannot be derived from the 3-legged access token
               value:
                 status: 422
-                code: UNIDENTIFIABLE_DEVICE
-                message: Phone number not defined                
+                code: UNIDENTIFIABLE_PHONE_NUMBER
+                message: The phone number cannot be identified           
+
 
     Generic500:
       description: Server error.  Problem with MNO's server side.  Some processing error within MNO's servers.