openapi: "3.0.0"

info:
  version: 1.2.3
  title: Example API (Internal version)
  x-public-title: Example API
  x-lang-sk-title: Vzorové API (Interná verzia)
  x-public-x-lang-sk-title: Vzorové API
  x-lang-cz-title: Ukázkové API (Interní verze)
  x-public-x-lang-cz-title: Ukázkové API

  description: |
    This specification describes sending an SMS message via the 2022 version of the API.
    Sending messages in this way is the recommended way to send SMS rights over the API.

    An SMS account (account)** can be used to log into the API **, i.e. the same account that
    is used for logging in to sms-brana.sk. The account must have HTTP enabled in the settings.

  x-lang-sk-description: |
    Táto špecifikácia popisuje odoslanie SMS správy cez API vo verzii z roku 2022.
    Odosielanie správ podľa týmto spôsobom je odporúčaný spôsob odosielania SMS práv cez API.

    Na prihlasovanie do API **je možné použiť SMS účet (konto)**, teda rovnaký účet, ktorý sa používa
    aj na prihlasovanie do sms-brana.sk. Účet musí mať v nastaveniach povolené použitie cez HTTP.

  x-lang-cz-description: |
    Tato specifikace popisuje odeslání zprávy SMS prostřednictvím rozhraní API verze 2022.
    Odesílání zpráv tímto způsobem je doporučený způsob odesílání práv SMS přes rozhraní API.

    Pro přihlášení k API lze použít SMS účet (účet)**, tj. stejný účet, který se používá
    pro přihlášení k sms-brana.sk. Účet musí mít v nastavení povolen protokol HTTP.

  termsOfService: http://example.com/terms/
  contact:
    name: Mojoperator API Team
    email: apiteam@mojoperator.sk
    url: http://mojoperator.sk

servers:
  - url: https://devel.exmaple.com/api
    x-internal: true
    description: Development server (klingger)
    x-lang-sk-description: Vývojový server (klingger)
    x-lang-cz-description: Vývojový server (klingger)

  - url: https://api.example.sk
    description: Production server
    x-lang-sk-description: Produkčný server
    x-lang-cz-description: Produkční server

security:
  - BasicAuth: []

tags:
  - name: Sending
  - name: Query status

x-lang-sk-tags:
  - name: Odoslanie
  - name: Zistenie stavu

x-lang-cz-tags:
  - name: Odeslání
  - name: Zjištění stavu

paths:
  /sms/{authType}/send{responseFormat}:
    get:
      description: |
        ## Sending a text message

        Sending a message is governed by the parameters of the request, which can be passed as
        part of the URL (GET method) or in the body of the request (POST method). The content of the message is
        is passed in the encoding specified in the HTTP request. The API transcodes the message into the encoding used by
        in the telephony network and, if necessary, breaks long messages into parts.

        The most common encoding used for sending SMS is the 7-bit GSM-7 encoding, which allows sending
        messages without special characters of the Slovak alphabet with a length of 160 characters for a one-part message
        or 153 characters for a multipart message. For messages with special characters it is usually used
        16-bit UCS-2 / UTF-16 encoding with a message length of 70 characters for a one-part message, or
        67 characters for a multipart message. It is also possible to use 8-bit UTF-8 encoding with a length of 140 characters
        for a one-part message or 134 characters for a multi-part message, but this encoding does not have to be
        not be correctly supported by all operators or end-devices, and the API will therefore not be able to correctly support this encoding when autodetecting
        does not set this encoding (it can be manually set with the bits=8 parameter).

      x-lang-sk-description: |
        ## Odoslanie SMS správy

        Odoslanie správy sa riadi parametrami požiadavky, ktoré môžu byť odovzdané ako
        súčasť URL (metóda GET) alebo v tele požiadavky (metóda POST). Obsah správy (content) sa
        odovzdáva v kódovaní uvedenom v HTTP požiadavke. API správu prekóduje do kódovania používaného
        v telefónnej sieti a ak je to potrebné, dlhé správy rozdelí na časti.

        Najčastejšie sa pre odosielanie SMS používa 7-bitové kódovanie GSM-7, ktoré umožňuje posielať
        správy bez špeciálnych znakov slovenskej abecedy s dĺžkou 160 znakov pri jednodielnej správe
        alebo 153 znakov pri viacdielnej správe. Pre správy so špeciálnymi znakmi sa obvykle používa
        16-bitové kódovanie UCS-2 / UTF-16 s dĺžkou správy 70 znakov pri jednodielnej správe alebo
        67 znakov pri viacdielnej správe. Je možné použiť aj 8-bitové kódovanie UTF-8 s dĺžkou 140 znakov
        pri jednodielnej správe alebo 134 znakov pri viacdielnej správe, avšak toto kódovanie nemusí byť
        korektne podporované všetkými operátormi alebo koncovými zariadeniami a API preto pri autodetekcii
        toto kódovanie nenastavuje (môže byť manuálne nastavené parametrom bits=8).

      x-lang-cz-description: |
        ## Odeslání textové zprávy

        Odeslání zprávy se řídí parametry požadavku, které mohou být předány jako  součástí adresy URL
        (metoda GET) nebo v těle požadavku (metoda POST). Obsah zprávy je  je předán v kódování uvedeném
        v požadavku HTTP. Rozhraní API překóduje zprávu do kódování používaného rozhraním
        v telefonní síti a v případě potřeby rozdělí dlouhé zprávy na části.

        Nejběžnějším kódováním používaným pro odesílání SMS je 7bitové kódování GSM-7, které umožňuje odesílat
        zprávy bez speciálních znaků slovenské abecedy o délce 160 znaků pro jednodílnou zprávu. nebo 153
        znaků pro vícedílnou zprávu. Pro zprávy se speciálními znaky se obvykle používá 16bitové kódování
        UCS-2 / UTF-16 s délkou zprávy 70 znaků pro jednodílnou zprávu nebo 67 znaků pro vícedílnou zprávu.
        Je také možné použít 8bitové kódování UTF-8 o délce 140 znaků pro jednodílnou zprávu nebo 134 znaků
        pro vícedílnou zprávu, ale toto kódování nemusí být nutně  nebudou správně podporovány všemi
        operátory nebo koncovými zařízeními, a rozhraní API proto nebude schopno správně podporovat
        toto kódování při automatické detekci.  toto kódování nenastavuje (lze jej nastavit ručně pomocí
        parametru bits=8).


      tags:
        - Sending
      x-lang-sk-tags:
        - Odoslanie
      x-lang-cz-tags:
        - Odeslání
      operationId: sendSMS
      parameters:
        - $ref: "#/components/parameters/AuthType"

        - $ref: "#/components/parameters/ResponseFormat"

        - name: src
          in: query
          required: false
          description: |
            Identification of the sender of the message (alphanumeric string or number).
            If the parameter is not  parameter is specified, the default value from the SMS account
            settings is used.

          x-lang-sk-description: |
            Identifikácia odosielateľa správy (alfanumerický reťazec alebo číslo). Ak parameter nie
            je zadaný, použije sa predvolená hodnota z nastavenia SMS účtu.

          x-lang-cz-description: |
            Identifikace odesílatele zprávy (alfanumerický řetězec nebo číslo). Pokud parametr
            není je zadán parametr, použije se výchozí hodnota z nastavení účtu SMS.

          schema:
            type: string

        - name: dst
          in: query
          required: true
          description: |
            Identification of the recipient or recipients of the message (phone number or multiple
            numbers separated by comma and/or space separators). We recommend that the number
            is given in international format with an initial '+' (for example, '+421943123456').
            Numbers in other forms will automatically be converted to the international form.

          x-lang-sk-description: |
            Identifikácia príjemcu alebo príjemcov správy (telefónne číslo alebo viaceré čísla
            oddelené oddeľovačmi čiarka a/alebo medzera). Odporúčame uvádzať číslo v medzinárodnom
            tvare s úvodným "+" (napríklad "+421943123456"). Čísla v iných tvaroch budú automaticky
            prevedené do medzinárodného tvaru.

          x-lang-cz-description: |
            Identifikace příjemce nebo příjemců zprávy (telefonní číslo nebo více čísel oddělených
            čárkou a/nebo mezerou). Doporučuje se, aby číslo bylo v mezinárodní s počátečním
            znakem "+" (například "+421943123456"). Čísla v jiných formulářích budou automaticky
            převedeny do mezinárodní podoby.

          schema:
            oneOf:
              - $ref: '#/components/schemas/SrcString'
              - $ref: '#/components/schemas/SrcArray'

        - name: content
          in: query
          required: true
          description: Message content (text). The parameter is required.
          x-lang-sk-description: Obsah správy (text). Parameter je povinný.
          x-lang-cz-description: Obsah zprávy (text). Parametr je povinný.
          schema:
            type: string

        - name: evid
          x-internal: true
          in: query
          required: false
          description: |
            Required if the login method does not allow the records to be
            detected automatically - softswitch

          x-lang-sk-description: |
            Povinné ak spôsob prihlásenia neumožňuje evid zistiť automaticky - softswitch

          x-lang-cz-description: |
            Vyžadováno, pokud metoda přihlášení neumožňuje automatickou detekci záznamů - softswitch

          schema:
            type: integer

        - name: bits
          in: query
          description: |
            Message encoding (number of bits). Possible values are "7", "8", "16"
            and "auto" (default value - autodetection according to the "content" parameter).

          x-lang-sk-description: |
            Kódovanie správy (počet bitov). Prípustné hodnoty sú "7", "8", "16"
            a "auto" (predvolená hodnota - autodetekcia podľa obsahu parametra "content").

          x-lang-cz-description: |
            Kódování zprávy (počet bitů). Přípustné hodnoty jsou "7", "8", "16".
            a "auto" (výchozí hodnota - autodetekce podle parametru "content").

          schema:
            type: integer
            enum: [7,8,16,auto]
            default: auto

        - name: convert
          in: query
          schema:
            type: boolean
            enum: [0,1,false,true,"f","t"]
            default: false

          description: |
            Specifies whether to convert the message content to the specified number of bits (which
            is useful especially useful when sending 7-bit messages). When converting, characters
            that are not supported in the selected encoding are replaced by similar characters
            or character sequences so that so that the content of the message is preserved as far
            as possible. Allowable values are '1' (convert) and '0' (do not convert - default value).
            If conversion is disabled and the message text cannot be transcoded into the selected number
            of bits, the API will respond with an error.

          x-lang-sk-description: |
            Určuje, či sa má obsah správy konvertovať na zadaný počet bitov (čo je užitočné
            najmä pri posielaní 7-bitových správ). Pri konverzii sa znaky, ktoré nie sú podporované
            vo zvolenom kódovaní, nahradia podobnými znakmi alebo sekvenciami znakov tak,
            aby bol obsah správy v rámci možností zachovaný. Prípustné hodnoty sú "1" (konvertovať)
            a "0" (nekonvertovať - predvolená hodnota). Ak je konvertovanie vypnuté a text správy
            nie je možné prekódovať do zvoleného počtu bitov, API odpovie chybou.

          x-lang-cz-description: |
            Určuje, zda se má obsah zprávy převést na zadaný počet bitů (což je užitečné, pokud se jedná o
            zvláště užitečné při odesílání 7bitových zpráv). Při převodu jsou znaky, které nejsou podporovány
            ve zvoleném kódování jsou nahrazeny podobnými znaky nebo sekvencemi znaků, takže
            aby byl obsah zprávy co nejvíce zachován. Přípustné hodnoty jsou "1" (převést)
            a "0" (nepřevádět - výchozí hodnota). Pokud je konverze zakázána a text zprávy
            nelze překódovat na zvolený počet bitů, rozhraní API odpoví chybou.

        - name: flash
          in: query
          schema:
            type: integer
            enum: [0,1,false,true,"f","t"]
            default: 0

          description: |
            Specifies whether the message will be sent with a flash flag that causes an immediate display
            the message on the phone's display when it is received, without saving the message in the inbox.
            Possible values are "1" (enable flash) and "0" (normal message - default value). When sending
            flash SMS, we strongly recommend to use only 7-bit encoding (messages in other encodings are
            not displayed correctly on some terminals) and only send one-part messages (end devices usually
            do not support the display of multi-part flash messages).

          x-lang-sk-description: |
            Určuje, či správa bude poslaná s príznakom flash, ktorý spôsobí okamžité zobrazenie
            správy na displeji telefónu po jej doručení, bez uloženia správy do priečinka prijatých správ.
            Prípustné hodnoty sú "1" (zapnúť flash) a "0" (normálna správa - predvolená hodnota).
            Pri odosielaní flash SMS výrazne odporúčame používať iba 7-bitové kódovanie
            (správy v iných kódovaniach nie sú na niektorých koncových zariadeniach zobrazované správne)
            a odosielať iba jednodielne správy (koncové zariadenia obvykle nepodporujú zobrazenie
            viacdielnych flash správ).

          x-lang-cz-description: |
            Určuje, zda bude zpráva odeslána s příznakem flash, který způsobí okamžité zobrazení.
            zprávu na displeji telefonu při jejím přijetí, aniž by se zpráva uložila do složky Doručená pošta.
            Možné hodnoty jsou "1" (povolit blesk) a "0" (normální zpráva - výchozí hodnota).
            Při odesílání flash SMS důrazně doporučujeme používat pouze 7bitové kódování.
            (zprávy v jiných kódováních se na některých terminálech nezobrazují správně)
            a posílat pouze jednočásticové zprávy (koncová zařízení obvykle nepodporují zobrazení dat).

        - name: time_send
          in: query
          schema:
            type: string
            format: date-time

          description: |
            The message shall be sent at the date and time indicated. The parameter is optional.
            Recommended format is 'YYYY-MM-DD HH:MM:SS', the format 'DD.MM.YYYY HH:MM:SS' is also supported,
            the indication of seconds is optional.

          x-lang-sk-description: |
            Správa sa odošle v uvedenom dátume a čase. Parameter je nepovinný. Odporúčaný formát
            je "YYYY-MM-DD HH:MM:SS", podporovaný je aj formát "DD.MM.YYYY HH:MM:SS",
            uvedenie sekúnd je nepovinné.

          x-lang-cz-description: |
            Zpráva se odešle v uvedené datum a čas. Parametr je nepovinný. Doporučený formát
            je "YYYY-MM-DD HH:MM:SS", podporován je také formát "DD.MM.YYYY HH:MM:SS",
            údaj o sekundách je nepovinný.

      responses:
        "200":
          description: Result of the operation
          x-lang-sk-description: Výsledok operácie
          x-lang-cz-description: Výsledek operace
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      response:
                        type: object
                        properties:
                          additionalProperties:
                            $ref: '#/components/schemas/SendResponse'
              example:
                status: ok
                error: null
                response:
                  "0901234567":
                    status: ok
                    error: null
                    msg_id: 123456
                    dst: "421901234567"
                    src: "421907894564"
                    content: "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
                    bits: 7
                  "123":
                    status: error
                    error: Invalid destination number
                    msg_id: null
                    dst: "123"
                    src: "421907894564"
                    content: "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
                    bits: 7

  /sms/{authType}/query{responseFormat}:
    get:
      description: |
        ## Query the SMS sending status

        The status of sending a message can be detected by the message identifier provided
        by the API in response to sending the message. With a single request, it is possible
        to get the status of one or multiple messages.

      x-lang-sk-description: |
        ## Zistenie stavu odoslania SMS

        Stav odoslania správy sa dá zistiť podľa identifikátora správy, ktorý API poskytne
        ako odpoveď na odoslanie správy. Jednou požiadavkou je možné získať stav jednej
        alebo viacerých správ.

      x-lang-cz-description: |
        ## Zjištění stavu odeslání SMS

        Stav odeslání zprávy lze zjistit podle identifikátoru zprávy, který poskytuje rozhraní API.
        v reakci na odeslání zprávy. Jediným požadavkem lze získat stav jednoho
        nebo více zpráv.

      tags:
        - Query status

      x-lang-sk-tags:
        - Zistenie stavu

      x-lang-cz-tags:
        - Zjištění stavu

      operationId: querySMS

      parameters:
        - $ref: "#/components/parameters/AuthType"
        - $ref: "#/components/parameters/ResponseFormat"
        - name: msg_id
          in: query
          required: true
          schema:
            oneOf:
              - $ref: '#/components/schemas/SrcString'
              - $ref: '#/components/schemas/SrcArray'

      responses:
        "200":
          description: Result of the operation
          x-lang-sk-description: Výsledok operácie
          x-lang-cz-description: Výsledek operace
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      response:
                        properties:
                          additionalProperties:
                            $ref: '#/components/schemas/QueryResponse'

components:
  schemas:
    ApiResponse:
      type: object
      properties:
        status:
          type: string
          enum: [ok,error]
          description: |
            - `ok` - the operation was successful
            - `error` - an error occurred
          x-lang-sk-description: |
            - `ok` - operácia bola úspešná
            - `error` - došlo k chybe
          x-lang-cz-description: |
            - `ok` - operáce byla úspěšná
            - `error` - došlo k chybě
        error:
          type: string
          nullable: true
          description: If the status is "error", it contains a textual description of the error
          x-lang-sk-description: Ak je stav "error", obsahuje textový popis chyby
          x-lang-cz-description: Pokud je stav "error", obsahuje textový popis chyby


    SendResponse:
      type: "object"
      allOf:
        - $ref: '#/components/schemas/ApiResponse'
        - type: object
          properties:
            msg_id:
              type: integer
              description: msg_id of the message in the SMS centre
              x-lang-sk-description: msg_id správy v SMS centre
              x-lang-cz-description: msg_id zprávy v SMS centre
              format: int64

            dst:
              type: string
              description: Formatted target number
              x-lang-sk-description: Naformátované cieľové číslo
              x-lang-cz-description: Naformátované cílové číslo

            src:
              type: string
              description: Formatted source number
              x-lang-sk-description: Naformátované číslo odosielateľa
              x-lang-cz-description: Naformátované číslo odesílatele

            content:
              type: string
              description: Message content (text) after possible conversion.
              x-lang-sk-description: Obsah správy (text) po prípadnje konverzii.
              x-lang-cz-description: Obsah zprávy (text) po případne konverzi.

            bits:
              type: integer
              enum: [7, 8, 16]
              description: Used number of bits
              x-lang-sk-description: Použitý počet bitov
              x-lang-cz-description: Použitý počet bitů

    QueryResponse:
      type: object
      properties:
        msg_id:
          type: integer
          description: msg_id messages received by the send method
          x-lang-sk-description: msg_id správy obdržané cez metódu send
          format: int64

        status:
          type: string
          enum: [DELIVERED, EXPIRED, DELETED, UNDELIVERABLE, ACCEPTED, UNKNOWN, REJECTED]
          description: Message status in the SMS centre
          x-lang-sk-description: Stav správy v SMS centre

        error_code:
          type: integer
          description: Error code
          x-lang-sk-description: Chybový kód
          x-lang-cz-description: Chybový kód

        error_description:
          type: string
          description: Text description of the error
          x-lang-sk-description: Textový popis chyby
          x-lang-cz-description: Textový popis chyby

    SrcString:
      type: string
      description: List of numbers separated by a comma
      x-lang-sk-description: Zoznam čísel oddelených čiarkou
      x-lang-cz-description: Seznam čísel oddělených čárkou

    SrcArray:
      type: array
      description: List of numbers as an array
      x-lang-sk-description: Zoznam čísel ako pole
      x-lang-cz-description: Seznam čísel jako pole
      items:
        type: string

    MsgIdString:
      type: string
      description: Comma separated list of msg_id
      x-lang-sk-description: Zoznam msg_id oddelených čiarkou
      x-lang-cz-description: Seznam msg_id oddělených čárkou

    MsgIdArray:
      type: array
      description: List msg_id as an array
      x-lang-sk-description: Zoznam msg_id ako pole
      x-lang-cz-description: Seznam msg_id jako pole
      items:
        type: string

  parameters:
    AuthType:
      name: authType
      in: path
      description: |
        Supported types:
          * `authType1` - Login method 1
          * `authType2` - Login method 1
      x-public-description: |
        Supported types:
          * `authType1` - Login method 1
      x-lang-sk-description: |
        Podporované typy:
          * `authType1` - Spôsob prihlásenia 1
          * `authType2` - Spôsob prihlásenia 2
      x-public-x-lang-sk-description: |
        Podporované typy:
          * `account` - Spôsob prihlásenia 1
      x-lang-cz-description: |
        Podporované typy:
          * `authType1` - Způsob přihlášení 1
          * `authType2` - Způsob přihlášení 1
      x-public-x-lang-cz-description: |
        Podporované typy:
          * `authType1` - Způsob přihlášení 1
      required: true
      schema:
        type: string
        enum: [account, softswitch]
        x-public-enum: [account]

    ResponseFormat:
      name: responseFormat
      in: path
      required: true
      schema:
        type: string
        enum: [".json"]
      description: |
        Response format

        Supported formats are:
          * `.json`
      x-lang-sk-description: |
        Formát odpovede

        Podporované formáty sú:
          * `.json`
      x-lang-cz-description: |
        Formát odpovědi

        Podporované formáty jsou:
          * `.json`

  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic


