openapi: 3.0.3
info:
  title: SMS API
  description: |
    The API provides the customer with the ability to send SMS to the recepient address(es).
    Customer can use this API to send SMS in following scenarios:
    1. Application server needs to send text message to a recepient number which is being used on a mobile phone device. There are 3 different categories of text SMS i.e. Service, Promotion & Transaction.
    2. Application server needs to send binary message to a recepient number which is being used on (IoT) device.
    
    Pre-requisite for using this API is that SMS Sender application / enterprise (or customer) needs to onboard themselves with the access provider before using this API. 
    This API has single operation to send SMS. 

    In order to the receive delivery receipt, separate API to be subscribed by the API consumer for receiving the delivery receipt in a standardized callback API. 

    # Authorization and authentication
    CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document [CAMARA-API-access-and-user-consent.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md). Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.

    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.    

  version: 0.1.0
  termsOfService: http://example.com/terms/
  contact:
    name: API Support
    url: http://www.example.com/support
    email: support@example.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
externalDocs:
  description: Product documentation at Camara
  url: https://github.com/camaraproject/ShortMessageService
servers:
  - url: '{apiRoot}/{basePath}'
    variables:
      apiRoot:
        default: https://api.ooredoo.ps
        description: API root
      basePath:
        default: sms/v0
        description: Base path for the Short Message Service
security:
  - Oauth: []
  
tags:
  - name: Short Message Service
    description: API operation to send SMS
paths:
  /short-message:
    post:
      
      tags:
        - Send SMS
      summary: Send SMS
      description: |
        The customer application server makes a request to the SMS API to send SMS message to the destination address.
      operationId: send-sms
      parameters:
        - in: header    
          name: transactionId
          description: transactionId
          required: true
          schema:
           type: string
           
        - in: header    
          name: applicationCode
          description: applicationCode
          required: true
          schema:
           type: string
        - in: header    
          name: applicationUserName
          description: applicationUserName
          required: true
          schema:
           type: string
        - in: header    
          name: username
          description: username
          required: true
          schema:
           type: string   
        - in: header    
          name: password
          description: password
          required: true
          schema:
           type: string
      requestBody:
        description: |
          Submit a request for sending SMS to the destination address
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageRequest'
            example:
                to: ["+972568560055","+972568560713"]
                from: '+919876543210'
                category: PROMOTION
                message: TEST MESSAGE
                senderName: XYZ
                clientCorrelator: XXXXX
                receiptRequest:
                  notifyURL: ABCD
                  callbackData: REQUEST123
        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'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
components:
  securitySchemes:
    Oauth:
      type: oauth2
      description: oauth2 security schema
      flows:
        clientCredentials:
          tokenUrl: "https://api.ooredoo.ps/tmf-api/oauth/token"
          scopes:
            send sms: Permission to send SMS 
  
  schemas:
    MessageRequest:
      type: object
      required:
        - to
        - from
        - message
        - receiptRequest
      properties:
        to:
          type: array
          description: "The recipients MSISDN"
          items:
            type: string
        from:
          type: string
          description: "The senders MSISDN"
        category:
          type: string
          enum: ["PROMOTION","SERVICE","TRANSACTION"]
        message:
          type: string
          description: "SMS message"
        clientCorrelator:
          type: string
          description: "clientCorrelator"
        senderName:
          type: string
          description: "senderName"
        receiptRequest:
            $ref: "#/components/schemas/receiptRequest"
            description: The value of the ReceiptRequest
    MessageResponse:
      type: object
      required:
        - msgId
        - timestamp
      properties:
        msgId:
          type: string
          description: "The SMS messages sent to the recipients are identified by smsnumber are identified."
        Infolist:
            $ref: "#/components/schemas/Infolist"
            description: The value of the Infolist
        to:
          type: array
          description: "The recipients MSISDN"
          items:
            type: string
        from:
          type: string
          description: "The senders MSISDN"
        receiptRequest:
            $ref: "#/components/schemas/receiptRequest"
            description: The value of the ReceiptRequest
        message:
          type: string
          description: "SMS message"
        clientCorrelator:
          type: string
          description: "clientCorrelator"
        senderName:
          type: string
          description: "senderName"

    ErrorInfo:
      type: object
      required:
        - status
        - code
        - detail
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: Code given to this error
        detail:
          type: string
          description: Detailed error description
          
    Any: {}    
    Characteristic:
      type: object
      description: Describes a given characteristic of an object or entity through a name/value pair.
      required:
        - name
        - value
      properties:
        id:
          type: string
          description: Unique identifier of the characteristic
        name:
          type: string
          description: Name of the characteristic
        valueType:
          type: string
          description: Data type of the value of the characteristic
      
        value:
            $ref: "#/components/schemas/Any"
            description: The value of the characteristic
            
    Infolist:
      type: object
      description: Info
      properties:
        resourceURL:
          type: string
          description: resourceURL
        Info:
          type: array
          items:
          $ref: '#/components/schemas/Info'
          description: deliveryInfo
          
    Info:
      type: object
      description: Infor
      properties:
        address:
          type: string
          description: address
        deliveryStatus:
          type: string
          description: deliveryStatus
        sequenceNumber:
          type: string
          description: sequenceNumber
        smppErrorCode :
          type: string
          description: smppErrorCode   
          
    
    receiptRequest:
      type: object
      description: ReceiptRequest
      properties:
        notifyURL:
          type: string
          description: notifyURL       
        callbackData:
          type: string
          description: callbackData  
          
  responses:
    Generic200:
      description: OK
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageResponse'
          example:
            msgId: 56647d96-b3e6-48d2-b93f-ab0d56bdd965
            to: ["+9725685xxxx","+97256856xxxx"]
            from: '+91987654xxxx'
            category: PROMOTION
            message: TEST MESSAGE
            senderName: XYZ
            clientCorrelator: XXXXX
            receiptRequest: [
              "notifyURL: ABCD",
              "callbackData: REQUEST123"
              ]
            Infolist: 
              resourceURL: http://XXXXXXX
              Info: [
                "address: tel:XXXXXX",
                "deliveryStatus: DeliveredToNetwork",
                "sequenceNumber: xxxxxxxx",
                "smppErrorCode: xxxxxxxx"
                ]
    
    Generic400:
      description: Problem with the client request
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 400
            code: INVALID_ARGUMENT
            detail: Client specified an invalid argument, request body or query param
    Generic401:
      description: Authentication problem with the client request
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 401
            code: UNAUTHENTICATED
            detail: Request not authenticated due to missing, invalid, or expired credentials
    Generic403:
      description: Client does not have sufficient permission
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            PermissionDenied:
              value:
                status: 403
                code: PERMISSION_DENIED
                detail: Client does not have sufficient permissions to perform this action
            InvalidTokenContext:
              value:
                status: 403
                code: INVALID_TOKEN_CONTEXT
                detail: Phone number cannot be deducted from access token context
    Generic404:
      description: Resource Not Found
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 404
            code: NOT_FOUND
            detail: A specified resource is not found
    Generic500:
      description: Server error
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 500
            code: INTERNAL
            detail: Server error
    Generic503:
      description: Service unavailable. Typically the server is down.
      headers:
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 503
            code: UNAVAILABLE
            detail: Service unavailable