{
  "openapi": "3.0.1",
  "info": {
    "title": "Zentraler eRechnungseingang Niedersachsen API",
    "description": "Webschnittstelle des Zentralen eRechnungseingangs Niedersachsen",
    "contact": {
      "name": "Service Zentraler eRechnungseingang Niedersachsen",
      "url": "https://rechnung.niedersachsen.de",
      "email": "service-erechnung@niedersachsen.de"
    },
    "version": "3.68.0+1720f2c541b48cce26a0afe2bab14ccec3cf6aa0"
  },
  "servers": [
    {
      "url": "https://api.erechnung.niedersachsen.de",
      "description": "Basis-URL der Schnittstelle"
    }
  ],
  "paths": {
    "/api/attachment/{attachmentId}": {
      "get": {
        "tags": [
          "Attachment"
        ],
        "summary": "Gets an attachment by id. Attachment file name is passed as header »Content-Disposition«.",
        "parameters": [
          {
            "name": "attachmentId",
            "in": "path",
            "description": "The attachment id. Must be a valid GUID.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "401": {
            "description": "If authentication is missing.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "If authentication fails or permissions aren't met.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "description": "Method Not Allowed",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "Server Error",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "200": {
            "description": "The attachment data.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "204": {
            "description": "If no attachment was found for the given id.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "406": {
            "description": "If GUID is malformed.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "security": [
          {
            "Bearer": [ ]
          }
        ]
      }
    },
    "/api/accesstoken/create": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Creates tokens for accessing the API. Credentials can be sent either in JSON format or in OAuth2 ROPC Form-URL-Encoded both using a POST request.\r\nReturns an OAuth 2.0 access token for use with the API endpoints and a refresh token for refreshing the access token.",
        "requestBody": {
          "description": "The authentication credentials.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuthenticationCredentials"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/AuthenticationCredentials"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/AuthenticationCredentials"
              }
            }
          }
        },
        "responses": {
          "405": {
            "description": "Method Not Allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "200": {
            "description": "The OAuth 2.0 tokens.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationData"
                }
              }
            }
          },
          "400": {
            "description": "If credentials are missing or invalid, or no user was found.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/accesstoken/refresh": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Refreshes an access token by sending a refresh token by POST request. The refresh token can be sent either in JSON format or in OAuth2 ROPC Form-URL-Encoded.",
        "requestBody": {
          "description": "The authentication refresh.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuthenticationRefresh"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/AuthenticationRefresh"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/AuthenticationRefresh"
              }
            }
          }
        },
        "responses": {
          "405": {
            "description": "Method Not Allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "200": {
            "description": "The OAuth 2.0 tokens.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthenticationData"
                }
              }
            }
          },
          "400": {
            "description": "If refresh token is missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/invoice/new": {
      "get": {
        "tags": [
          "Invoice"
        ],
        "summary": "Gets a list of all invoices with the status »new« for an authorized users leitweg id.\r\nAttachments are passed as an array of guids which also include the original invoice as the only xml file.",
        "responses": {
          "401": {
            "description": "If authentication is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "If authentication fails or permissions aren't met.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "description": "Method Not Allowed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "200": {
            "description": "The invoice data.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/InvoiceApiView"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "Bearer": [ ]
          }
        ]
      }
    },
    "/api/invoice/{invoiceId}/xml": {
      "get": {
        "tags": [
          "Invoice"
        ],
        "summary": "Gets the XRechnung xml of an invoice.",
        "parameters": [
          {
            "name": "invoiceId",
            "in": "path",
            "description": "The invoice id. Must be a valid GUID.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "401": {
            "description": "If authentication is missing.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "If authentication fails or permissions aren't met.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "description": "Method Not Allowed",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "Server Error",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "200": {
            "description": "The invoice xml."
          },
          "204": {
            "description": "If no invoice was found for the given id.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "406": {
            "description": "If GUID is malformed.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "security": [
          {
            "Bearer": [ ]
          }
        ]
      }
    },
    "/api/invoice/{invoiceId}/validationreport": {
      "get": {
        "tags": [
          "Invoice"
        ],
        "summary": "Gets the validation report of an invoice generated by the KoSIT validation tool.",
        "parameters": [
          {
            "name": "invoiceId",
            "in": "path",
            "description": "The invoice id. Must be a valid GUID.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "401": {
            "description": "If authentication is missing.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "If authentication fails or permissions aren't met.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "description": "Method Not Allowed",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "Server Error",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "200": {
            "description": "The validation report xml."
          },
          "204": {
            "description": "If no invoice was found for the given id.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "406": {
            "description": "If GUID is malformed.",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "security": [
          {
            "Bearer": [ ]
          }
        ]
      }
    },
    "/api/invoice/{invoiceId}/downloaded": {
      "patch": {
        "tags": [
          "Invoice"
        ],
        "summary": "Sets the status of an invoice as »downloaded«. This invoice will not show up again in the list of new invoices.",
        "parameters": [
          {
            "name": "invoiceId",
            "in": "path",
            "description": "The invoice id. Must be an valid GUID.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "401": {
            "description": "If authentication is missing.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "string"
                }
              },
              "text/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "If authentication fails or permissions aren't met.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "string"
                }
              },
              "text/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "405": {
            "description": "Method Not Allowed",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "string"
                }
              },
              "text/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "Server Error",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "string"
                }
              },
              "text/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "200": {
            "description": "If status was set successfully."
          },
          "204": {
            "description": "If no invoice was found for the submitted id."
          },
          "406": {
            "description": "If GUID is malformed.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "string"
                }
              },
              "text/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "security": [
          {
            "Bearer": [ ]
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "AuthenticationCredentials": {
        "type": "object",
        "properties": {
          "userName": {
            "type": "string",
            "nullable": true
          },
          "password": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "AuthenticationData": {
        "type": "object",
        "properties": {
          "accessToken": {
            "type": "string",
            "nullable": true
          },
          "refreshToken": {
            "type": "string",
            "nullable": true
          },
          "expiresIn": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false
      },
      "AuthenticationRefresh": {
        "type": "object",
        "properties": {
          "refreshToken": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "InvoiceApiData": {
        "type": "object",
        "properties": {
          "invoiceId": {
            "type": "string",
            "format": "uuid"
          },
          "invoiceReceivedDate": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "recipientLeitwegId": {
            "type": "string",
            "nullable": true
          },
          "senderName": {
            "type": "string",
            "nullable": true
          },
          "senderEmailAddress": {
            "type": "string",
            "nullable": true
          },
          "senderInvoiceNumber": {
            "type": "string",
            "nullable": true
          },
          "invoiceScheme": {
            "type": "integer",
            "format": "int32"
          },
          "invoiceTypeCode": {
            "type": "integer",
            "format": "int32"
          },
          "invoiceXml": {
            "type": "string",
            "nullable": true
          },
          "invoiceValidationReportXml": {
            "type": "string",
            "nullable": true
          },
          "invoiceAttachments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InvoiceAttachment"
            },
            "nullable": true
          },
          "invoiceApiStatusId": {
            "type": "string",
            "format": "uuid"
          },
          "apiStatus": {
            "$ref": "#/components/schemas/InvoiceApiStatus"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          }
        },
        "additionalProperties": false
      },
      "InvoiceApiStatus": {
        "type": "object",
        "properties": {
          "statusText": {
            "type": "string",
            "nullable": true
          },
          "intValue": {
            "type": "integer",
            "format": "int32"
          },
          "invoices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InvoiceApiData"
            },
            "nullable": true
          },
          "id": {
            "type": "string",
            "format": "uuid"
          }
        },
        "additionalProperties": false
      },
      "InvoiceApiView": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "received": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "sender": {
            "$ref": "#/components/schemas/InvoiceSender"
          },
          "senderInvoiceNumber": {
            "type": "string",
            "nullable": true
          },
          "scheme": {
            "type": "integer",
            "format": "int32"
          },
          "typeCode": {
            "type": "integer",
            "format": "int32"
          },
          "attachments": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "nullable": true
          },
          "status": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false
      },
      "InvoiceAttachment": {
        "type": "object",
        "properties": {
          "invoiceId": {
            "type": "string",
            "format": "uuid"
          },
          "attachmentId": {
            "type": "string",
            "format": "uuid"
          },
          "invoice": {
            "$ref": "#/components/schemas/InvoiceApiData"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          }
        },
        "additionalProperties": false
      },
      "InvoiceSender": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true
          },
          "emailAddress": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "Bearer": {
        "type": "http",
        "description": "JWT Authorization header using the Bearer scheme. Paste your API token **_only_**.",
        "scheme": "bearer"
      }
    }
  }
}