openapi: 3.1.0
info:
  title: SMS Service
  version: '1.0'
servers:
  - url: https://api.solaris-sandbox.de
    description: Sandbox
  - url: https://api.solarisbank.de
    description: Production
paths:
  /v1/sms/messages:
    post:
      tags:
        - SMS messages
      summary: Send an SMS to a customer
      description: >-
        Sends an SMS to the customer's verified mobile number. You can use this
        endpoint to send informational texts to your customers, such as
        notifications about transactions (e.g., amounts debited or credited or
        request for purchases) or reminders (e.g., minimum amount due for credit
        cards, loans, etc.) or other informational messages (e.g., account
        statement generated, end of month account balance, etc.).<br>
        **Important:** You cannot use this endpoint for use cases that require
        Strong Customer Authentication (SCA) (i.e., confirmation via OTP). In
        such cases, please use the dedicated [SMS challenges
        endpoints](https://docs.solarisgroup.com/api-reference/onboarding/device-management/#tag/SMS-challenges).
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                person_id:
                  type: string
                  description: >-
                    The `person_id` of the customer to whom the SMS should be
                    sent.
                  example: dc1a6812a14f6cc338cd084208535bcdcper
                text:
                  type: string
                  description: The text of the SMS to be sent. A maximum of 160 characters.
                  example: >-
                    Account Statement for the month of July has been generated.
                    Please login to your account to view.
                purpose:
                  type: string
                  description: The purpose of the SMS.
                  example: Account statements
                idempotency_key:
                  type: string
                  format: uuid
                  description: >-
                    A randomly generated UUID which the server uses to recognize
                    subsequent retries of the same request.
                  example: 504f6816-f7b5-4965-bc35-69acadc9f5c7
              required:
                - person_id
                - text
                - purpose
                - idempotency_key
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: A unique ID of the message that has been sent.
                    example: 4d9d9eab-0392-4ffb-a9c6-dac9f18e3411
                  message:
                    type: string
                    description: A short description about the request status.
                    example: SMS has been accepted for processing.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: No access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
      security:
        - oauth2:
            - solaris_sms_messages#send
components:
  schemas:
    Error400:
      type: object
      title: Error400
      properties:
        errors:
          items:
            type: object
            properties:
              status:
                type: integer
                example: 400
              source:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
              code:
                type: string
                example: Invalid person Id
              title:
                type: string
                example: Bad Request
              detail:
                type: string
                example: Unable to fetch the person Id
              id:
                type: string
                description: Correlation/Request ID
                example: a95f2aaf-4e0c-4d49-8021-8a16a884ed86
          type: array
    Error403:
      type: object
      title: Error403
      properties:
        errors:
          items:
            type: object
            properties:
              status:
                type: integer
                example: 403
              source:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
              code:
                type: string
                example: unauthorized_action
              title:
                type: string
                example: Unauthorized Action
              detail:
                type: string
                example: Unauthorized action is not allowed.
              id:
                type: string
                description: Correlation/Request ID
                example: a95f2aaf-4e0c-4d49-8021-8a16a884ed86
          type: array
    Error409:
      type: object
      title: Error409
      properties:
        errors:
          items:
            type: object
            properties:
              status:
                type: integer
                example: 409
              source:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
              code:
                type: string
                example: validation_error
              title:
                type: string
                example: mobile number not verified
              detail:
                type: string
                example: The person's mobile number is unverified
              id:
                type: string
                description: Correlation/Request ID
                example: a95f2aaf-4e0c-4d49-8021-8a16a884ed86
          type: array
    Error429:
      type: object
      title: Error429
      properties:
        errors:
          items:
            type: object
            properties:
              status:
                type: integer
                example: 429
              source:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
              code:
                type: string
                example: sms_request_rate_limit_exceeded
              title:
                type: string
                example: Sms Request Rate Limit Exceeded
              detail:
                type: string
                example: 'SMS request rate limit exceeded for the number: +491520555555'
              id:
                type: string
                description: Correlation/Request ID
                example: ed5de352-85ea-4ad2-ac5d-3c75e48ef183
          type: array
    Error500:
      type: object
      properties:
        errors:
          items:
            type: object
            properties:
              status:
                type: integer
                example: 500
              source:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
              code:
                type: string
                example: generic_error
              title:
                type: string
                example: Generic Error
              detail:
                type: string
                example: There was an error.
              id:
                type: string
                description: Correlation/Request ID
                example: e8915041-9d8c-4d96-9dd1-04e8522ecdbf
          type: array
