AEB Billing API

openapi: 3.2.0
info:
  title: Logistics Cost Management HTTP Billing API
  description: Thank you for using our HTTP API documentation.
  version: '2.0'
servers:
- url: https://rz3.aeb.de/demo1billing/rest
security:
- SWAGGER_AUTH_KEY: []
- BASIC_AUTH: []
tags:
- name: Billing
  description: API for the billing of services
paths:
  /BillingBFBean/acknowledgeChangedSettlements:
    post:
      tags:
      - Billing
      summary: acknowledgeChangedSettlements
      description: Acknowledge that changed settlements were processed and should no longer be returned by getChangedSettlements.
      operationId: acknowledgeChangedSettlements
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BAcknowledgeChangedSettlementsRequestDTO'
          application/xml:
            schema:
              $ref: '#/components/schemas/BAcknowledgeChangedSettlementsRequestDTO'
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BAcknowledgeChangedSettlementsResponseDTO'
            application/xml:
              schema:
                $ref: '#/components/schemas/BAcknowledgeChangedSettlementsResponseDTO'
      security:
      - BASIC_AUTH: []
  /BillingBFBean/cancelServiceItems:
    post:
      tags:
      - Billing
      summary: cancelServiceItems
      description: Cancel the service items in the Billing engine.<br> Cancel a service item will try to logically remove the service item with all of its settelement items, if this is possible.<br> In some cases the cancellation of service items is not (or no longer) possible and will lead to errors.<br> E.g. the service item can not be found, or some of the settlement items of the service item can not or no longer be logically removed.<br> The processing of all items will be done in one transaction, so in case of any error, nothing will be persisted. Therefore check the errorFlag and message arrays in the response for any error to detect this case.<br>
      operationId: cancelServiceItems
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BReverseServiceItemsRequestDTO'
          application/xml:
            schema:
              $ref: '#/components/schemas/BReverseServiceItemsRequestDTO'
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BReverseServiceItemsResponseDTO'
            application/xml:
              schema:
                $ref: '#/components/schemas/BReverseServiceItemsResponseDTO'
      security:
      - BASIC_AUTH: []
  /BillingBFBean/createServiceItems:
    post:
      tags:
      - Billing
      summary: createServiceItems
      description: Creates one or more service items. For each BServiceItemDTO included in the BCreateServiceItemsRequestDTO one service item is created. Starts pricing if boolean calculatePriceImmediately in BCreateServiceItemParmsDTO is true and returns the calculated prices. Use this method if you want to invoice and or audit the service items.
      operationId: createServiceItems
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BCreateServiceItemsRequestDTO'
            examples:
              Complete data:
                description: Complete data
                value:
                  clientSystemId: APITEST
                  clientIdentCode: APITEST
                  userName: user
                  resultLanguageIsoCodes:
                  - de
                  - en
                  parms:
                    calculatePriceImmediately: false
                    createSettlementsImmediately: false
                    returnTraceInfo: true
                    rollbackOnErrorMessage: true
                  items:
                  - itemId: 25-11-2022
                    scenarioIdentCode: A01
                    serviceIdentCode: TNTDE_EXP12
                    referenceNumber: 25-11-2022
                    orderNumber: 25-11-2022
                    serviceProvider:
                      companyNumber: TNT
                      name: TNT Express Worldwide
                      street: Heilbronner Staße 110
                      postcode: '70334'
                      city: Stuttgart
                      countryISOCode: DE
                    orderer:
                      companyNumber: '001'
                      name: AEB SE
                      street: Sigmaringer Straße 109
                      postcode: '70567'
                      city: Stuttgart
                      countryISOCode: DE
                    payer:
                      companyNumber: '001'
                      name: AEB SE
                      street: Sigmaringer Straße 109
                      postcode: '70567'
                      city: Stuttgart
                      countryISOCode: DE
                    beneficiary:
                      companyNumber: '001'
                      name: AEB SE
                      street: Sigmaringer Straße 109
                      postcode: '70567'
                      city: Stuttgart
                      countryISOCode: DE
                    referenceDate:
                      dateInTimezone: '2022-11-25 12:00:00'
                      timezone: Europe/Berlin
                    pricingDate:
                      dateInTimezone: '2022-11-25 12:00:00'
                      timezone: Europe/Berlin
                    chargeDate:
                      dateInTimezone: '2022-11-25 12:00:00'
                      timezone: Europe/Berlin
                    serviceDate:
                      dateInTimezone: '2022-11-25 12:00:00'
                      timezone: Europe/Berlin
                    orderDate:
                      dateInTimezone: '2022-11-25 12:00:00'
                      timezone: Europe/Berlin
                    quantity:
                      value: '1'
                      unit: St
                    description: Shipment
                    extendedData:
                      fields:
                      - name: carrierDefinitionIdentCode
                        type: string
                        value: TNT
                      - name: numberOfInvoices
                        type: decimal
                        value: '1'
                      - name: isDangerousGoods
                        type: boolean
                        value: 'false'
                      - name: referenceNumber
                        type: string
                        value: referenceNumber
                      - name: incotermIdentCode
                        type: string
                        value: incoterm
                      - name: numberOfItems
                        type: decimal
                        value: '2'
                      - name: palletPlaces
                        type: decimal
                        value: '1.000'
                      - name: numberOfPackages
                        type: decimal
                        value: '2'
                      - name: isDocumentShipment
                        type: boolean
                        value: 'false'
                      - name: numberOfDeliveryNotes
                        type: decimal
                        value: '1'
                      subrecords:
                      - name: volume
                        record:
                          fields:
                          - name: unit
                            type: string
                            value: ccm
                          - name: value
                            type: decimal
                            value: '4500.000'
                      - name: grossWeight
                        record:
                          fields:
                          - name: unit
                            type: string
                            value: kg
                          - name: value
                            type: decimal
                            value: '1.900'
                      - name: transportStart
                        record:
                          subrecords:
                          - name: postalAddress
                            record:
                              fields:
                              - name: countryIsoCode
                                type: string
                                value: DE
                              - name: postcode
                                type: string
                                value: '70597'
                      - name: transportEnd
                        record:
                          subrecords:
                          - name: postalAddress
                            record:
                              fields:
                              - name: countryIsoCode
                                type: string
                                value: DE
                              - name: postcode
                                type: string
                                value: '94405'
                      - name: packages
                        record:
                          fields:
                          - name: dangerousGoodsHandlingCode
                            type: string
                            value: NONE
                          - name: packageReferenceNumber
                            type: string
                            value: package1
                          - name: numberOfPackages
                            type: decimal
                            value: '1'
                          subrecords:
                          - name: volume
                            record:
                              fields:
                              - name: unit
                                type: string
                                value: ccm
                              - name: value
                                type: decimal
                                value: '1500.000'
                          - name: grossWeight
                            record:
                              fields:
                              - name: unit
                                type: string
                                value: kg
                              - name: value
                                type: decimal
                                value: '0.600'
                          - name: dimensions
                            record:
                              fields:
                              - name: length
                                type: decimal
                                value: '30.000'
                              - name: width
                                type: decimal
                                value: '10.000'
                              - name: quantityUnit
                                type: string
                                value: cm
                              - name: height
                                type: decimal
                                value: '5.000'
                      - name: packages
                        record:
                          fields:
                          - name: dangerousGoodsHandlingCode
                            type: string
                            value: NONE
                          - name: packageTypeIdentCode
                            type: string
                            value: packageType
                          - name: packageReferenceNumber
                            type: string
                            value: package2
                          - name: numberOfPackages
                            type: decimal
                            value: '1'
                          subrecords:
                          - name: volume
                            record:
                              fields:
                              - name: unit
                                type: string
                                value: ccm
                              - name: value
                                type: decimal
                                value: '3000.000'
                          - name: grossWeight
                            record:
                              fields:
                              - name: unit
                                type: string
                                value: kg
                              - name: value
                                type: decimal
                                value: '1.300'
                          - name: dimensions
                            record:
                              fields:
                              - name: length
                                type: decimal
                                value: '30.000'
                              - name: width
                                type: decimal
                                value: '20.000'
                              - name: quantityUnit
                                type: string
                                value: cm
                              - name: height
                                type: decimal
                                value: '5.000'
          application/xml:
            schema:
              $ref: '#/components/schemas/BCreateServiceItemsRequestDTO'
            examples:
              Complete data:
                description: Complete data
                value:
                  clientSystemId: APITEST
                  clientIdentCode: APITEST
                  userName: user
                  resultLanguageIsoCodes:
                  - de
                  - en
                  parms:
                    calculatePriceImmediately: false
                    createSettlementsImmediately: false
                    returnTraceInfo: true
                    rollbackOnErrorMessage: true
                  items:
                  - itemId: 25-11-2022
                    scenarioIdentCode: A01
                    serviceIdentCode: TNTDE_EXP12
                    referenceNumber: 25-11-2022
                    orderNumber: 25-11-2022
                    serviceProvider:
                      companyNumber: TNT
                      name: TNT Express Worldwide
                      street: Heilbronner Staße 110
                      postcode: '70334'
                      city: Stuttgart
                      countryISOCode: DE
                    orderer:
                      companyNumber: '001'
                      name: AEB SE
                      street: Sigmaringer Straße 109
                      postcode: '70567'
                      city: Stuttgart
                      countryISOCode: DE
                    payer:
                      companyNumber: '001'
                      name: AEB SE
                      street: Sigmaringer Straße 109
                      postcode: '70567'
                      city: Stuttgart
                      countryISOCode: DE
                    beneficiary:
                      companyNumber: '001'
                      name: AEB SE
                      street: Sigmaringer Straße 109
                      postcode: '70567'
                      city: Stuttgart
                      countryISOCode: DE
                    referenceDate:
                      dateInTimezone: '2022-11-25 12:00:00'
                      timezone: Europe/Berlin
                    pricingDate:
                      dateInTimezone: '2022-11-25 12:00:00'
                      timezone: Europe/Berlin
                    chargeDate:
                      dateInTimezone: '2022-11-25 12:00:00'
                      timezone: Europe/Berlin
                    serviceDate:
                      dateInTimezone: '2022-11-25 12:00:00'
                      timezone: Europe/Berlin
                    orderDate:
                      dateInTimezone: '2022-11-25 12:00:00'
                      timezone: Europe/Berlin
                    quantity:
                      value: '1'
                      unit: St
                    description: Shipment
                    extendedData:
                      fields:
                      - name: carrierDefinitionIdentCode
                        type: string
                        value: TNT
                      - name: numberOfInvoices
                        type: decimal
                        value: '1'
                      - name: isDangerousGoods
                        type: boolean
                        value: 'false'
                      - name: referenceNumber
                        type: string
                        value: referenceNumber
                      - name: incotermIdentCode
                        type: string
                        value: incoterm
                      - name: numberOfItems
                        type: decimal
                        value: '2'
                      - name: palletPlaces
                        type: decimal
                        value: '1.000'
                      - name: numberOfPackages
                        type: decimal
                        value: '2'
                      - name: isDocumentShipment
                        type: boolean
                        value: 'false'
                      - name: numberOfDeliveryNotes
                        type: decimal
                        value: '1'
                      subrecords:
                      - name: volume
                        record:
                          fields:
                          - name: unit
                            type: string
                            value: ccm
                          - name: value
                            type: decimal
                            value: '4500.000'
                      - name: grossWeight
                        record:
                          fields:
                          - name: unit
                            type: string
                            value: kg
                          - name: value
                            type: decimal
                            value: '1.900'
                      - name: transportStart
                        record:
                          subrecords:
                          - name: postalAddress
                            record:
                              fields:
                              - name: countryIsoCode
                                type: string
                                value: DE
                              - name: postcode
                                type: string
                                value: '70597'
                      - name: transportEnd
                        record:
                          subrecords:
                          - name: postalAddress
                            record:
                              fields:
                              - name: countryIsoCode
                                type: string
                                value: DE
                              - name: postcode
                                type: string
                                value: '94405'
                      - name: packages
                        record:
                          fields:
                          - name: dangerousGoodsHandlingCode
                            type: string
                            value: NONE
                          - name: packageReferenceNumber
                            type: string
                            value: package1
                          - name: numberOfPackages
                            type: decimal
                            value: '1'
                          subrecords:
                          - name: volume
                            record:
                              fields:
                              - name: unit
                                type: string
                                value: ccm
                              - name: value
                                type: decimal
                                value: '1500.000'
                          - name: grossWeight
                            record:
                              fields:
                              - name: unit
                                type: string
                                value: kg
                              - name: value
                                type: decimal
                                value: '0.600'
                          - name: dimensions
                            record:
                              fields:
                              - name: length
                                type: decimal
                                value: '30.000'
                              - name: width
                                type: decimal
                                value: '10.000'
                              - name: quantityUnit
                                type: string
                                value: cm
                              - name: height
                                type: decimal
                                value: '5.000'
                      - name: packages
                        record:
                          fields:
                          - name: dangerousGoodsHandlingCode
                            type: string
                            value: NONE
                          - name: packageTypeIdentCode
                            type: string
                            value: packageType
                          - name: packageReferenceNumber
                            type: string
                            value: package2
                          - name: numberOfPackages
                            type: decimal
                            value: '1'
                          subrecords:
                          - name: volume
                            record:
                              fields:
                              - name: unit
                                type: string
                                value: ccm
                              - name: value
                                type: decimal
                                value: '3000.000'
                          - name: grossWeight
                            record:
                              fields:
                              - name: unit
                                type: string
                                value: kg
                              - name: value
                                type: decimal
                                value: '1.300'
                          - name: dimensions
                            record:
                              fields:
                              - name: length
                                type: decimal
                                value: '30.000'
                              - name: width
                                type: decimal
                                value: '20.000'
                              - name: quantityUnit
                                type: string
                                value: cm
                              - name: height
                                type: decimal
                                value: '5.000'
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BCreateServiceItemsResponseDTO'
            application/xml:
              schema:
                $ref: '#/components/schemas/BCreateServiceItemsResponseDTO'
      security:
      - BASIC_AUTH: []
  /BillingBFBean/getBillingScenarios:
    post:
      tags:
      - Billing
      summary: getBillingScenarios
      description: Returns all billing scenarios for the given client
      operationId: getBillingScenarios
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BGetBillingScenariosRequestDTO'
          application/xml:
            schema:
              $ref: '#/components/schemas/BGetBillingScenariosRequestDTO'
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BGetBillingScenariosResponseDTO'
            application/xml:
              schema:
                $ref: '#/components/schemas/BGetBillingScenariosResponseDTO'
      security:
      - BASIC_AUTH: []
  /BillingBFBean/getBillingServices:
    post:
      tags:
      - Billing
      summary: getBillingServices
      description: Returns all billing services for the given client and billing scenario as optional parameter.
      operationId: getBillingServices
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BGetBillingServicesRequestDTO'
          application/xml:
            schema:
              $ref: '#/components/schemas/BGetBillingServicesRequestDTO'
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BGetBillingServicesResponseDTO'
            application/xml:
              schema:
                $ref: '#/components/schemas/BGetBillingServicesResponseDTO'
      security:
      - BASIC_AUTH: []
  /BillingBFBean/getChangedSettlements:
    post:
      tags:
      - Billing
      summary: getChangedSettlements
      description: <p>Returns all changed settlements.</p> <p> This method should be used together with acknowledgeChangedSettlements. </p> See also BGetChangedSettlementsResponseDTO#syncId
      operationId: getChangedSettlements
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BGetChangedSettlementsRequestDTO'
          application/xml:
            schema:
              $ref: '#/components/schemas/BGetChangedSettlementsRequestDTO'
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BGetChangedSettlementsResponseDTO'
            application/xml:
              schema:
                $ref: '#/components/schemas/BGetChangedSettlementsResponseDTO'
      security:
      - BASIC_AUTH: []
  /BillingBFBean/getServiceItems:
    post:
      tags:
      - Billing
      summary: getServiceItems
      description: Returns all service items for the given client.
      operationId: getServiceItems
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BGetServiceItemsRequestDTO'
          application/xml:
            schema:
              $ref: '#/components/schemas/BGetServiceItemsRequestDTO'
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BGetServiceItemsResponseDTO'
            application/xml:
              schema:
                $ref: '#/components/schemas/BGetServiceItemsResponseDTO'
      security:
      - BASIC_AUTH: []
  /BillingBFBean/offsetServiceItems:
    post:
      tags:
      - Billing
      summary: offsetServiceItems
      description: Offset the service items in the Billing engine.<br> Offsetting a service item will offset all relevant settlement items of this service item, by creating exact copies of the relevant settlement items with reversed sign.<br> Depending on customizing, some settlement items will not take part in offsetting the service item and some settlement items will prevent any offsetting at all, which leads to an error.<br> The processing of all items will be done in one transaction, so in case of any error, nothing will be persisted. Therefore check the errorFlag and error message arrays in the response for any error to detect this case.<br>
      operationId: offsetServiceItems
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BReverseServiceItemsRequestDTO'
          application/xml:
            schema:
              $ref: '#/components/schemas/BReverseServiceItemsRequestDTO'
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BReverseServiceItemsResponseDTO'
            application/xml:
              schema:
                $ref: '#/components/schemas/BReverseServiceItemsResponseDTO'
      security:
      - BASIC_AUTH: []
  /BillingBFBean/setServiceMasterFileData:
    post:
      tags:
      - Billing
      summary: setServiceMasterFileData
      description: Create or update multiple Services in the Billing engine.<br> Create or update multiple services in the master file data of the engine. Because of performance and transactional issues it is recommended to transfer about 100 services within one synchronous call. All transfered services will be either created or updated. The identCode and scenarioIdentCode (these are key values) of the service will be checked before processing. In case of any unfilled key value, nothing will be done. In case of other problems for a single service e.g locking or invalid identCode values the processing is usually continued with the next service, skipping, the problematic service. This means the record will be skipped completely and processing will continue with the next service. Anyway such errors will set the hasErrors or hasWarnings to true. To analyse situations check the response for details. Possible messageIdentCodes are documented in AbstractResponseDTO, BSetServiceMasterFileDataResponseDTO, BServiceMFResultDTO, AbstractResponseItemDTO and BServiceMFResultDTO
      operationId: setServiceMasterFileData
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BSetServiceMasterFileDataRequestDTO'
          application/xml:
            schema:
              $ref: '#/components/schemas/BSetServiceMasterFileDataRequestDTO'
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BSetServiceMasterFileDataResponseDTO'
            application/xml:
              schema:
                $ref: '#/components/schemas/BSetServiceMasterFileDataResponseDTO'
      security:
      - BASIC_AUTH: []
  /BillingBFBean/simulateCreateServiceItems:
    post:
      tags:
      - Billing
      summary: simulateCreateServiceItems
      description: This method does the same as createServiceItems, but does not store the results in the database.<br> So this method can e.g. be used to precalculate prices for potential service items or just for testing purposes.
      operationId: simulateCreateServiceItems
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BCreateServiceItemsRequestDTO'
          application/xml:
            schema:
              $ref: '#/components/schemas/BCreateServiceItemsRequestDTO'
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BCreateServiceItemsResponseDTO'
            application/xml:
              schema:
                $ref: '#/components/schemas/BCreateServiceItemsResponseDTO'
      security:
      - BASIC_AUTH: []
components:
  schemas:
    BAccountingItemResultDTO:
      type: object
      properties:
        costCenter:
          type: string
          description: Cost center of this item. <br> <p>length=50</p>
        vatInfo:
          $ref: '#/components/schemas/BVatInfoResultDTO'
        settlementNetPrice:
          $ref: '#/components/schemas/BAmountOfMoneyDTO'
        settlementVatPrice:
          $ref: '#/components/schemas/BAmountOfMoneyDTO'
      description: <p>Accounting item of a settlement.</p> <p>Accumulation of settlement items grouped by cost center and VAT.</p>
    BCreateServiceItemsResponseDTO:
      type: object
      proper

# --- truncated at 32 KB (92 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/aeb/refs/heads/main/openapi/aeb-billing-api-openapi.yml