openapi: 3.1.0
info:
  title: API dla systemu Krajowej Infolinii 19111
  description: Specyfikacja interfejsu umożliwiającego integrację z Krajową Infolinią 19111
  version: '1.0'

servers:
  - url: https://krajowa-infolinia-19111
tags:
  - name: call
    description: Przeprowadzona rozmowa
  - name: call-transcription
    description: Transkrypcja przeprowadzonej rozmowy
paths:
  /calls/{idCall}:
    get:
      tags:
        - call
      summary: Pobiera dane rozmowy na podstawie identyfikatora połączenia „idCall”
      description: Pobiera dane rozmowy na podstawie identyfikatora połączenia „idCall”
      operationId: getCallById
      parameters:
        - name: idCall
          in: path
          description: Identyfikator połączenia
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Operacja zakończyła się powodzeniem
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Call'
        '401':
          description: Brak autoryzacji, błąd uwierzytelnienia
        '404':
          description: Wskazany zasób nie istnieje np. Połączenie o wskazanym identyfikatorze
        '500':
          description: Wewnętrzny błąd serwera
  /calls/{idCall}/transcription:
    get:
      tags:
        - call-transcription
      summary: Pobiera transkrypcję rozmowy na podstawie identyfikatora połączenia „idCall”
      description: Pobiera transkrypcję rozmowy na podstawie identyfikatora połączenia „idCall”
      operationId: getCallTranscriptionByIdCall
      parameters:
        - name: idCall
          in: path
          description: Identyfikator połączenia
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Operacja zakończyła się powodzeniem
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallTranscription'
        '401':
          description: Brak autoryzacji, błąd uwierzytelnienia
        '404':
          description: Wskazany zasób nie istnieje np. Połączenie o wskazanym identyfikatorze
        '500':
          description: Wewnętrzny błąd serwera
      security:
        - sc_auth: []
components:
  schemas:
    Call:
      description: Komunikat z informacją o odebranej rozmowie przychodzącej lub wychodzącej
      required:
        - idCall
        - direction
        - phoneNumber
        - idAgent
        - answeredTimestamp
        - audioPlayerLink
        - audioDownloadLink
      type: object
      properties:
        idCall:
          description: Unikalny identyfikator połączenia z systemu Krajowej Infolinii 19111
          type: string
          examples: ['a961002e-41bf-49db-80e3-02406ad0391d']
        direction:
          type: string
          description: Kierunek połączenia
          $ref: "#/components/schemas/CallDirection"
          examples: ['INCOMING']
        phoneNumber:
          description: Numer telefonu rozmówcy
          type: string
          examples: ['+48123456789']
        contactName:
          description: Nazwa rozmówcy z książki kontaktowej
          type: string
          examples: ['Name from contacts']
        idAgent:
          description: Unikalny identyfikator użytkownika z systemu Krajowej Infolinii 19111, który przeprowadził rozmowę
          type: string
          examples: ['1001']
        answeredTimestamp:
          description: Data i czas rozpoczęcia rozmowy
          type: string
          format: date-time
          examples: ['2025-02-21T14:25:05+01:00']
        endTimestamp:
          description: Data i czas zakończenia rozmowy
          type: string
          format: date-time
          examples: ['2025-02-21T14:25:05+01:00']
        audioPlayerLink:
          description: Link do odtworzenia nagrania audio rozmowy w systemie Krajowej Infolinii 19111
          type: string
          examples: ['https://krajowa-infolinia-19111/calls/02406ad0391d/player']
        audioDownloadLink:
          description: Link do pobrania nagrania audio rozmowy z systemu Krajowej Infolinii 19111
          type: string
          examples: ['https://krajowa-infolinia-19111/calls/02406ad0391d/audio']
    CallDirection:
      description: |
        Kierunek połączenia:
        - INCOMING - Połączenie przychodzące
        - OUTGOING - Połączenie wychodzące
      enum:
        - INCOMING
        - OUTGOING
    CallTranscription:
      description: Komunikat z transkrypcją rozmowy
      required:
        - transcription
      type: object
      properties:
        transcription:
          type: array
          description: Elementy transkrypcji
          items:
            $ref: "#/components/schemas/TranscriptionElement"
          examples: [[{"timestamp":"00:00:00","client":"Dzień dobry"},{"timestamp":"00:00:01","agent":"Dzień dobry"}]]
    TranscriptionElement:
      description: Element transkrypcji
      required:
        - timestamp
      type: object
      properties:
        timestamp:
          description: Czas zarejestrowanej wypowiedzi względem czasu rozpoczęcia rozmowy
          type: string
          examples: ['00:00:01']
        client:
          description: Transkrypcja wypowiedzi dzwoniącego na Krajową Infolinię 19111
          type: string
          examples: ['Dzień dobry']
        agent:
          description: Transkrypcja wypowiedzi operatora Krajowej Infolinii 19111
          type: string
          examples: ['Dzień dobry']
  securitySchemes:
    sc_auth:
      type: http
      scheme: basic