> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maesn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create booking proposal async

## Field support per integration

<AccordionGroup>
  <Accordion title="DATEV Unternehmen Online" icon="https://mintcdn.com/maesn/NQwZPkomn6wLid0x/logo/datev.svg?fit=max&auto=format&n=NQwZPkomn6wLid0x&q=85&s=5589154dcfa064e1d967a067e488896a" width="24" height="24" data-path="logo/datev.svg">
    <Note>
      This endpoints is asynchronous. To check the status of the request, use the `GET asyncTask` endpoint.

      For more info about asynchronous tasks visit the [`Asynchronous Task`](/async-task) section.
    </Note>

    <Note>
      If you're not using the [Interactive Authentication Flow](/authentication#interactive-authentication-flow), make sure the query parameter `companyId` is accurately populated with the appropriate company ID. You can obtain this value by using the `GET Companies` endpoint available under the Authentication section.
    </Note>

    Supported Request Parameters:

    <ResponseField name="bookingProposal" type="string" required>
      <Expandable title="properties">
        <ResponseField name="id" type="string">
          The `id` field represents the unique identifier of the booking proposal.
        </ResponseField>

        <Note>
          The `id` must be a valid UUID; otherwise, it will be ignored.

          This field is only relevant and used `when uploading files` with the booking proposal.
        </Note>

        <ResponseField name="addresses" type="Address[]">
          <Expandable title="properties">
            <ResponseField name="city" type="string">
              The `city` must not exceed 30 characters in length.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="bankAccount" type="bankAccount">
          <Expandable title="properties">
            <ResponseField name="bic" type="string">
              The `bic` field must respect the following pattern: `^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}[A-Z0-9]{0,3}$`.

              Example: `DEUTDEFF`.
            </ResponseField>

            <ResponseField name="code" type="string">
              The `code` must respect the following pattern: `^([1-9]|[0-9]{2,10})$`

              If `code` is provided, then `number` is required.

              Example: `37040044`
            </ResponseField>

            <ResponseField name="iban" type="string">
              The `iban` field must respect the following pattern: `^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$`.

              Example: `DE89370400440532013000`.
            </ResponseField>

            <ResponseField name="number" type="number">
              The `number` field must be 1-10 digits long and includes only numbers.

              If `number` is provided, then `code` is required.

              Example: `532013000`
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="bookingProposalDate" type="string" required>
          For date format details visits the [`Standardized Data`](/standardization) section.
        </ResponseField>

        <ResponseField name="contact" type="Contact">
          <Expandable title="properties">
            <ResponseField name="accountNumber" type="number">
              The `accountNumber` field represents the account number of the contact associated with the booking proposal.

              It must be a valid number. The length must be equal to the account configured length + 1.

              It is the customer account number for `INVOICE` and `CREDIT_NOTE` or the vendor account number for `BILL` and `VENDOR_CREDIT`.
            </ResponseField>

            <ResponseField name="name" type="string">
              The `name` field represents the name of the contact associated with the booking proposal.

              It cannot exceed 50 characters in length.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="currency" type="enum" required>
          The `currency` field supports **ISO 4217** (3-letter codes).
          For details visits the [`Standardized Data`](/standardization) section.
        </ResponseField>

        <ResponseField name="deliveryDate " type="string">
          For date format details visits the [`Standardized Data`](/standardization) section.
        </ResponseField>

        <ResponseField name="discountPaymentDate" type="string">
          For date format details visits the [`Standardized Data`](/standardization) section.

          The `discountPaymentDate` field represents the date until which a discount (`discountAmount` and `discountPercentage` in line items) can be applied to the payment.

          If `discountPaymentDate` is provided, then `discountAmount` and `discountPercentage` are required for each line item.

          Its value must be earlier than the `dueDate` and later than the `bookingProposalDate`.
        </ResponseField>

        <ResponseField name="discountPaymentDate2" type="string">
          For date format details visits the [`Standardized Data`](/standardization) section.

          The `discountPaymentDate2` field represents the date until which a discount (`discountAmount2` and `discountPercentage2` in line items) can be applied to the payment.

          If provided, `discountPaymentDate`, `discountAmount`, `discountPercentage`, `discountAmount2` and `discountPercentage2` are required for each line item.

          Its value must be earlier than the `dueDate` and later than the `bookingProposalDate` and `discountPaymentDate`.
        </ResponseField>

        <ResponseField name="dueDate " type="string">
          For date format details visits the [`Standardized Data`](/standardization) section.

          The `dueDate` field represents the date by which the payment for the booking proposal is expected to be made.

          It is required when discount fields are provided. It must be after the `bookingProposalDate`.
        </ResponseField>

        <ResponseField name="generatorName" type="string" required>
          <Note>
            If not provided, the fallback value `Integration` will be used.
          </Note>
        </ResponseField>

        <ResponseField name="isPaymentOrder" type="boolean">
          The `isPaymentOrder` field determines whether a payment instruction (transfer for bills or direct debit for invoices) should
          be automatically created when the booking proposal is processed.

          It must be `false` if `paymentTermId` is equal to `9`.
        </ResponseField>

        <ResponseField name="ledgerName" type="string" required>
          The `ledgerName` field represents the name of the correct ledger folder where the data will be sent to.

          To get the correct name, you can use the  `GET Accounts` endpoint.
        </ResponseField>

        <Note>
          For `INVOICE` and `CREDIT_NOTE` booking proposals, the `ledgerName` must be of type `ACCOUNT_RECEIVABLE`, and for `BILL` and `VENDOR_CREDIT` booking proposals, it must be of type `ACCOUNT_PAYABLE`.
        </Note>

        <ResponseField name="lineItems" type="BookingLineItem[]" required>
          <Note>
            Depending on the Rechnungsdatenschnittstelle (invoice data interface) settings in DATEV Unternehmen Online, either a single booking proposal or one booking proposal per line item is created. Please check your configuration to ensure the desired behavior.
          </Note>

          <Expandable title="properties">
            <ResponseField name="account" type="Account">
              <Expandable title="properties">
                <ResponseField name="name" type="string">
                  The `name` field specifies the name of the general ledger account linked to the individual line item.

                  It cannot exceed 40 characters in length.
                </ResponseField>

                <ResponseField name="number" type="number">
                  The `number` field specifies the general ledger account linked to the individual line item.

                  It must be a valid number. The length must be equal to the account configured length.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="description" type="string">
              The `description` field provides details about the specific line item in the booking proposal.

              It cannot exceed 60 characters in length.
            </ResponseField>

            <ResponseField name="dimensions" type="Dimension[]">
              Only 2 dimensions are allowed per line item.

              <Expandable title="properties">
                <ResponseField name="name" type="string">
                  The `name` field specifies the name of the dimension associated with the line item.

                  It cannot exceed 36 characters in length. It must follow the pattern : `^([\S][\S ]{0,34}[\S]|[\S]{0,1})$`.

                  Example: `Marketing`.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="discountAmount" type="number">
              The `discountAmount` field represents the fixed amount to be discounted if paid by the `discountPaymentDate`.

              It must be a positive number with up to 8 digits before the decimal point and exactly 2 digits after.

              It cannot exceed the line item's `totalGrossAmount`.
            </ResponseField>

            <ResponseField name="discountAmount2" type="number">
              The `discountAmount2` field represents the fixed amount to be discounted if paid by the `discountPaymentDate2`.

              It must be a positive number with up to 8 digits before the decimal point and exactly 2 digits after.

              It cannot exceed the line item's `totalGrossAmount` and the `discountAmount`.
            </ResponseField>

            <ResponseField name="discountPercentage" type="number">
              The `discountPercentage` field represents the percentage to be discounted if paid by the `discountPaymentDate`.

              It must be a positive number with up to 2 digits before the decimal point and up to 2 digits after.

              It cannot exceed 100%.
            </ResponseField>

            <ResponseField name="discountPercentage2" type="number">
              The `discountPercentage2` field represents the percentage to be discounted if paid by the `discountPaymentDate2`.

              It must be a positive number with up to 2 digits before the decimal point and up to 2 digits after.

              It must be less then the `discountPercentage`.
            </ResponseField>

            <ResponseField name="taxCode " type="string">
              The `taxCode` field represents the BU code associated with the line item.

              It must be max 4 characters long. Only numbers are allowed.
            </ResponseField>

            <ResponseField name="taxRatePercentage " type="number">
              The `taxRatePercentage` field represents the tax rate applied to the line item.

              It must be a positive number.
            </ResponseField>

            <ResponseField name="totalGrossAmount" type="number" required>
              The `totalGrossAmount` field represents the total gross amount for the specific line item.

              It must be a number with up to 10 digits before the decimal point and up to 2 digits after.

              It cannot be zero.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="notes" type="string">
          The `notes` field allows for additional information or comments related to the booking proposal.
          It cannot exceed 120 characters in length.
        </ResponseField>

        <ResponseField name="number" type="string" required>
          The `number` field represents the document number.

          It must match the pattern: `^[a-zA-Z0-9$%&*\+\-/]{0,36}$`.
        </ResponseField>

        <ResponseField name="orderId" type="string">
          The `orderId` field represents the order identifier associated with the booking proposal.

          It must match the pattern: `^[a-zA-Z0-9$%&*+\-./]{1,30}$`.
        </ResponseField>

        <ResponseField name="paidDate" type="string">
          For date format details visits the [`Standardized Data`](/standardization) section.
        </ResponseField>

        <ResponseField name="paymentTermId" type="string">
          The `paymentTermId` field represents the identifier of the payment term associated with the booking proposal.

          It is max 3 characters long. It must includes only numbers.

          If provided, the discount fields are not allowed.
        </ResponseField>

        <ResponseField name="totalGrossAmount" type="number" required>
          The `totalGrossAmount` field represents the total gross amount for the entire booking proposal.

          It cannot be zero and must equal the sum of the `totalGrossAmount` of all line items.

          It must always be a positive amount. The bookingType (INVOICE, BILL, CREDIT\_NOTE, VENDOR\_CREDIT) determines the document type.
        </ResponseField>

        <ResponseField name="vatId" type="string">
          The `vatId` field represents the VAT identification number associated with the booking proposal.

          It must match pattern: `^[0-9a-zA-Z\. _]{1,15}$`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="bookingType" type="BookingType" required>
      Available options: `INVOICE`, `BILL`, `CREDIT_NOTE`, `VENDOR_CREDIT`
    </ResponseField>

    <ResponseField name="files" type="file[]">
      The `files` array can be used to attach files to the booking proposal.

      <Note>
        The name of the uploaded files must include the file extension, for example `invoice.pdf`.
      </Note>
    </ResponseField>

    <ResponseField name="folderManagement" type="FolderManagement">
      The `folderManagement` object defines the three-level folder structure for a booking proposal. If not provided, the default structure will be used.

      <Expandable title="properties">
        <ResponseField name="category" type="string" required>
          The `category` field represents the top-level folder in the folder structure.
        </ResponseField>

        <ResponseField name="folder" type="string" required>
          The `folder` field represents the second-level folder in the folder structure.
        </ResponseField>

        <ResponseField name="register" type="string" required>
          The `register` field represents the third-level folder in the folder structure.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml POST /accounting/bookingProposals/async
openapi: 3.0.0
info:
  title: Maesn unified API
  description: The Maesn unified API description
  version: '1.0'
  contact: {}
servers:
  - url: https://api.maesn.dev
security: []
tags:
  - name: maesn
    description: ''
paths:
  /accounting/bookingProposals/async:
    post:
      tags:
        - accounting
      operationId: createBookingProposalAsync
      parameters:
        - name: X-API-KEY
          description: API key
          in: header
          schema:
            type: string
          required: true
        - name: X-ACCOUNT-KEY
          description: Account key
          in: header
          schema:
            type: string
          required: true
        - name: companyId
          required: false
          in: query
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                bookingProposal:
                  $ref: '#/components/schemas/BookingProposalRequestAsyncDto'
                bookingType:
                  type: string
                  enum:
                    - BILL
                    - CREDIT_NOTE
                    - INVOICE
                    - VENDOR_CREDIT
                files:
                  type: array
                  items:
                    format: binary
                  description: Array of files to upload
                folderManagement:
                  $ref: '#/components/schemas/FolderManagementDto'
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponseDto'
                  - properties:
                      data:
                        $ref: '#/components/schemas/TaskIdResponseDto'
                        type: object
components:
  schemas:
    BookingProposalRequestAsyncDto:
      type: object
      properties:
        id:
          type: string
          example: 23a24449-6v28-446e-bb12-3f428073fc
        'addresses ':
          type: array
          items:
            $ref: '#/components/schemas/AddressBookingProposal'
        bankAccount:
          $ref: '#/components/schemas/BankAccountCommonDto'
        bookingProposalDate:
          type: string
          example: '2025-07-14T00:00:00Z'
        contact:
          $ref: '#/components/schemas/ContactCommonDto'
        currency:
          type: string
          example: EUR
        deliveryDate:
          type: string
          example: '2025-07-26T00:00:00Z'
        discountPaymentDate:
          type: string
          example: '2025-07-16T00:00:00Z'
        discountPaymentDate2:
          type: string
          example: '2025-07-18T00:00:00Z'
        dueDate:
          type: string
          example: '2025-07-24T00:00:00Z'
        generatorName:
          type: string
          example: Maesn GmbH
        journalCode:
          type: string
          example: '60'
        isPaymentOrder:
          type: boolean
          example: 'true'
        ledgerName:
          type: string
          example: Eingangsrechnungen
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/BookingProposalLineItemRequestAsyncDto'
        notes:
          type: string
          example: Bill for maintenance services
        number:
          type: string
          example: '1233330'
        orderId:
          type: string
          example: '3344566'
        paidDate:
          type: string
          example: '2025-07-20T00:00:00Z'
        paymentTermId:
          type: string
          example: '03'
        status:
          type: string
          enum:
            - DRAFT
            - SUBMITTED
            - OPEN
            - PAID
            - PARTIALLY_PAID
            - VOIDED
            - CANCELLED
            - OVERDUE
            - DISPUTED
          example: DRAFT
        totalGrossAmount:
          type: number
          example: 500
        vatId:
          type: string
          example: DE987654321
    FolderManagementDto:
      type: object
      properties:
        category:
          type: string
          example: Accounting
        folder:
          type: string
          example: Invoices
        register:
          type: string
          example: 2025 January
    BaseResponseDto:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/MetaResponse'
        data:
          oneOf:
            - type: object
            - type: array
    TaskIdResponseDto:
      type: object
      properties:
        taskId:
          type: string
          example: 02cc5849-b23c-48fe-8a9b-96f74bfc9571
    AddressBookingProposal:
      type: object
      properties:
        city:
          type: string
          example: city
    BankAccountCommonDto:
      type: object
      properties:
        id:
          type: string
          example: 5a6b7f5dw45c1c-403e-ad56-202fbc312414
        bic:
          type: string
          example: DEUTDEFF
        code:
          type: string
          example: '50010517'
        iban:
          type: string
          example: DE89370400440532013000
        number:
          type: number
          example: 5407324931
    ContactCommonDto:
      type: object
      properties:
        id:
          type: string
          example: eaa28f49-6028-4b6e-bb12-d8f6278073fc
        accountNumber:
          type: number
          example: 70000
        name:
          type: string
          example: John Doe
    BookingProposalLineItemRequestAsyncDto:
      type: object
      properties:
        id:
          type: string
          example: Item-112233
        account:
          $ref: '#/components/schemas/AccountCommonDto'
        description:
          type: string
          example: Item A
        dimensions:
          type: array
          items:
            $ref: '#/components/schemas/DimensionCommonDto'
        discountAmount:
          type: number
          example: 100
        discountAmount2:
          type: number
          example: 50
        discountPercentage:
          type: number
          example: 20
        discountPercentage2:
          type: number
          example: 10
        taxCode:
          type: string
          example: '9'
        taxRatePercentage:
          type: number
          example: 19
        totalGrossAmount:
          type: number
          example: 500
        totalNetAmount:
          type: number
          example: 450
        type:
          type: string
          enum:
            - PRODUCT
            - SERVICE
          example: SERVICE
    MetaResponse:
      type: object
      properties:
        warnings:
          type: array
          items:
            type: string
            example: Field not used by target system
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
    AccountCommonDto:
      type: object
      properties:
        id:
          type: string
          example: db32-4f56-8a9b-1234567890ab
        code:
          type: string
          example: '200'
        name:
          type: string
          example: EXPENSE
        number:
          type: number
          example: 4900
    DimensionCommonDto:
      type: object
      properties:
        id:
          type: string
          example: eaa28f49-6028-4b6e-bb12-d8f6278073fc
        code:
          type: string
          example: CS1
        dimension:
          type: string
          example: CostCenter
        name:
          type: string
          example: Jerde, Greenfelder and Jacobi
    PaginationResponse:
      type: object
      properties:
        total:
          type: number
          example: 125
        perPage:
          type: number
          example: 50
        currentPage:
          type: number
          example: 1
        totalPages:
          type: number
          example: 3

````