openapi: 3.0.1
info:
  title: Branded Calling AntiSpoofing API
  version: 2.0.0-beta1
  description: |
    The Branded Calling Anti Spoofing API provides an interface for call centres to submit details of planned outbound calls in advance ("pre-announcement") to the Branded Calling Platform.
    Its main purpose is to guard against enriching spoofed phone calls. Pre-announcement ensures only legitimate calls are enriched by the Branded Calling platform. If Anti-Spoofing is enabled for a calling number, then all outbound calls from that number must be pre-announced using this API. Otherwise, the Branded Calling platform will either block the call or not enrich it, depending on the preferred Anti-Spoofing action submitted during brand registration phase.
    # Use Cases
    * **Announce Call Details** - External entities such as 3rd party call centres or banks invoke Vodafone DMP exposed Anti Spoof API API in order to announce a call letting Vodafone know that they are going to make a call to their customer within a specific duration.

servers:
  - url: https://api-sandbox.vf-dmp.engineering.vodafone.com/antispoof/v2
    description: "Sandbox"
#  - url: https://api.vf-dmp.engineering.vodafone.com/antispoof/v2
#    description: "Production"

tags:
  - name: AntiSpoofing API
    description: |
       Helps to prevent spoofed calls from being enriched with a display name
  - name: Monitoring
    description: |
       Perform API healthchecks. Internal systems use only.

paths:
  /announcecall:
    post:
      tags:
        - AntiSpoofing API
      x-openapi-router-controller: app.controllers.admins_controller
      summary: Helps to pre-announce an outbound call details to the Branded Calling Platform
      description: This operation lets external consumers to pre-announce legitimate calls that should be enriched by the Branded Calling platform
      operationId: post_announce_call
      parameters:
        - $ref: '#/components/parameters/XVfCorrelationIdParam'
        # - $ref: '#/components/parameters/XVfPartnerId'

      requestBody:
        required: true
        description: Object to represent parameters of a registration request
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnnounceCallRequest"
            examples:
              WITH_VISUAL_SEPERATORS:
                value:
                  callingParticipant: "+44-123-123456789"
                  calledParticipant: "+44-123-123456790"
                  clientId: "BANK1"
                  timeToLive: 60
              WITHOUT_VISUAL_SEPERATORS:
                value:
                  callingParticipant: "+44123123456791"
                  calledParticipant: "+44123123456792"
                  clientId: "BANK2"
                  timeToLive: 30

      responses:
        "204":
          $ref: '#/components/responses/204NoContent'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '405':
          $ref: '#/components/responses/Generic405'
        '406':
          $ref: '#/components/responses/Generic406'
        '409':
          $ref: '#/components/responses/Generic409'
        '415':
          $ref: '#/components/responses/Generic415'
        '429':
          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
        '502':
          $ref: '#/components/responses/Generic502'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'

      security:
        - oAuthSample:
            - ANTI_SPOOFING_APIGEE_PRODUCT_V2
  /ping:
    get:
      tags:
      - Monitoring
      summary: ping operation
      description: This operation returns if the API is alive
      operationId: healthcheckPing
      x-openapi-router-controller: app.controllers.admins_controller
      security:
        - oAuthSample:
            - ANTI_SPOOFING_HEALTHCHECK_APIGEE_PRODUCT_V2
      parameters:
      - $ref: '#/components/parameters/XVfCorrelationIdParam'
      responses:
        "200":
          description: ping information returned in the result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PongInfo'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '405':
          $ref: '#/components/responses/Generic405'
        '406':
          $ref: '#/components/responses/Generic406'
        '415':
          $ref: '#/components/responses/Generic415'
        '429':
          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
        '502':
          $ref: '#/components/responses/Generic502'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'

  /status:
    get:
      tags:
      - Monitoring
      summary: Status operation
      description: This operation returns if the API is working E2E
      operationId: healthcheckStatus
      x-openapi-router-controller: app.controllers.admins_controller
      security:
        - oAuthSample:
            - ANTI_SPOOFING_HEALTHCHECK_APIGEE_PRODUCT_V2
      parameters:
       - $ref: '#/components/parameters/XVfCorrelationIdParam'
      responses:
        "200":
          description: ping information returned in the result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusInfo'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '405':
          $ref: '#/components/responses/Generic405'
        '406':
          $ref: '#/components/responses/Generic406'
        '415':
          $ref: '#/components/responses/Generic415'
        '429':
          $ref: '#/components/responses/Generic429'
        '500':
          $ref: '#/components/responses/Generic500'
        '502':
          $ref: '#/components/responses/Generic502'
        '503':
          $ref: '#/components/responses/Generic503'
        '504':
          $ref: '#/components/responses/Generic504'

components:
  securitySchemes:
    oAuthSample:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: '/oauth2/v1/token'
          scopes:
            ANTI_SPOOFING_APIGEE_PRODUCT_V2: API Consumer is allowed to consume the AntiSpoofing resource of the API
            ANTI_SPOOFING_HEALTHCHECK_APIGEE_PRODUCT_V2: API Consumer is allowed to consume the Healthcheck resource of the API

  responses:
    204NoContent:
      description: Successful creation of a pre-announcement
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
        Strict-Transport-Security:
          $ref: '#/components/headers/Strict-Transport-Security'
        Date:
          $ref: '#/components/headers/Date'
        X-Content-Type-Options:
          $ref: '#/components/headers/X-Content-Type-Options'
        # Content-Type:
        #   $ref: '#/components/headers/Content-Type'
        X-Correlator:
          $ref: '#/components/headers/X-Correlator'
        Server:
          $ref: '#/components/headers/Server'

 ############## Added Camara Error Structure ###########################################
   
    Generic400:
      description: |
        **Bad Request**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            invalid argument:
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: Client specified an invalid argument, request body or query param
    Generic401:
      description: |
        **Unauthorized**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            invalid creds:
              value:
                status: 401
                code: UNAUTHENTICATED
                message: Request not authenticated due to missing, invalid, or expired credentials
    Generic403:
      description: |
        **Forbidden**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            permission denied:
              value:
                status: 403
                code: PERMISSION_DENIED
                message: Client does not have sufficient permissions to perform this action
    Generic404:
      description: |
        **Not Found**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:

              NOT_FOUND:
                value: {
                          "status": 404,
                          "code" : "NOT_FOUND",
                          "message": "The specified resource is not found."
                        }
              UNKNOWN_PHONE_NUMBER:
                value: {
                          "status": 404,
                          "code" : "UNKNOWN_PHONE_NUMBER",
                          "message": "Can't be checked because the phone number is unknown."
                        }
    Generic405:
      description: |
        **Method Not Allowed**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            METHOD_NOT_ALLOWED:
              value:
                status: 405
                code: METHOD_NOT_ALLOWED
                message: The requested method is not allowed/supported on
                      the target resource"
    Generic406:
      description: |
        **Not Acceptable**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            Not Acceptable:
              value:
                status: 406
                code: Not Acceptable
                message: The server cannot produce a response matching
                          the content requested by the client through Accept-* headers."
                          
    Generic409:
      description: |
        **Conflict**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:

              CONFLICT:
                value: {
                          "status": 409,
                          "code" : "CONFLICT",
                          "message": "The specified resource duplicate entry found."
                        }
              ALREADY_EXISTS:
                value: {
                          "status": 404,
                          "code" : "ALREADY_EXISTS",
                          "message": "The specified resource that client tried to create already exists."
                        }
    Generic415:
      description: |
        **Unsupported Media Type**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            UNSUPPORTED_MEDIA_TYPE:
              value:
                status: 415
                code: UNSUPPORTED_MEDIA_TYPE
                message: The server refuses to accept the request because
                      the payload format is in an unsupported format
                      
    Generic429:
      description: |
        **Too Many Requests**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
              SpikeArrestViolation:
                value: {
                          "status": 429,
                          "code" : "TOO_MANY_REQUESTS",
                          "message": "Spike Arrest Violation."
                        }
              QuotaViolation:
                value: {
                          "status": 429,
                          "code" : "TOO_MANY_REQUESTS",
                          "message": "API/App/Country Quota limit reached."
                        }
                        
    Generic500:
      description: |
        **Internal Server Error**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            Internal_Server_Error:
              value:
                status: 500
                code: INTERNAL
                message: The server encountered an unexpected condition
                      that prevented it from fulfilling the request
    Generic502:
      description: |
        **Bad Gateway**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            Bad_Gateway:
              value:
                status: 502
                code: BAD_GATEWAY
                message: An upstream internal service cannot be reached

    Generic503:
      description: |
        **UNAVAILABLE**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            UNAVAILABLE:
              value:
                status: 503
                code: UNAVAILABLE
                message: Request timeout exceeded
    Generic504:
      description: |
        **Gateway Timeout**
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            TIMEOUT:
              value:
                status: 504
                code: TIMEOUT
                message: Request timeout exceeded. 
            
   
   
####################################################################################################################   
   
   
    
  schemas:
  
############################# Add Camara Schema ###############################################################

    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: Detailed error description
          
    clientId:
      type: string
      description: Unique customer identifier for a brand
      example: "VODA"
    timeToLive:
      type: integer
      minimum: 1
      maximum: 86400
      description: >-
        This parameter specifies for how long the call announcement is valid, in units of seconds.
        Calls processed after the call announcement expiry are treated as not announced.
        If not specified, the service platform applies a default value.
        The platform may choose to enforce an upper bound on this value. If the requested duration is too long, the request fails.
      example: 60
    callParticipant:
          type: string
          pattern: '^\+(\d[\-.\(\)]*){4,15}((\;)(\w)*(\=)(\w)*)*$'
          example: "+49-123-123456789"
    AnnounceCallRequest:
      type: object
      required:
        - "callingParticipant"
        - "calledParticipant"
      properties:
        callingParticipant:
          allOf:
            - description: >-
                Indication of the Calling Party (A-Number subject to branding).
                It must be a telephone number in international format, i.e. a `<global-number>` in the sense of RFC 3966, Section 3.
                Visual separators (like the hyphen in the examples) and trailing parameters (after a semicolon) are silently ignored.
          $ref: '#/components/schemas/callParticipant'
        calledParticipant:
          allOf:
            - description: >-
                Indication of the Called Party (B-Number).
                It must be a telephone number in international format, i.e. a `<global-number>` in the sense of RFC 3966, Section 3.
                Visual separators (like the hyphen in the examples) and trailing parameters (after a semicolon) are silently ignored.
          $ref: '#/components/schemas/callParticipant'
        clientId:
          $ref: '#/components/schemas/clientId'
        timeToLive:
          $ref: '#/components/schemas/timeToLive'
      description: "Request object for call announcement"
    errorResponse:
      description: Error response format for Antispoofing operation(s)
      type: object
      properties:
        type:
          type: string
          description: Link to API in developers portal giving mode information w.r.t. error
        title:
          type: string
          description: A short, human-readable summary of the problem type
        status:
          type: integer
          description: The HTTP status code
        detail:
          type: string
          description: This parameter appears when there was an error. Human readable explanation specific to this occurrence of the problem
    healthcheckError:
      type: object
      properties:
        code:
          type: integer
          description: Application relevant detail, defined in the API or a common
            list.
        message:
          type: string
          description: More details and corrective actions related to the error which
            can be shown to a client user.
        status:
          type: integer
          description: HTTP Error code
      description: Error response format for Healthcheck resources
    PongInfo:
      description: Pong response object in return to a ping request
      type: object
      required:
        - suffix
        - client
        - startTime
        - endTime
        - responseTime
        - message
      properties:
        suffix:
          type: string
          description: Operation URI Path
          enum:
          - "/ping"
          example: "/ping"
        client:
          type: string
          description: Origin IP that request the operation
          example: "35.191.14.51"
          format: ipv4
        startTime:
          type: string
          description: Start time of the request in date-time format
          example: "2024-02-08T14:42:20.675Z"
          format: date-time
        endTime:
          type: string
          description: End time of the operation
          example: "2024-02-08T14:42:20.687Z"
          format: date-time
        responseTime:
          type: integer
          description: Time in miliseconds between startTime and endTime
          example: 12
        message:
          type: string
          description: Response message for the PING, that allways will be PONG
          example: PONG
          enum:
          - "PONG"
    StatusInfo:
      description: Status response object
      type: object
      required:
        - status
      properties:
        status:
          type: string
          description: The status of the API, that returns if the API is working E2E
          example: OK
          enum:
          - OK
          - KO

  parameters:
    XVfCorrelationIdParam:
      name: X-Correlator
      in: header
      description:
        The Correlation ID that will be used to allow correlation between response and corresponding request
      required: false
      example: "9e765f76-8037-4e5f-ba5d-e0c87c09a320"
      schema:
        type: string
        format: uuid
    XVfPartnerId:
      name: partnerId
      in: header
      description:
        Unique reference associated to an onboarded partner
      required: true
      example: "VIH001"
      schema:
        type: string

  headers:
    Cache-Control:
      schema:
        type: string
        default: "no-store,no-cache"
      description: >
        used to specify browser caching policies in both client requests and server responses
    Strict-Transport-Security:
      schema:
        type: string
        default: "max-age=15724800;includeSubDomains"
      description: >
        web security policy mechanism which helps to protect websites against protocol downgrade attacks and cookie hijacking
    Date:
      schema:
        type: string
        format: date-time
      description: >
        Time the server constructed the response. example: e.g. YYY-MM-DDThh:mm:ssZ
    X-Content-Type-Options:
      schema:
        type: string
        default: "nosniff"
      description: >
        prevent the browser from interpreting files as a different MIME type to what is specified in the Content-Type HTTP header
    Content-Type:
      schema:
        type: string
        default: application/json
      description: >
            The Content-Type entity header is used to indicate the media type of the resource.
    X-Correlator:
      schema:
        type: string
        format: uuid
      description: >
            The Correlation ID that will be used to allow correlation between response and corresponding request
    Server:
      schema:
        type: string
        default: VF
      description: Identification of the responding server