swagger.yml

openapi: "3.0.0"
info:
  version: 1.0.0
  description: This is REST endpoints API documentation for E-invoice project.
  title: E-invoice API
servers:
  - description: Dev
    url: https://dev.api.einvoice.mfsr.sk
tags:
  - name: Auth
  - name: Users
  - name: Invoices
  - name: Drafts
paths:
  /login:
    get:
      tags:
        - Auth
      summary: Authenticate user with ÚPVS (slovensko.sk) token
      security:
        - upvsOboTokenAuth: []
      responses:
        '200':
          $ref: '#/components/responses/Login'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '424':
          $ref: '#/components/responses/Error'
  /logout:
    get:
      tags:
        - Auth
      summary: Logout user from e-invoice
      security:
        - sessionAuth: []
      responses:
        '200':
          $ref: '#/components/responses/Logout'
        '401':
          $ref: '#/components/responses/Error'
  /upvs/logout:
    get:
      tags:
        - Auth
      summary: Redirect to ÚPVS (slovensko.sk) logout
      description: |
        Redirect to ÚPVS and invalidate OBO token.
        If OBO token is already invalid redirect to ÚPVS callback directly
      parameters:
        - name: token
          in: query
          description: OBO token
          schema:
            type: string
          required: true
        - name: callback
          in: query
          description: |
            Callback URL, to which user will be redirected once logout is successful.
            Callback URL has to be same as one of the addresses set at the component API level,
            or it has to be an extension of one of these addresses.
          schema:
            type: string
          required: true
      responses:
        '302':
          description: Redirect user to ÚPVS logout
        '401':
          $ref: '#/components/responses/Error'

  /users/{userId}:
    parameters:
      - name: userId
        in: path
        description: ID of user to be affected
        required: true
        schema:
          type: integer
    get:
      tags:
        - Users
      summary: Get info about requested user
      security:
        - sessionAuth: []
        - apiKeyAuth: []
      responses:
        '200':
          description: User data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '401':
          $ref: '#/components/responses/Error'
    patch:
      tags:
        - Users
      summary: Update user info
      security:
        - sessionAuth: []
        - apiKeyAuth: []
      requestBody:
        $ref: '#/components/requestBodies/PatchUser'
      responses:
        '200':
          description: Updated user info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
  /users/{userId}/substitutes:
    parameters:
      - name: userId
        in: path
        description: ID of user to be affected
        required: true
        schema:
          type: integer
    post:
      tags:
        - Users
      summary: Add substitute users
      description: Add rights for particular users to create invoices on your behalf
      security:
        - sessionAuth: []
        - apiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubstituteIds'
      responses:
        '200':
          description: List of substitute Ids that were successfully added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubstituteIds'
        '400':
          $ref: '#/components/responses/Error'
    delete:
      tags:
        - Users
      summary: Remove substitute users
      description: Revoke rights for particular users to create invoices on your behalf
      security:
        - sessionAuth: []
        - apiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubstituteIds'
      responses:
        '200':
          description: List of substitute Ids that were successfully removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubstituteIds'
        '400':
          $ref: '#/components/responses/Error'
    get:
      tags:
        - Users
      summary: Get substitute users
      description: Get list of users that can create invoices on your behalf
      security:
        - sessionAuth: []
        - apiKeyAuth: []
      responses:
        '200':
          description: List of substitute user Ids of requested user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubstituteIds'
  /users/{userId}/organizations:
    get:
      tags:
        - Users
      summary: Get substituted organizations
      description: Get list of IČOs that requested user can create invoices on behalf of
      parameters:
        - name: userId
          in: path
          description: User ID
          required: true
          schema:
            type: integer
      security:
        - sessionAuth: []
        - apiKeyAuth: []
      responses:
        '200':
          description: List of substituted organizations for requested user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubstitutedOrganizations'
  /users/{userId}/invoices:
    get:
      tags:
        - Users
      summary: Get all invoices requested user can view
      parameters:
        - name: userId
          in: path
          description: Get invoices of user with this user ID
          required: true
          schema:
            type: integer
        - $ref: '#/components/parameters/InvoiceFormat'
        - $ref: '#/components/parameters/StartId'
        - $ref: '#/components/parameters/Order'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/TestInvoice'
        - $ref: '#/components/parameters/AmountFrom'
        - $ref: '#/components/parameters/AmountTo'
        - $ref: '#/components/parameters/AmountCurrency'
        - $ref: '#/components/parameters/AmountWithoutVatFrom'
        - $ref: '#/components/parameters/AmountWithoutVatTo'
        - $ref: '#/components/parameters/AmountWithoutVatCurrency'
        - $ref: '#/components/parameters/IssueDateFrom'
        - $ref: '#/components/parameters/IssueDateTo'
        - $ref: '#/components/parameters/UploadTimeFrom'
        - $ref: '#/components/parameters/UploadTimeTo'
        - $ref: '#/components/parameters/CustomerName'
        - $ref: '#/components/parameters/SupplierName'
        - $ref: '#/components/parameters/CustomerIco'
        - $ref: '#/components/parameters/SupplierIco'
      security:
        - sessionAuth: []
        - apiKeyAuth: []
      responses:
        '200':
          description: List of user invoices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoices'

  /invoices:
    get:
      tags:
        - Invoices
      summary: Get list of metadata of public invoices
      parameters:
        - $ref: '#/components/parameters/InvoiceFormat'
        - $ref: '#/components/parameters/StartId'
        - $ref: '#/components/parameters/Order'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/TestInvoice'
        - $ref: '#/components/parameters/AmountFrom'
        - $ref: '#/components/parameters/AmountTo'
        - $ref: '#/components/parameters/AmountCurrency'
        - $ref: '#/components/parameters/AmountWithoutVatFrom'
        - $ref: '#/components/parameters/AmountWithoutVatTo'
        - $ref: '#/components/parameters/AmountWithoutVatCurrency'
        - $ref: '#/components/parameters/IssueDateFrom'
        - $ref: '#/components/parameters/IssueDateTo'
        - $ref: '#/components/parameters/UploadTimeFrom'
        - $ref: '#/components/parameters/UploadTimeTo'
        - $ref: '#/components/parameters/CustomerName'
        - $ref: '#/components/parameters/SupplierName'
        - $ref: '#/components/parameters/CustomerIco'
        - $ref: '#/components/parameters/SupplierIco'
      responses:
        '200':
          description: Successfull response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoices'
    post:
      security:
        - sessionAuth: []
        - apiKeyAuth: []
      tags:
        - Invoices
      summary: Create invoice
      requestBody:
        description: "UBL2.1 or D16B invoice"
        content:
          application/xml:
            schema:
              type: object
              xml:
                name: Invoice
      responses:
        '201':
          description: Invoice created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '400':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '424':
          $ref: '#/components/responses/Error'
  /invoices/test:
    post:
      security:
        - sessionAuth: []
        - apiKeyAuth: []
      tags:
        - Invoices
      summary: Create test invoice
      requestBody:
        description: "UBL2.1 or D16B invoice"
        content:
          application/xml:
            schema:
              type: object
              xml:
                name: Invoice
      responses:
        '201':
          description: Test invoice created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '400':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'

  /invoices/visualization:
    post:
      tags:
        - Invoices
      summary: Get visualization of sent invoice
      requestBody:
        description: "UBL2.1 or D16B invoice"
        content:
          application/xml:
            schema:
              type: object
              xml:
                name: Invoice
      responses:
        '200':
          description: Successful response
          content:
            application/zip:
              schema:
                type: string
                format: binary
  /invoices/{invoiceId}:
    get:
      tags:
        - Invoices
      summary: Get invoice meta data
      parameters:
        - name: invoiceId
          in: path
          description: Invoice ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfull response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
  /invoices/{invoiceId}/detail:
    get:
      tags:
        - Invoices
      summary: Get invoice content
      parameters:
        - name: invoiceId
          in: path
          description: Invoice ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Invoice'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
  /invoices/{invoiceId}/visualization:
    get:
      tags:
        - Invoices
      summary: Get invoice visualization
      parameters:
        - name: invoiceId
          in: path
          description: Invoice ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
  /drafts:
    get:
      tags:
        - Drafts
      security:
        - sessionAuth: []
      summary: Get my invoice drafts
      responses:
        '200':
          description: List of draft metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Drafts'
        '403':
          $ref: '#/components/responses/Error'
    post:
      tags:
        - Drafts
      security:
        - sessionAuth: []
      summary: Create my invoice draft
      requestBody:
        description: Draft of invoice form
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                data:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - invoice
                        - creditNote
                    data:
                      type: object
                      description: Redux state of invoice form
      responses:
        '201':
          description: Draft created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Draft'
        '400':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
  /drafts/{draftId}:
    get:
      tags:
        - Drafts
      security:
        - sessionAuth: []
      summary: Get draft content
      parameters:
        - $ref: '#/components/parameters/DraftId'
      responses:
        '200':
          description: Draft
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - invoice
                      - creditNote
                  data:
                    type: object
                    description: Redux state of invoice form
    patch:
      tags:
        - Drafts
      security:
        - sessionAuth: []
      summary: Update draft
      requestBody:
        description: Draft of invoice form
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  nullable: true
                data:
                  type: object
                  nullable: true
                  properties:
                    type:
                      type: string
                      enum:
                        - invoice
                        - creditNote
                    data:
                      type: object
                      description: Redux state of invoice form
      parameters:
        - $ref: '#/components/parameters/DraftId'
      responses:
        '200':
          description: Updated draft
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchedDraft'
    delete:
      tags:
        - Drafts
      security:
        - sessionAuth: []
      summary: Delete draft
      parameters:
        - $ref: '#/components/parameters/DraftId'
      responses:
        '200':
          description: ID of deleted draft
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
        '403':
          $ref: '#/components/responses/Error'
components:
  securitySchemes:
    upvsOboTokenAuth:
      description: OBO token received from ÚPVS (slovensko.sk)
      type: http
      scheme: bearer
      bearerFormat: JWT
    sessionAuth:
      description: Token received in response of login request
      type: http
      scheme: bearer
    apiKeyAuth:
      description: |
        JWT token satisfying:
        - encoded by RS256 algorithm
        - signed by your private key (paired with public key you set in your account)
        - `sub` claim set to your user Id as integer
        - `exp` claim set to current Unix timestamp + 10 minutes
        - `jti` claim set to random string unique during 15 minutes

        Example of `header` segment:

            {
              "alg": "RS256",
              "typ": "JWT"
            }

        Example of `payload` segment:

            {
              "sub": 1,
              "exp": 1607590024,
              "jti": "4dee8618-abbe-4dc3-83ba-e984d1396f9f"
            }

        Notes:

        - `jti` value should follow regular expression `/\A[0-9a-z\-_]{32,256}\z/i`
        - same `jti` value cannot be reused in 15 minute timeframe
        - server considers `exp` valid if it fits in time interval `(current Unix; current Unix + 10 minutes)`
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    UserInfo:
      type: object
      properties:
        id:
          type: integer
          example: 8498081
        upvsUri:
          type: string
          example: rc://sk/8314451298_tisici_janko
        name:
          type: string
        serviceAccountPublicKey:
          type: string
        createdAt:
          type: string
          format: date-time
    Invoices:
      type: object
      properties:
        nextId:
          type: string
          format: uuid
          nullable: true
        invoices:
          type: array
          items:
            $ref: '#/components/schemas/Invoice'
    InvoiceFormat:
      type: string
      enum:
        - ubl2.1
        - d16b
    Invoice:
      type: object
      properties:
        id:
          type: string
          format: uuid
        sender:
          type: string
          example: SubjectA
        receiver:
          type: string
          example: SubjectB
        format:
          $ref: '#/components/schemas/InvoiceFormat'
        price:
          type: integer
          example: 100
        supplierIco:
          type: string
          example: '11190993'
        customerIco:
          type: string
          example: '11190993'
        createdAt:
          type: string
          format: date-time
        issueDate:
          type: string
          format: date
        createdBy:
          type: integer
        test:
          type: boolean
          description: True if invoice is just for test purposes
        notificationsSent:
          type: boolean
          description: True if involved parties were notified
    SubstituteIds:
      type: array
      items:
        type: integer
        description: Substitute ID
    SubstitutedOrganizations:
      type: array
      items:
        type: integer
        description: Organization ID (IČO)
    Drafts:
      type: array
      items:
        $ref: '#/components/schemas/Draft'
    Draft:
      type: object
      properties:
        name:
          type: string
        id:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        data:
          type: object
          properties:
            type:
              type: string
              enum:
                - invoice
                - creditNote
            data:
              type: object
              description: Redux state of invoice form
    PatchedDraft:
      type: object
      properties:
        name:
          type: string
        id:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        data:
          type: object
          nullable: true
          properties:
            type:
              type: string
              enum:
                - invoice
                - creditNote
            data:
              type: object
              description: Redux state of invoice form
    Error:
      type: object
      properties:
        error:
          type: string
        detail:
          type: string
      required:
        - error
  parameters:
    Limit:
      name: limit
      in: query
      description: Limit number of entities returned
      schema:
        type: integer
        minimum: 1
    TestInvoice:
      name: test
      in: query
      description: If flag turned on, test invoices are considered as well
      schema:
        type: boolean
    Order:
      name: order
      in: query
      description: |
        Order of returned entities. If not provided order is not guaranteed.
        - `asc` - entitites are returned from the oldest to the newest
        - `desc` - entities are returned from the newest to the oldest
      schema:
        type: string
        enum:
          - asc
          - desc
    StartId:
      name: startId
      in: query
      description: Entity id where service start search
      schema:
        type: string
        format: uuid
    InvoiceFormat:
      name: format
      in: query
      description: Filter invoices by format
      schema:
        type: array
        items:
          $ref: '#/components/schemas/InvoiceFormat'
    AmountFrom:
      name: amountFrom
      in: query
      description: Select invoices with amount not lesser than this value
      schema:
        type: number
    AmountTo:
      name: amountTo
      in: query
      description: Select invoices with amount not greater than this value
      schema:
        type: number
    AmountCurrency:
      name: amountCurrency
      in: query
      description: Filter invoices by amount currency
      schema:
        type: string
    AmountWithoutVatFrom:
      name: amountWithoutVatFrom
      in: query
      description: Select invoices with amount without VAT not lesser than this value
      schema:
        type: number
    AmountWithoutVatTo:
      name: amountWithoutVatTo
      in: query
      description: Select invoices with amount without VAT not greater than this value
      schema:
        type: number
    AmountWithoutVatCurrency:
      name: amountWithoutVatCurrency
      in: query
      description: Filter invoices by amount without VAT currency
      schema:
        type: string
    IssueDateFrom:
      name: issueDateFrom
      in: query
      description: Select invoices with issue date not lesser than this date
      schema:
        type: string
        format: date
        example: '2021-01-15'
    IssueDateTo:
      name: issueDateTo
      in: query
      description: Select invoices with issue date not greater than this date
      schema:
        type: string
        format: date
        example: '2021-01-15'
    UploadTimeFrom:
      name: uploadTimeFrom
      in: query
      description: Select invoices with upload time not lesser than this time
      schema:
        type: string
        format: date-time
        example: '2021-01-02T15:04:05.999+00:00'
    UploadTimeTo:
      name: uploadTimeTo
      in: query
      description: Select invoices with upload date lesser than this time
      schema:
        type: string
        format: date
        example: '2021-01-02T15:04:05.999+00:00'
    CustomerName:
      name: customerName
      in: query
      description: Select invoices with customer name containing this value
      schema:
        type: string
        example: 'Company 1'
    SupplierName:
      name: supplierName
      in: query
      description: Select invoices with supplier name containing this value
      schema:
        type: string
        example: 'Company 1'
    CustomerIco:
      name: customerIco
      in: query
      description: Filter invoices by customer IČO
      schema:
        type: string
        example: '11190993'
    SupplierIco:
      name: supplierIco
      in: query
      description: Filter invoices by supplier IČO
      schema:
        type: string
        example: '11190993'
    DraftId:
      name: draftId
      in: path
      description: Draft ID
      required: true
      schema:
        type: string
        format: uuid
  requestBodies:
    PatchUser:
      content:
        application/json:
          schema:
            type: object
            properties:
              serviceAccountPublicKey:
                type: string
  responses:
    Login:
      description: User is sucessfully logged in.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/UserInfo'
              - type: object
                properties:
                  token:
                    type: string
                    format: uuid
    Logout:
      description: User is successfully logged out.
      content:
        application/json:
          schema:
            type: object
            properties:
              logout:
                type: string
                example: successful
    Error:
      description: There was an error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'