openapi: 3.0.3
info:
  title: SAP Emarsys SMS Partner Service
  description: |
    An SAP Emarsys SMS Partner Service allows partners to host SMS message sends that are triggered
    by an SAP Emarsys SMS campaign launch. This OpenAPI specification describes the required Partner service endpoints.
  version: 0.0.1
  contact:
    name: SAP Emarsys SMS Team
    email: team-sms@emarsys.com
x-sap-shortText: Configure, test client setup and sends SMS messages.
servers:
  - url: https://api.sms-partner.io/sms/partner/v1
paths:
  /clients/{clientId}/configuration:
    summary: Manage a client configuration within a Partner service
    parameters:
      - $ref: './common.yaml#/components/parameters/clientIdPathParam'
    put:
      tags: [ Client Configuration ]
      operationId: createOrUpdateClientConfiguration
      summary: Create or update a single client's configuration
      requestBody:
        description: client's custom field values as a map.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrUpdateClientConfigurationRequest'
      responses:
        '200':
          description: Client configuration was successfully recorded within the Partner service.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrUpdateClientConfigurationResponse'
        '400':
            $ref: '#/components/responses/InvalidClientConfigurationFormatResponse'
        '401':
          $ref: './common.yaml#/components/responses/AuthenticationFailedResponse'
        '403':
          $ref: './common.yaml#/components/responses/AuthorizationFailedResponse'
        '5XX':
          $ref: './common.yaml#/components/responses/ServerErrorResponse'
    get:
      tags: [ Client Configuration ]
      operationId: getClientConfiguration
      summary: Get a client's configuration by their ID
      responses:
        '200':
          description: Client exists within the Partner service and their configuration
            is returned in the response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetClientConfigurationResponse'
        '403':
          description: Authentication failed.
        '404':
          description: Client does not have a configuration recorded within the Partner service.
        '5XX':
          description: Server error occurred
          content:
            application/json:
              schema:
                $ref: './common.yaml#/components/schemas/Error'
    delete:
      tags: [ Client Configuration ]
      operationId: deleteClientConfiguration
      summary: Delete a client's configuration by their ID
      responses:
        '204':
          description: Client exists within the Partner service and their configuration
            is returned in the response.
        '403':
          description: Authentication failed.
        '404':
          description: Client does not have a configuration recorded within the Partner service.
        '5XX':
          description: Server error occurred
          content:
            application/json:
              schema:
                $ref: './common.yaml#/components/schemas/Error'
  /testConnection:
    post:
      tags: [ Client Configuration Test ]
      operationId: testConnection
      summary: Test connection with the provided custom fields with the provider
      requestBody:
        description: Provider specific custom fields
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestConnectionRequest'
      responses:
        '200':
          description: The request is successfully processed
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/TestConnectionSuccessResponse'
                  - $ref: '#/components/schemas/TestConnectionFailureResponse'
                discriminator:
                  propertyName: state
                  mapping:
                    success: '#/components/schemas/TestConnectionSuccessResponse'
                    error: '#/components/schemas/TestConnectionFailureResponse'
              examples: # examples are not used from the schema
                ok:
                  summary: Test connection was success
                  value: { state: 'success' }
                ko:
                  summary: Test connection failed
                  value: { state: 'error', description: 'There was an error', errorType: 'temporary' }
        '400':
          $ref: '#/components/responses/InvalidClientConfigurationFormatResponse'
        '401':
          $ref: './common.yaml#/components/responses/AuthenticationFailedResponse'
        '403':
          $ref: './common.yaml#/components/responses/AuthorizationFailedResponse'
        '5XX':
          $ref: './common.yaml#/components/responses/ServerErrorResponse'
  /clients/{clientId}/messages:
    parameters:
      - $ref: './common.yaml#/components/parameters/clientIdPathParam'
    post:
      tags: [ Outbound Message Sending ]
      operationId: sendMessages
      summary: Send SMS messages to the Partner API
      requestBody:
        description: Messages to be sent
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutboundMessageBatch'
      responses:
        '202':
          $ref: './common.yaml#/components/responses/AcceptedResponse'
        '400':
          description: |
            Returns error type and error context globally, for all messages, or per message. 
            
            Use the OutboundMessageBatchGlobalError schema if there is an issue with the payload as a whole, and use the OutboundMessageBatchMessageSpecificError response schema if any of the messages are invalid.
            
            No messages should be sent or processed if the payload is invalid in any way, even if there are some valid messages among the invalid ones.
            
            Upon recieving a OutboundMessageBatchMessageSpecificError response, the Emarsys SMS Service will treat all of the messages with errors as failed and will retry any messages that did not have errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundMessageBatchError'
        '401':
          $ref: './common.yaml#/components/responses/AuthenticationFailedResponse'
        '403':
          $ref: './common.yaml#/components/responses/AuthorizationFailedResponse'
        '404':
          $ref: './common.yaml#/components/responses/ClientDoesNotExistResponse'
        '429':
          $ref: './common.yaml#/components/responses/TooManyRequestsResponse'
        '5XX':
          $ref: './common.yaml#/components/responses/ServerErrorResponse'

components:
  schemas:
    CustomFieldValues:
      type: object
      description: Object containing the values the client entered during onboarding mapped by their custom field name as key.
      minProperties: 1
      example:
        apiKey: 'abc123'
        servicePlanId: '123abc'
        baseUrl: 'https://api.sms.provider.io'
    CallbackUrl:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: A callback URL, provided by the Partner.'
          example: 'https://api.partner.io/callback-path/unique-id'
      required:
        - url
    ClientCallbackUrls:
      type: object
      properties:
        inboundMessages:
          allOf:
            - $ref: '#/components/schemas/CallbackUrl'
            - description: 'The inbound message callback URL, provided by the Partner.'
        deliveryReports:
          allOf:
            - $ref: '#/components/schemas/CallbackUrl'
            - description: 'The delivery report callback URL, provided by the Partner.'
    GetClientConfigurationResponse:
      type: object
      properties:
        customFieldValues:
          $ref: '#/components/schemas/CustomFieldValues'
        callbackUrls:
          $ref: '#/components/schemas/ClientCallbackUrls'
      required:
        - customFieldValues
        - callbackUrls
    CreateOrUpdateClientConfigurationResponse:
      type: object
      properties:
        callbackUrls:
          $ref: '#/components/schemas/ClientCallbackUrls'
      required:
        - callbackUrls
    CreateOrUpdateClientConfigurationRequest:
      type: object
      properties:
        customFieldValues:
          $ref: '#/components/schemas/CustomFieldValues'
      required:
        - customFieldValues
    TestConnectionRequest:
      type: object
      properties:
        customFieldValues:
          $ref: '#/components/schemas/CustomFieldValues'
      required:
        - customFieldValues
    TestConnectionSuccessResponse:
      type: object
      properties:
        state:
          type: string
          enum: [ success ]
          example: 'success'
          description: 'Connection test was successful when state is "success".'
      required:
        - state
    TestConnectionFailureResponse:
      type: object
      properties:
        state:
          type: string
          enum: [ error ]
          example: 'error'
          description: 'Connection test was unsuccessful when state is "error".'
        description:
          type: string
          example: 'There was an error'
          description: 'Description of the error.'
        errorType:
          type: string
          enum: [ temporary, credential, integration ]
          example: temporary
          description: |
            | Value | Description |
            |---|---|
            | temporary | There was a temporary issue whilst performing the request so try again later |
            | credential | There was a problem authorizing the client on the vendor platform |
            | integration | There is an issue related to the integration between Emarsys and the Partner service |
      discriminator:
        propertyName: state
      required:
        - state
        - description
        - errorType
    InvalidFieldError:
      type: object
      properties:
        fieldName:
          type: string
          example: 'servicePlanId'
          description: 'Key to uniquely identify the field.'
        description:
          type: string
          example: 'servicePlanId can only contain numbers.'
          description: 'Description of the error.'
        errorType:
          type: string
          enum: [ missing, invalid ]
          example: invalid
          description: 'Type of the error.'
      required:
        - fieldName
        - description
        - errorType
    InvalidFieldErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/InvalidFieldError'
          minItems: 1
    OutboundMessage:
      allOf:
        - $ref: './common.yaml#/components/schemas/Message'
        - $ref: './common.yaml#/components/schemas/EmarsysMessageId'
    OutboundMessageBatch:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/OutboundMessage'
          minItems: 1
          maxItems: 1000
      required:
        - messages
    OutboundMessageError:
      type: object
      properties:
        errorType:
          type: string
          enum: [ emarsys, client, partner, provider, unknown ]
          example: partner
          description: |
            | Value | Description |
            |---|---|
            | emarsys | There was a a problem with the message send payload |
            | client | There was a problem with the client setup |
            | partner | There was a problem at the partner |
            | provider | There was a problem at the provider |
            | unknown | There was an unknown problem |
        errorContext:
          type: object
          description: whatever seems to be useful
        isErrorTransient:
          type: boolean
          example: false
      required:
        - errorType
        - isErrorTransient
    OutboundMessageBatchGlobalError:
      type: object
      properties:
        globalError:
          allOf: # Combines the BasicErrorModel and the inline model
            - $ref: '#/components/schemas/OutboundMessageError'
            - type: object
    OutboundMessageBatchMessageSpecificError:
      type: object
      properties:
        messageSpecificErrors:
          type: array
          items:
            allOf: # Combines the BasicErrorModel and the inline model
              - $ref: '#/components/schemas/OutboundMessageError'
              - $ref: './common.yaml#/components/schemas/EmarsysMessageId'
    OutboundMessageBatchError:
      oneOf:
        - $ref: '#/components/schemas/OutboundMessageBatchGlobalError'
        - $ref: '#/components/schemas/OutboundMessageBatchMessageSpecificError'
  responses:
    InvalidClientConfigurationFormatResponse:
      description: Request body is invalid and does not follow API specification.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/InvalidFieldErrors'
  securitySchemes:
    oAuthAuthorization:
      type: oauth2
      description: OAuth client credentials grant type authorization
      flows:
        clientCredentials:
          tokenUrl: https://smsemarsys.accounts.ondemand.com/oauth2/token
          scopes: {}
security:
  - oAuthAuthorization: [ ]