diff --git a/code/API_definitions/customer-insights.yaml b/code/API_definitions/customer-insights.yaml index ca24204..aed056c 100644 --- a/code/API_definitions/customer-insights.yaml +++ b/code/API_definitions/customer-insights.yaml @@ -67,6 +67,18 @@ info: - If the subject can be identified from the access token and the optional `phoneNumber` field is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same phone number is identified by these two methods, as the server is unable to make this comparison. + # Additional Information on Error scenarios + + This section provides valuable information about the scope of some exceptions in order to provide support for the API implementation. + + `422 - SERVICE_NOT_APPLICABLE` + + This error code is used when the service cannot be provided. Applicable scenarios include, but are not limited to, the following: + - The API is invoked for a subscription, identified via access token or phoneNumber, that is not supported or not commercially allowed by the API Provider. + - The API is invoked for a valid subscription, identified via access token or phoneNumber, but the service cannot be provided for that specific subscription. For instance, this can be the case when the subscription has not enough historical data to provide a reliable Scoring result. + - The API is invoked without `idDocument` and the field is required by the API Provider. + - The API is invoked with a combination of `phoneNumber` and `idDocument`, considering `idDocument` is required by the API Provider, that does not point to the same subscription (i.e. the `phoneNumber` and `idDocument` provided are not related). + # Additional CAMARA error responses The list of error codes in this API specification is not exhaustive. Therefore the API specification may not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`. @@ -409,9 +421,7 @@ components: - An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token ("code": "MISSING_IDENTIFIER","message": "The phone number cannot be identified.") - An explicit identifier is provided when a device or phone number has already been identified from the access token ("code": "UNNECESSARY_IDENTIFIER","message": "The phone number is already identified by the access token.") - Provided `scoringType` value is not supported. (`"code": "CUSTOMER_INSIGHTS.SCALE_TYPE_NOT_SUPPORTED","message": "Indicated parameter scoringType is not supported."`) - - Provided `idDocument` is not consistent with the phone number. (`"code": "CUSTOMER_INSIGHTS.INVALID_IDENTIFIERS","message": "The request contains invalid data."`) - Provided `idDocument` field is not supported. (`"code": "CUSTOMER_INSIGHTS.ID_DOCUMENT_NOT_SUPPORTED","message": "Indicated parameter idDocument is not supported"`) - - Required `idDocument` field and it is not provided. (`"code": "CUSTOMER_INSIGHTS.ID_DOCUMENT_REQUIRED","message": "The idDocument is required to perform the properties validation."`) headers: x-correlator: $ref: "#/components/headers/x-correlator" @@ -431,9 +441,7 @@ components: - MISSING_IDENTIFIER - UNNECESSARY_IDENTIFIER - CUSTOMER_INSIGHTS.SCALE_TYPE_NOT_SUPPORTED - - CUSTOMER_INSIGHTS.INVALID_IDENTIFIERS - CUSTOMER_INSIGHTS.ID_DOCUMENT_NOT_SUPPORTED - - CUSTOMER_INSIGHTS.ID_DOCUMENT_REQUIRED examples: GENERIC_422_SERVICE_NOT_APPLICABLE: description: Service not applicable for the provided identifier @@ -459,24 +467,12 @@ components: status: 422 code: CUSTOMER_INSIGHTS.SCALE_TYPE_NOT_SUPPORTED message: Indicated parameter `scoringType` is not supported. - GENERIC_422_INVALID_IDENTIFIERS: - description: The request contains invalid data identifying customer - value: - status: 422 - code: CUSTOMER_INSIGHTS.INVALID_IDENTIFIERS - message: The request contains invalid data. GENERIC_422_ID_DOCUMENT_NOT_SUPPORTED: description: Error when `idDocument` field is not supported value: status: 422 code: CUSTOMER_INSIGHTS.ID_DOCUMENT_NOT_SUPPORTED - message: Indicated parameter `idDocument` is not supported - GENERIC_422_ID_DOCUMENT_REQUIRED: - description: Error when `idDocument` field is not provided and it is required. - value: - status: 422 - code: CUSTOMER_INSIGHTS.ID_DOCUMENT_REQUIRED - message: The `idDocument` is required to perform the properties validation. + message: Indicated parameter `idDocument` is not supported. Generic429: description: Too Many Requests headers: diff --git a/code/Test_definitions/customer-insights-retrieveScoring.feature b/code/Test_definitions/customer-insights-retrieveScoring.feature index 46f8008..9d3a80e 100644 --- a/code/Test_definitions/customer-insights-retrieveScoring.feature +++ b/code/Test_definitions/customer-insights-retrieveScoring.feature @@ -106,7 +106,7 @@ Feature: CAMARA Customer Insights API, vwip - Operation retrieveScoring @retrieve_scoring_C02.01_phone_number_not_schema_compliant Scenario: Phone number value does not comply with the schema - Given the header "Authorization" is set to a valid access which does not identify a single phone number + Given the header "Authorization" is set to a valid access token which does not identify a single phone number And the request body property "$.phoneNumber" does not comply with the OAS schema at "/components/schemas/PhoneNumber" When the request "retrieveScoring" is sent Then the response status code is 400 @@ -164,8 +164,11 @@ Feature: CAMARA Customer Insights API, vwip - Operation retrieveScoring @retrieve_scoring_404.01_idDocument_not_found Scenario: idDocument not found + # To test this, a 3-legged access token is needed, just because if not it triggers test "@retrieve_scoring_C02.04_missing_phone_number" + # Scenario applicable for a Telco Operator that requires `idDocument` for scoring retrieval. + # In case `idDocument` is not a required field for the Telco Operator, applicable scenarios are "@retrieve_scoring_422.03_id_document_not_supported_three_legged" and "@retrieve_scoring_422.04_id_document_not_supported_two_legged". Given the header "Authorization" is set to a valid access token identifying a phone number - And the request body property "$.idDocument" is set to a valid value not existing in the environment + And the request body property "$.idDocument" is required and set to a valid value not existing in the environment When the request "retrieveScoring" is sent Then the response status code is 404 And the response property "$.status" is 404 @@ -203,7 +206,7 @@ Feature: CAMARA Customer Insights API, vwip - Operation retrieveScoring When the request "retrieveScoring" is sent Then the response status code is 422 And the response property "$.status" is 422 - And the response property "$.code" is "CUSTOMER_INSIGHTS.INVALID_IDENTIFIERS" + And the response property "$.code" is "SERVICE_NOT_APPLICABLE" And the response property "$.message" contains a user friendly text @retrieve_scoring_422.03_id_document_not_supported_three_legged @@ -271,7 +274,7 @@ Feature: CAMARA Customer Insights API, vwip - Operation retrieveScoring When the request "retrieveScoring" is sent Then the response status code is 422 And the response property "$.status" is 422 - And the response property "$.code" is "CUSTOMER_INSIGHTS.ID_DOCUMENT_REQUIRED" + And the response property "$.code" is "SERVICE_NOT_APPLICABLE" And the response property "$.message" contains a user friendly text @retrieve_scoring_422.08_id_document_required_two_legged @@ -283,7 +286,7 @@ Feature: CAMARA Customer Insights API, vwip - Operation retrieveScoring When the request "retrieveScoring" is sent Then the response status code is 422 And the response property "$.status" is 422 - And the response property "$.code" is "CUSTOMER_INSIGHTS.ID_DOCUMENT_REQUIRED" + And the response property "$.code" is "SERVICE_NOT_APPLICABLE" And the response property "$.message" contains a user friendly text @retrieve_scoring_422.09_id_document_required_three_legged_with_scoring_type @@ -296,7 +299,7 @@ Feature: CAMARA Customer Insights API, vwip - Operation retrieveScoring When the request "retrieveScoring" is sent Then the response status code is 422 And the response property "$.status" is 422 - And the response property "$.code" is "CUSTOMER_INSIGHTS.ID_DOCUMENT_REQUIRED" + And the response property "$.code" is "SERVICE_NOT_APPLICABLE" And the response property "$.message" contains a user friendly text Examples: @@ -314,7 +317,7 @@ Feature: CAMARA Customer Insights API, vwip - Operation retrieveScoring When the request "retrieveScoring" is sent Then the response status code is 422 And the response property "$.status" is 422 - And the response property "$.code" is "CUSTOMER_INSIGHTS.ID_DOCUMENT_REQUIRED" + And the response property "$.code" is "SERVICE_NOT_APPLICABLE" And the response property "$.message" contains a user friendly text Examples: