CAMARA Short Message Service API

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-alpha.1
  termsOfService: http://example.com/terms/
  contact:
    name: API Support
    url: http://www.example.com/support
    email: [email protected]
  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: http://localhost:9091
        description: API root
      basePath:
        default: sms/v0alpha1
        description: Base path for the Short Message Service
tags:
  - name: Short Message Service
    description: API operation to send SMS
paths:
  /short-message:
    post:
      security:
        - openId:
          - send-sms:short-message
      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:
        - $ref: '#/components/parameters/x-correlator'      
      requestBody:
        description: |
          Submit a request for sending SMS to the destination address
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageRequest'
            examples:
              MessageRequest:
                value:
                  to: ['+910123456789']
                  from: '+919876543210'
                  category: PROMOTION
                  message: xxxxxxxxxx
        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:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
  parameters:
    x-correlator:
      name: x-correlator
      in: header
      description: Correlation id for the different services
      schema:
        type: string
  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        type: string
  schemas:
    MessageRequest:
      type: object
      required:
        - to
        - from
        - message
      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"
    MessageResponse:
      type: object
      required:
        - msgId
        - timestamp
      properties:
        msgId:
          type: string
          description: "The SMS messages sent to the recipients are identified by smsnumber are identified."
        timestamp:
          type: string
          format: date-time
          description: Timestamp when SMS was delivered. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)
    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
  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
            timestamp: "2024-03-19T12:33:27.070Z"
    
    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