Add number recycling

diegotid · diegotid · commit 12d01fb3a0ce · 2026-01-08T11:59:29.000+01:00
diff --git a/.github/workflows/rdme-guides-openapi.yml b/.github/workflows/rdme-guides-openapi.yml
@@ -122,3 +122,8 @@ jobs:
         uses: readmeio/rdme@v10
         with:
           rdme: openapi --file=./v0/catalog/knowyourcustomer/kyc_tenure_openapi.yaml --key=${{ secrets.README_API_KEY }} --id=6874e6f254f6aa3161e0c45b
+
+      - name: Run `openapi` command 🚀
+        uses: readmeio/rdme@v10
+        with:
+          rdme: openapi --file=./v0/catalog/numberrecycling/numberrecycling_openapi.yaml --key=${{ secrets.README_API_KEY }} --slug=v0catalognumberrecyclingnumberrecycling_openapi.yaml --branch=0
diff --git a/v0/catalog/numberrecycling/numberrecycling_openapi.yaml b/v0/catalog/numberrecycling/numberrecycling_openapi.yaml
@@ -0,0 +1,353 @@
+openapi: 3.0.3
+info:
+  title: Number Recycling
+  description: |
+    The API can be used to check whether the subscriber of the phone number has changed.
+    A common scenario is when Application service provider (ASP) wants to check whether there has been a change in the user associated with the phone number after the specified date. This allows the ASP to ensure that a phone number is correctly linked to an user and prevent the mis-delivery of SMS messages.
+
+    For example, below is a potential scenarios:
+    * Scenario 1
+      * Pre-conditions
+        * User A signed a contract with MNO A for the phone number '+123456789' on October 9, 2023, and is still using it.
+        * User A also signed contracts with ASP A on December 22, 2023 for its services.
+        * ASP A holds the contract date (2023-12-22) and the phone number (+123456789) for User A.
+        * Currently, on November 2, 2024, ASP A wishes to send a SMS message to User A.
+      * Potential operations
+        * ASP A sends a request with specified date (2023-12-22) and phone number (+123456789) to the Number Recycling API.
+        * The API response sets to 'false', indicating that there has not been a change in the user associated with the phone number.
+      * Post-conditions
+        * ASP A decides to send the SMS message to User A.
+      * By following these steps, ASP A ensures that a phone number is linked to User A.
+
+    <img width="4000" alt="Number_Recycling_scenario_1" src="https://raw.githubusercontent.com/camaraproject/NumberRecycling/r1.1/documentation/API_documentation/assets/Number_Recycling_scenario_1.png">
+
+    Note:
+    * When API receives a request with specified date on which a user signed a contract with MNO, the API respond sets to 'false'(e.g., 2023-10-09 in the Scenario 1 of the figure above).
+
+      * Scenario 2
+        * Pre-conditions
+          * User A signed a contract with MNO A for the phone number '+123456789' on October 9, 2023, and canceled it on February 25, 2024. Subsequently, User B signed a contract with MNO A for the same phone number on September 21, 2024, and is still using it.
+          * User A also signed contracts with ASP A on December 22, 2023 for its services.
+          * ASP A holds the contract date (2023-12-22) and the phone number (+123456789) for User A.
+          * Currently, on November 2, 2024, ASP A wishes to send a SMS message to User A.
+        * Potential operations
+          * ASP A sends a request with specified date (2023-12-22) and phone number (+123456789) to the Number Recycling API.
+          * The API response sets to 'true', indicating that there has been a change in the user associated with the phone number.
+        * Post-conditions
+          * ASP A decides to stop sending the SMS message to User A and contacts User A by mail.
+        * By following these steps, ASP A ensures that a phone number is not linked to User A and prevents the mis-delivery of the SMS message.
+
+    <img width="4000" alt="Number_Recycling_scenario_2" src="https://raw.githubusercontent.com/camaraproject/NumberRecycling/r1.1/documentation/API_documentation/assets/Number_Recycling_scenario_2.png">
+
+    Note:
+    * When the API receives a request with specified date during which there is no contract with MNO for the phone number, the API respond sets to 'true'(e.g., the period between 2024-02-25 and 2024-09-20 in the Scenario 2 of the figure above).
+
+    # Authorization and authentication
+
+    The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile.
+
+    The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation.
+
+    In cases where personal 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 three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design.
+
+    # Identifying the phone number from the access token
+
+    This API requires the API consumer to identify a phone number as the subject of the API as follows:
+    - When the API is invoked using a two-legged access token, the subject will be identified from the optional `phoneNumber` field, which therefore MUST be provided.
+    - When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token.
+
+    This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process.
+
+    ## Error handling:
+
+    - If the subject cannot be identified from the access token and the optional `phoneNumber` field is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code.
+    - 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.
+
+  version: "0.1"
+  termsOfService: http://example.com/terms/
+  contact:
+    name: Telefónica Open Gateway DevRel
+    url: https://opengateway.telefonica.com/en/developer-hub
+    email: devrel@telefonica.com
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+
+servers:
+  - url: '{host}/number-recycling/v0'
+    variables:
+      host:
+        default: sandbox.opengateway.telefonica.com/apigateway
+        description: gateway URL
+
+paths:
+  /check:
+    post:
+      summary: Check number recycling v0.1
+      security:
+        - three_legged:
+            - number-recycling:check
+      tags:
+        - Check for phone number subscriber change.
+      description: Check whether the subscriber of the phone number has changed.
+      operationId: checkNumberRecycling
+      parameters:
+        - $ref: '#/components/parameters/x-correlator'
+      requestBody:
+        description: |
+          Check whether the subscriber of the phone number has changed.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateCheckNumRecycling'
+        required: true
+      responses:
+        '200':
+          $ref: '#/components/responses/Generic200'
+        '400':
+          $ref: '#/components/responses/Generic400'
+        '401':
+          $ref: '#/components/responses/Generic401'
+        '403':
+          $ref: '#/components/responses/Generic403'
+        '404':
+          $ref: '#/components/responses/Generic404'
+        '422':
+          $ref: '#/components/responses/Generic422'
+components:
+  securitySchemes:
+    three_legged:
+      type: oauth2
+      flows:
+        authorizationCode:
+          authorizationUrl: https://{host}/authorize
+          tokenUrl: https://{host}/token
+          scopes:
+            number-recycling:check: checkNumberRecycling operation
+  parameters:
+    x-correlator:
+      name: x-correlator
+      in: header
+      description: Correlation id for the different services
+      schema:
+        type: string
+        pattern: "^[a-zA-Z0-9-]{0,55}$"
+        example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"
+  headers:
+    x-correlator:
+      description: Correlation id for the different services
+      schema:
+        type: string
+        pattern: "^[a-zA-Z0-9-]{0,55}$"
+        example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"
+  schemas:
+    CreateCheckNumRecycling:
+      type: object
+      required:
+        - specifiedDate
+      properties:
+        phoneNumber:
+          $ref: '#/components/schemas/PhoneNumber'
+        specifiedDate:
+          type: string
+          format: date
+          description: Specified date to check whether there has been a change in the subscriber associated with the specific phone number, in RFC 3339 calendar date format (YYYY-MM-DD).
+          example: "2024-10-31"
+    PhoneNumber:
+      description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.
+      type: string
+      pattern: '^\+[1-9][0-9]{4,14}$'
+      example: "+123456789"
+    CheckNumRecyclingInfo:
+      type: object
+      required:
+        - phoneNumberRecycled
+      properties:
+        phoneNumberRecycled:
+          type: boolean
+          description: |
+            Set to true (Boolean, not string) when there has been a change in the subscriber associated with the specific phone number after “specifiedDate”.
+    ErrorInfo:
+      type: object
+      required:
+        - status
+        - code
+        - message
+      properties:
+        status:
+          type: integer
+          description: HTTP response status code
+        code:
+          type: string
+          description: Code given to this error
+        message:
+          type: string
+          description: A human readable description of what the event represent
+  responses:
+    Generic200:
+      description: OK
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/CheckNumRecyclingInfo'
+
+    Generic400:
+      description: Problem with the client request
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: "#/components/schemas/ErrorInfo"
+              - type: object
+                properties:
+                  status:
+                    enum:
+                      - 400
+                  code:
+                    enum:
+                      - INVALID_ARGUMENT
+                      - OUT_OF_RANGE
+          examples:
+            InvalidArgument:
+              description: Invalid Argument. Generic Syntax Exception
+              value:
+                status: 400
+                code: INVALID_ARGUMENT
+                message: Client specified an invalid argument, request body or query param.
+            OutOfRange:
+              description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested
+              value:
+                status: 400
+                code: OUT_OF_RANGE
+                message: Client specified an invalid range.
+
+    Generic401:
+      description: Authentication problem with the client request
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: "#/components/schemas/ErrorInfo"
+              - type: object
+                properties:
+                  status:
+                    enum:
+                      - 401
+                  code:
+                    enum:
+                      - UNAUTHENTICATED
+                      - AUTHENTICATION_REQUIRED
+          examples:
+            Unauthenticated:
+              description: Request cannot be authenticated
+              value:
+                status: 401
+                code: UNAUTHENTICATED
+                message: Request not authenticated due to missing, invalid, or expired credentials.
+            Authentication Required:
+              description: New authentication is needed, authentication is no longer valid
+              value:
+                status: 401
+                code: AUTHENTICATION_REQUIRED
+                message: New authentication is required.
+
+    Generic403:
+      description: Client does not have sufficient permission
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: "#/components/schemas/ErrorInfo"
+              - type: object
+                properties:
+                  status:
+                    enum:
+                      - 403
+                  code:
+                    enum:
+                      - PERMISSION_DENIED
+          examples:
+            Permission Denied:
+              description: Permission denied. OAuth2 token access not have the required scope or when the user fails operational security
+              value:
+                status: 403
+                code: PERMISSION_DENIED
+                message: Client does not have sufficient permissions to perform this action
+
+    Generic404:
+      description: Resource Not Found
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: "#/components/schemas/ErrorInfo"
+              - type: object
+                properties:
+                  status:
+                    enum:
+                      - 404
+                  code:
+                    enum:
+                      - IDENTIFIER_NOT_FOUND
+          examples:
+            Phone Number Used By Different Network Operator:
+              description: Provided phone number is used by a different network operator
+              value:
+                status: 404
+                code: IDENTIFIER_NOT_FOUND
+                message: Phone number not found.
+
+    Generic422:
+      description: Unprocessable Content
+      headers:
+        x-correlator:
+          $ref: '#/components/headers/x-correlator'
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: "#/components/schemas/ErrorInfo"
+              - type: object
+                properties:
+                  status:
+                    enum:
+                      - 422
+                  code:
+                    enum:
+                      - SERVICE_NOT_APPLICABLE
+                      - MISSING_IDENTIFIER
+                      - UNNECESSARY_IDENTIFIER
+          examples:
+            Device Not Applicable:
+              description: Service not applicable for the provided phone number
+              value:
+                status: 422
+                code: SERVICE_NOT_APPLICABLE
+                message: The service is not available for the provided phone number
+            Unnecessary Identifier:
+              description: An explicit identifier is provided when a phone number has already been identified from the access token
+              value:
+                status: 422
+                code: UNNECESSARY_IDENTIFIER
+                message: The phone number is already identified by the access token
+            Missing Identifier:
+              description: An identifier is not included in the request and the phone number identification cannot be derived from the 3-legged access token
+              value:
+                status: 422
+                code: MISSING_IDENTIFIER
+                message: The phone number cannot be identified
