swagger.yaml

openapi: 3.0.0
info:
  title: zScanner REST API
  version: 3.1.0

servers:
  - url: https://tempra.ikem.cz/api/public/v1

paths:
  /medicalc/v3.1/departments:
    get:
      summary: Get available departments
      operationId: getDepartments
      responses:
        "200":
          description: |
            List of available departments for the logged-in user.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: objectdepartments
                  properties:
                    code:
                      type: string
                    display:
                      type: string
                        
              example: 
                [
                  { "id": "kardiologie", "display": "Kardiologie" },
                  { "id": "diabetologie", "display": "Diabetologie" },
                  { "id": "orl", "display": "ORL" },
                  { "id": "nefrologie", "display": "Nefrologie" }
                ]
      
  /medicalc/v3.1/documenttypes:
    get:
      summary: Get available document types and sub-types
      operationId: getDocumentTypes
      parameters:
        - name: department
          in: query
          description: current department of the user
          required: true
          schema:
            type: string
      responses:
        "200":
          description: |
            List of available document types and sub-types.
          content:
            application/json:
              schema:
                type: object
                required:
                  - type
                properties:
                  type: 
                    type: array
                    items: 
                      $ref: '#/components/schemas/DocumentType'
              example: 
                {
                  type: [
                    { "id": "photo", "display": "Fotografie" },
                    { "id": "ext", "display": "Dokumentace z jiného zdravotnického zařízení", sub-types: [
                      { "id": "histology-biopsy", "display": "Histologie/Biopsie" },
                      { "id": "lab-results", "display": "Laboratorní vyšetření" },
                      { "id": "op-protocol", "display": "Operační protokol" }
                    ]},
                    { "id": "infconsent", "display": "Informovaný souhlas" },
                    { "id": "revers", "display": "Revers" },
                    { "id": "sono", "display": "Sonografické vyšetření",  sub-types: [
                      { "id": "Scan", "display": "Scan" },
                    ]}, 
                  ]
                }
                
  /medicalc/v3.1/folders/search:
    get:
      summary: Search for a folder via NIN (national identification number)
      operationId: findFolderByName
      parameters:
        - name: query
          in: query
          description: national identification number of patient
          required: true
          schema:
            type: string
      responses:
        "200":
          description: List of folders matching the NIN
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentFolder'
              example: 
                [
                  { "externalId": "925221/9449", "internalId": "124587112", "name": "Fiona Shreková" },
                  { "externalId": "011116/0632", "internalId": "124587113", "name": "Šípková Růženka" }
                ]
            
  /medicalc/v3.1/folders/decode:
    get:
      summary: Get a folder by internalId
      operationId: findFolderByInternalId
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Folder matching the ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentFolder'
              example:
                { "externalId": "925221/9449", "internalId": "124587112", "name": "Fiona Shreková" }


  /medicalc/v3.1/documents/summary:
    post:
      summary: Post summary of a set of photos
      operationId: postSummary
      description: |
        This is a call sent by the phone to post a summary of the document being submitted.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DocumentSummary"
            examples:
              enumeratedDocumentType:
                description: "Typ dokumentu z číselníku"
                value:
                  {
                    "correlation": "30ca99cc-af1b-4c41-bb83-d1a40a18e354",
                    "folderInternalId": "788392",
                    "documentType": "ext",
                    "documentSubType": "lab-results",
                    "pages": 1,
                    "datetime": "2000-01-02T12:34:12Z"
                  }
              genericPhoto:
                description: "Obecná fotografie"
                value:
                  {
                    "correlation": "39d4294a-0066-453d-9a97-53252574ec83",
                    "folderInternalId": "788392",
                    "documentType": "photo",
                    "pages": 2,
                    "datetime": "2000-01-02T12:34:12Z"
                  }
                  
      responses:
        "200":
          description: Summary posted successfully
        "400":
          description: Error in request
    
  /medicalc/v3.1/documents/page:
    post:
      summary: Post an individual page
      operationId: postPage
      description: |
        This call is sent by the phone to post an individual page of the document being submitted.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                page:
                  type: string
                  format: binary
                  description: Binary content of the image.
                correlation:
                  type: string
                  description: Correlation ID referencing the document summary.
                pageIndex:
                  type: number
                  description: Index of the page within the document. The first page has index 0.
                description:
                  type: string
                  
              required:
                - page
                - correlation
                - pageIndex
      responses:
        200:
          description: Page posted successfully
        400:
          description: Error in request
                
  
components:
  schemas:
    DocumentType:
      type: object
      required:
        - id
        - 
      properties:
        id:
          type: string
        display:
          type: string
        sub-types:
          type: array
          items: 
            $ref: '#/components/schemas/DocumentSubType'

    DocumentSubType:
      type: object
      properties:
        id:
          type: string
        display:
          type: string
    
    DocumentSummary:
      type: object
      properties:
        correlation:
          type: string
        folderInternalId:
          type: string
        documentType:
          type: string
        documentSubType:
          type: string
        department:
          type: string
        pages:
          type: number
        datetime:
          type: string
          format: date-time
    

    DocumentFolder:
      type: object
      properties:
        externalId:
          type: string
        internalId:
          type: string
        name:
          type: string
      required:
        - externalId
        - internalId
        - name