openapi: 3.0.3
info:
  title: TopSMS.cz REST API
  version: "1.0"
  description: |
    Česká SMS brána — odeslání SMS, stav doručení a zůstatek kreditu.
    Autentizace: hlavička "Authorization: Bearer <clientId>:<secret>".
    Klíče spravujete v dashboardu (https://www.topsms.cz/dashboard/api).
    Push doručenky: u API klíče lze nastavit webhook URL — při změně stavu
    zprávy pošleme HTTP POST (payload viz komponenta WebhookEvent, podpis
    v hlavičce X-TopSMS-Signature: sha256=HMAC-SHA256(body, webhookSecret),
    3 pokusy: ihned, +30 s, +2 min).
  contact:
    email: info@topsms.cz
    url: https://www.topsms.cz/api-integrace/rest-api
servers:
  - url: https://www.topsms.cz
security:
  - bearerAuth: []
paths:
  /api/sms/send:
    post:
      summary: Odeslání SMS (scope send)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [to, text]
              properties:
                to: { type: string, example: "+420601234567", description: "Číslo v mezinárodním formátu" }
                text: { type: string, example: "Vase objednavka je na ceste." }
                from: { type: string, maxLength: 11, example: "MojeFirma", description: "Schválené Sender ID; výchozí TopSMS" }
      responses:
        "200":
          description: Odesláno, kredit odečten
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  id: { type: string, description: "Interní ID zprávy (pro status)" }
                  externalId: { type: string, nullable: true }
                  to: { type: string }
                  from: { type: string }
                  smsCount: { type: integer, description: "Počet účtovaných segmentů" }
                  price: { type: number, description: "Cena v Kč" }
                  status: { type: string, example: sent }
        "400": { $ref: "#/components/responses/Error" }
        "401": { $ref: "#/components/responses/Error" }
        "402": { $ref: "#/components/responses/Error" }
        "403": { $ref: "#/components/responses/Error" }
        "429": { $ref: "#/components/responses/Error" }
        "502": { $ref: "#/components/responses/Error" }
  /api/sms/status/{id}:
    get:
      summary: Stav doručení zprávy (scope read)
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
          description: Interní id nebo externalId z odpovědi na odeslání
      responses:
        "200":
          description: Detail zprávy
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string }
                  externalId: { type: string, nullable: true }
                  to: { type: string }
                  from: { type: string }
                  text: { type: string }
                  status: { type: string, enum: [sent, delivered, failed, expired, pending] }
                  price: { type: number }
                  carrier: { type: string, nullable: true }
                  createdAt: { type: string, format: date-time }
                  deliveredAt: { type: string, format: date-time, nullable: true }
                  failedAt: { type: string, format: date-time, nullable: true }
                  errorMessage: { type: string, nullable: true }
        "404": { $ref: "#/components/responses/Error" }
  /api/credit:
    get:
      summary: Zůstatek kreditu (scope read)
      responses:
        "200":
          description: Aktuální zůstatek
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  credit: { type: number, description: "Zůstatek v Kč" }
                  currency: { type: string, example: CZK }
                  smsPrice: { type: number, description: "Cena za SMS dle tarifu" }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "Bearer <clientId>:<secret>"
  responses:
    Error:
      description: Chyba
      content:
        application/json:
          schema:
            type: object
            properties:
              error: { type: string }
  schemas:
    WebhookEvent:
      type: object
      description: Payload HTTP POST na webhook URL při změně stavu zprávy
      properties:
        event: { type: string, example: sms.status }
        id: { type: string }
        externalId: { type: string, nullable: true }
        to: { type: string }
        from: { type: string }
        status: { type: string, enum: [delivered, failed, expired] }
        price: { type: number }
        deliveredAt: { type: string, format: date-time, nullable: true }
        failedAt: { type: string, format: date-time, nullable: true }
        errorMessage: { type: string, nullable: true }
        sentAt: { type: string, format: date-time }