openapi: 3.0.0
servers:
  - url: /api/v1
info:
  contact:
    email: info@obono.at
    name: CodeWerkstatt OG
    url: https://obono.at
    x-twitter: obono_at
  description: |
    Provides a RESTful API for interacting with virtual cash registers and creating receipts that are conform with the Registrierkassensicherheitsverordnung (RKSV).

    You may find our [automatically generated clients](./clients) for various programming languages and environments helpful...
  license:
    name: Creative Commons Attribution NonCommercial 4.0 (CC-BY-NC)
    url: https://creativecommons.org/licenses/by-nc/4.0/legalcode
  title: obono RKSV API
  version: 1.4.0.0
  x-apisguru-categories:
    - ecommerce
  x-logo:
    url: https://twitter.com/obono_at/profile_image?size=original
  x-origin:
    - format: openapi
      url: https://app.obono.at/api/docs/api.yml
      version: "3.0"
  x-providerName: obono.at
security:
  - jwt: []
tags:
  - description: resources concerning a "Registrierkasse"
    name: registrierkasse
  - description: resources concerning a "Beleg"
    name: beleg
  - description: authentication and authorization
    name: auth
paths:
  /auth:
    get:
      description: Request a JWT access token using your obono username and password.
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthResult"
          description: The JWT `accessToken` to use for accessing secured resourced as well as the `registrierkassenUuid` of the corresponding "Registrierkasse".
      security:
        - basicAuth: []
      tags:
        - auth
  "/belege/{belegUuid}":
    get:
      description: Retrieves a particular `Beleg` from the "Datenerfassungsprotokoll".
      parameters:
        - description: The `_uuid` of the `Beleg` to fetch.
          in: path
          name: belegUuid
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Beleg"
          description: The requested `Beleg` resource.
        "404":
          description: The requested `Beleg` resource does not exist.
      security: []
      tags:
        - beleg
  "/export/csv/registrierkassen/{registrierkasseUuid}/belege":
    get:
      parameters:
        - description: The `_uuid` of the `Registrierkasse` to export.
          in: path
          name: registrierkasseUuid
          required: true
          schema:
            type: string
        - description: Only return results that were saved before the specified date-time string (i.e., anything that `Date.parse()` can parse).
          in: query
          name: before
          schema:
            type: string
        - description: Only return results that were saved after the specified date-time string (i.e., anything that `Date.parse()` can parse).
          in: query
          name: after
          schema:
            type: string
        - description: Export `Posten` instead of `Belegdaten`.
          in: query
          name: posten
          schema:
            type: boolean
      responses:
        "200":
          description: The exported data of a particular `Registrierkasse` in its CSV representation.
      tags:
        - export
  "/export/dep131/registrierkassen/{registrierkasseUuid}/belege":
    get:
      parameters:
        - description: The `_uuid` of the `Registrierkasse` to export.
          in: path
          name: registrierkasseUuid
          required: true
          schema:
            type: string
        - description: Only return results that were saved before the specified date-time string (i.e., anything that `Date.parse()` can parse).
          in: query
          name: before
          schema:
            type: string
        - description: Only return results that were saved after the specified date-time string (i.e., anything that `Date.parse()` can parse).
          in: query
          name: after
          schema:
            type: string
      responses:
        "200":
          description: The exported data of a particular `Registrierkasse` in its DEP131 / CSV representation.
      tags:
        - export
  "/export/dep7/registrierkassen/{registrierkasseUuid}/belege":
    get:
      parameters:
        - description: The `_uuid` of the `Registrierkasse` to export.
          in: path
          name: registrierkasseUuid
          required: true
          schema:
            type: string
        - description: Only return results that were saved before the specified date-time string (i.e., anything that `Date.parse()` can parse).
          in: query
          name: before
          schema:
            type: string
        - description: Only return results that were saved after the specified date-time string (i.e., anything that `Date.parse()` can parse).
          in: query
          name: after
          schema:
            type: string
      responses:
        "200":
          description: The exported data of a particular `Registrierkasse` in its DEP7 representation.
      tags:
        - export
  "/export/gobd/registrierkassen/{registrierkasseUuid}":
    get:
      parameters:
        - description: The `_uuid` of the `Registrierkasse` to export.
          in: path
          name: registrierkasseUuid
          required: true
          schema:
            type: string
        - description: Only return results that were saved before the specified date-time string (i.e., anything that `Date.parse()` can parse).
          in: query
          name: before
          schema:
            type: string
        - description: Only return results that were saved after the specified date-time string (i.e., anything that `Date.parse()` can parse).
          in: query
          name: after
          schema:
            type: string
      responses:
        "200":
          description: The exported data of a particular `Registrierkasse` in its GoBD representation.
      tags:
        - export
  "/export/html/belege/{belegUuid}":
    get:
      parameters:
        - description: The `_uuid` of a particular `Beleg` to export.
          in: path
          name: belegUuid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: A particular `Beleg` in its HTML representation.
      security: []
      tags:
        - export
  "/export/pdf/belege/{belegUuid}":
    get:
      parameters:
        - description: The `_uuid` of a particular `Beleg` to export.
          in: path
          name: belegUuid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: A particular `Beleg` in its PDF representation.
      security: []
      tags:
        - export
  "/export/qr/belege/{belegUuid}":
    get:
      parameters:
        - description: The `_uuid` of a particular `Beleg` to export.
          in: path
          name: belegUuid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The RKSV QR-Code as PNG file.
      security: []
      tags:
        - export
  "/export/thermal-print/belege/{belegUuid}":
    get:
      parameters:
        - description: The `_uuid` of a particular `Beleg` to export.
          in: path
          name: belegUuid
          required: true
          schema:
            type: string
        - description: Should the RKSV QR code should be rendered?
          in: query
          name: qr
          schema:
            default: true
            type: boolean
        - description: Number of characters per line.
          in: query
          name: width
          schema:
            default: 42
            type: integer
        - description: The thermal printer dialect.
          in: query
          name: dialect
          schema:
            default: escpos
            enum:
              - escpos
              - escposlite
              - star
              - text
            type: string
        - description: The encoding of the binary data.
          in: query
          name: encoding
          schema:
            default: raw
            enum:
              - raw
              - base64
            type: string
      responses:
        "200":
          description: A particular `Beleg` in its ESC/POS or STAR representation.
      security: []
      tags:
        - export
  "/export/xls/registrierkassen/{registrierkasseUuid}/belege":
    get:
      parameters:
        - description: The `_uuid` of the `Registrierkasse` to export.
          in: path
          name: registrierkasseUuid
          required: true
          schema:
            type: string
        - description: Only return results that were saved before the specified date-time string (i.e., anything that `Date.parse()` can parse).
          in: query
          name: before
          schema:
            type: string
        - description: Only return results that were saved after the specified date-time string (i.e., anything that `Date.parse()` can parse).
          in: query
          name: after
          schema:
            type: string
      responses:
        "200":
          description: The exported data of a particular `Registrierkasse` in its Microsoft Excel representation.
      tags:
        - export
  "/registrierkassen/{registrierkasseUuid}":
    get:
      description: Returns information about a particular `Registrierkasse`.
      operationId: getRegistrierkasse
      parameters:
        - description: The `_uuid` of a particular `Registrierkasse` to fetch.
          in: path
          name: registrierkasseUuid
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Registrierkasse"
          description: Information about a particular `Registrierkasse`.
        "404":
          description: This particular `Registrierkasse` does not exist.
      tags:
        - registrierkasse
  "/registrierkassen/{registrierkasseUuid}/abschluss":
    post:
      description: Generates an `Abschlussbeleg`.
      operationId: createAbschluss
      parameters:
        - description: The `_uuid` of the `Registrierkasse` to retrieve the `Beleg` collection.
          in: path
          name: registrierkasseUuid
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Abschlussbelegdaten"
        description: An object that contains all data for a particular `Abschlussbeleg`.
        required: true
      responses:
        "201":
          description: The `Abschlussbeleg` has been created, signed and added to the "Datenerfassungsprotokoll".
          headers:
            Location:
              description: The URL (`_href`) of the newly created `Beleg` resource.
              schema:
                format: url
                type: string
      tags:
        - beleg
  "/registrierkassen/{registrierkasseUuid}/belege":
    get:
      description: Retrieves the `Beleg` collection from the "Datenerfassungsprotokoll".
      operationId: getBelege
      parameters:
        - description: The `_uuid` of the `Registrierkasse` to retrieve the `Beleg` collection.
          in: path
          name: registrierkasseUuid
          required: true
          schema:
            type: string
        - description: Determines the format of the `Beleg` collection.
          in: query
          name: format
          required: true
          schema:
            default: export
            enum:
              - export
              - beleg
              - uuidlist
            type: string
        - description: Determines the sorting order.
          in: query
          name: order
          schema:
            default: asc
            enum:
              - asc
              - desc
            type: string
        - description: Limits the number of returned results.
          in: query
          name: limit
          schema:
            type: integer
        - description: Skips the specified number of results from the result set.
          in: query
          name: offset
          schema:
            default: 0
            type: integer
        - description: Only return results that where saved before the specified date-time string (i.e., anything that `Date.parse()` can parse).
          in: query
          name: before
          schema:
            type: string
        - description: Only return results that where saved after the specified date-time string (i.e., anything that `Date.parse()` can parse).
          in: query
          name: after
          schema:
            type: string
        - description: Only return results that have at least a particular `Belegnummer`.
          in: query
          name: gte
          schema:
            type: integer
        - description: Only return results that have at most a particular `Belegnummer`.
          in: query
          name: lte
          schema:
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Belege"
          description: The `Beleg` collection from the "Datenerfassungsprotokoll".
      tags:
        - beleg
  "/registrierkassen/{registrierkasseUuid}/belege/{belegUuid}":
    get:
      description: Retrieves a particular `Beleg` from the "Datenerfassungsprotokoll".
      operationId: getBeleg
      parameters:
        - description: The `_uuid` of the `Registrierkasse` that contains the requested `Beleg`.
          in: path
          name: registrierkasseUuid
          required: true
          schema:
            type: string
        - description: The `_uuid` of the `Beleg` to fetch.
          in: path
          name: belegUuid
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Beleg"
          description: The requested `Beleg` resource.
        "404":
          description: The requested `Beleg` resource does not exist.
      tags:
        - beleg
    put:
      description: Signs a receipt and stores it in the "Datenerfassungsprotokoll".
      operationId: addBeleg
      parameters:
        - description: The `_uuid` of the `Registrierkasse` to use for signing data.
          in: path
          name: registrierkasseUuid
          required: true
          schema:
            type: string
        - description: The `_uuid` of the `Beleg` to store.
          in: path
          name: belegUuid
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Belegdaten"
        description: An object that contains all data for a particular `Beleg` and is formatted according to RKSV "Signaturformat".
        required: true
      responses:
        "201":
          description: The `Beleg` has been signed and added to the "Datenerfassungsprotokoll".
          headers:
            Location:
              description: The URL (`_href`) of the newly created `Beleg` resource.
              schema:
                format: url
                type: string
        "400":
          description: The provided request payload is invalid i.e. not conform the the JSON schema.
        "403":
          description: Access token is either missing or invalid. Be sure to include the Authorization HTTP header.
        "409":
          description: A `Beleg` with this particular `belegUuid` already exists.
        "415":
          description: The provided request payload is not JSON encoded.
        "429":
          description: Request limit exceeded.
        "500":
          description: The receipt could not be signed either because the HSM delivered invalid data or the request signing request timed out (currently after 10 seconds).
      tags:
        - beleg
  "/registrierkassen/{registrierkasseUuid}/dep":
    get:
      description: Generates a DEP file.
      operationId: getDEP
      parameters:
        - description: The `_uuid` of the `Registrierkasse` to retrieve the DEP file.
          in: path
          name: registrierkasseUuid
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The DEP file.
      tags:
        - registrierkasse
  "/registrierkassen/{registrierkasseUuid}/monatsbelege":
    get:
      description: Returns a list of `Monatsbelege`.
      operationId: getMonatsbelege
      parameters:
        - description: The `_uuid` of the `Registrierkasse`.
          in: path
          name: registrierkasseUuid
          required: true
          schema:
            type: string
        - in: query
          name: year
          schema:
            type: integer
        - in: query
          name: month
          schema:
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/Monatsbeleg"
                type: array
          description: Information about `Monatsbelege`.
      tags:
        - monatsbelege
components:
  schemas:
    Abschlussbelegdaten:
      properties:
        Abschluss-Beginn-Datum-Uhrzeit:
          format: iso8601-date-time
          type: string
        Abschluss-Ende-Datum-Uhrzeit:
          format: iso8601-date-time
          type: string
      required:
        - Abschluss-Beginn-Datum-Uhrzeit
        - Abschluss-Ende-Datum-Uhrzeit
      type: object
    AuthResult:
      properties:
        accessToken:
          type: string
        registrierkasseUuid:
          format: uuid
          type: string
      type: object
    Beleg:
      properties:
        Beleg-Codes:
          items:
            type: string
          type: array
        Beleg-Typen:
          items:
            enum:
              - Belegkreisinitialisierung
              - Kassenbericht
              - Monatsabschluss
              - Startbeleg
              - Storno
              - Systembeleg
              - Training
            type: string
          type: array
        Belegdaten:
          $ref: "#/components/schemas/SignierteBelegdaten"
        JWS:
          description: The signed `Beleg` as a JWS signature token.
          format: jws
          type: string
        QR:
          description: The portion of the `JWS` token to be used for generating QR codes.
          type: string
        QR-Link:
          description: A hyperlink that retrieves the `QR` data.
          format: url
          type: string
        Registrierkasse-UUID:
          description: The `_uuid` of the `Registrierkasse` that has issued this `Beleg`.
          format: uuid
          type: string
        Signaturerstellungseinheit-UUID:
          description: The `_uuid` of the `Signaturerstellungseinheit` that has signed this `Beleg`.
          format: uuid
          type: string
        _href:
          description: URL of the particular `Beleg` instance.
          format: url
          type: string
        _uuid:
          description: Unique ID of the particular `Beleg` instance.
          type: string
      type: object
    Belegdaten:
      description: The `Beleg` to be signed by the "Signaturerstellungseinheit" and stored in the "Datenerfassungsprotokoll".
      properties:
        Externer-Beleg-Belegkreis:
          type: string
        Externer-Beleg-Bezeichnung:
          type: string
        Externer-Beleg-Referenz:
          type: string
        Kunde:
          type: string
        Notizen:
          items:
            type: string
          type: array
        Posten:
          items:
            $ref: "#/components/schemas/Posten"
          type: array
        Rabatte:
          items:
            $ref: "#/components/schemas/Rabatt"
          type: array
        Storno:
          description: Storno?
          type: boolean
        Storno-Beleg-UUID:
          description: The `Beleg-UUID` property of the `Beleg` to be cancelled
          format: uuid
          type: string
        Storno-Text:
          type: string
        Training:
          description: Training?
          type: boolean
        Unternehmen-Adresse1:
          type: string
        Unternehmen-Adresse2:
          type: string
        Unternehmen-Fusszeile:
          type: string
        Unternehmen-ID:
          type: string
        Unternehmen-ID-Typ:
          enum:
            - steuernummer
            - uid
            - gln
          type: string
        Unternehmen-Kopfzeile:
          type: string
        Unternehmen-Name:
          type: string
        Unternehmen-Ort:
          type: string
        Unternehmen-PLZ:
          type: string
        Zahlungen:
          items:
            $ref: "#/components/schemas/Zahlung"
          type: array
      type: object
    Belege:
      allOf:
        - $ref: "#/components/schemas/Belegformat"
        - $ref: "#/components/schemas/Exportformat"
      type: object
    Belegformat:
      properties:
        Belege:
          items:
            $ref: "#/components/schemas/Beleg"
          type: array
      type: object
    Exportformat:
      properties:
        Belege-Gruppe:
          items:
            properties:
              Belege-kompakt:
                items:
                  format: base64
                  type: string
                minItems: 1
                type: array
              Signaturzertifikat:
                format: base64
                type: string
              Zertifizierungsstellen:
                items:
                  format: base64
                  type: string
                minItems: 1
                type: array
            required:
              - Signaturzertifikat
              - Zertifizierungsstellen
              - Belege-kompakt
            type: object
          minItems: 1
          type: array
      type: object
    Monatsbeleg:
      properties:
        Beleg-UUID:
          format: uuid
          type: string
        FON-Geprueft-Datum-Uhrzeit:
          format: iso8601-date-time
          type: string
        FON-Geprueft-Erfolgreich:
          type: boolean
        Jahr:
          type: integer
        Monat:
          type: integer
      type: object
    Posten:
      properties:
        Bezeichnung:
          type: string
        BruttoBetrag:
          description: The amount in cents
          type: integer
        Externer-Beleg-Belegkreis:
          type: string
        Externer-Beleg-Bezeichnung:
          type: string
        Externer-Beleg-Referenz:
          type: string
        Menge:
          type: integer
        NettoBetrag:
          description: The amount in cents
          type: integer
        Satz:
          enum:
            - NORMAL
            - ERMAESSIGT1
            - ERMAESSIGT2
            - BESONDERS
            - "NULL"
          type: string
      required:
        - Bezeichnung
        - Satz
        - Menge
        - NettoBetrag
        - BruttoBetrag
      type: object
    Rabatt:
      properties:
        Betrag-Brutto:
          description: The amount in cents
          type: integer
        Betrag-Netto:
          description: The amount in cents
          type: integer
        Bezeichnung:
          type: string
        Satz:
          enum:
            - NORMAL
            - ERMAESSIGT1
            - ERMAESSIGT2
            - BESONDERS
            - "NULL"
          type: string
      required:
        - Bezeichnung
        - Betrag-Netto
        - Betrag-Brutto
      type: object
    Registrierkasse:
      properties:
        Benutzerschluessel:
          description: The base64 encoded AES 256 key used for encrypting the "Umsatzzaehler".
          format: base64
          type: string
        Kassen-ID:
          description: The (RKSV) "Kassenidentifikationsnummer" of this particular `Registrierkasse`.
          type: string
        Signaturerstellungseinheit-UUID:
          description: The `_uuid` of the paired "Signaturerstellungseinheit".
          format: uuid
          type: string
        _href:
          description: URL of the particular `Registrierkasse` instance.
          format: url
          type: string
        _uuid:
          description: Unique ID of the particular `Registrierkasse` instance.
          type: string
      type: object
    SignierteBelegdaten:
      description: The complete `Beleg` that has been signed by the "Signaturerstellungseinheit" and stored in the "Datenerfassungsprotokoll".
      properties:
        Beleg-Datum-Uhrzeit:
          type: string
        Belegnummer:
          type: string
        Betrag-Brutto:
          type: integer
        Betrag-Netto:
          type: integer
        Betrag-Satz-Besonders-Brutto:
          description: The total amount in cents
          type: integer
        Betrag-Satz-Besonders-Netto:
          description: The total amount in cents
          type: integer
        Betrag-Satz-Ermaessigt-1-Brutto:
          description: The total amount in cents
          type: integer
        Betrag-Satz-Ermaessigt-1-Netto:
          description: The total amount in cents
          type: integer
        Betrag-Satz-Ermaessigt-2-Brutto:
          description: The total amount in cents
          type: integer
        Betrag-Satz-Ermaessigt-2-Netto:
          description: The total amount in cents
          type: integer
        Betrag-Satz-Normal-Brutto:
          description: The total amount in cents
          type: integer
        Betrag-Satz-Normal-Netto:
          description: The total amount in cents
          type: integer
        Betrag-Satz-Null-Brutto:
          description: The total amount in cents
          type: integer
        Betrag-Satz-Null-Netto:
          description: The total amount in cents
          type: integer
        Externer-Beleg-Belegkreis:
          type: string
        Externer-Beleg-Bezeichnung:
          type: string
        Externer-Beleg-Referenz:
          type: string
        Kassen-ID:
          type: string
        Kunde:
          type: string
        Notizen:
          items:
            type: string
          type: array
        Posten:
          items:
            $ref: "#/components/schemas/Posten"
          type: array
        Rabatte:
          items:
            $ref: "#/components/schemas/Rabatt"
          type: array
        Storno:
          description: Storno?
          type: boolean
        Storno-Beleg-UUID:
          description: The `Beleg-UUID` property of the `Beleg` to be cancelled
          format: uuid
          type: string
        Storno-Text:
          type: string
        Training:
          description: Training?
          type: boolean
        Unternehmen-Adresse1:
          type: string
        Unternehmen-Adresse2:
          type: string
        Unternehmen-Fusszeile:
          type: string
        Unternehmen-ID:
          type: string
        Unternehmen-ID-Typ:
          enum:
            - steuernummer
            - uid
            - gln
          type: string
        Unternehmen-Kopfzeile:
          type: string
        Unternehmen-Name:
          type: string
        Unternehmen-Ort:
          type: string
        Unternehmen-PLZ:
          type: string
        Zahlungen:
          items:
            $ref: "#/components/schemas/Zahlung"
          type: array
        Zertifikat-Seriennummer:
          type: string
      type: object
    Zahlung:
      properties:
        Betrag:
          description: The amount in cents
          type: integer
        Bezeichnung:
          type: string
        Referenz:
          type: string
      required:
        - Bezeichnung
        - Betrag
      type: object
  securitySchemes:
    basicAuth:
      description: HTTP Basic Authentication.
      scheme: basic
      type: http
    jwt:
      description: A JSON Web Token (JWT) used for access control and authorization.
      in: header
      name: Authorization
      type: apiKey
